Digital Assets API Reference Guide

Request Parameters

Enumerations

GET /v1/accounts/{accountId}/summary

Sample Request

const summaryResponse = await fetch(
  `${baseUrl}/v1/accounts/${accountId}/summary?includeObac=true`,
  { headers: { 'Authorization': `Bearer ${access_token}` } }
);
const summaryItems = await summaryResponse.json();
const accountIds = summaryItems.filter(i => i.type === 'Account').map(i => i.id);
const walletIds = summaryItems.filter(i => i.type === 'Wallet').map(i => i.id);

Response Template

[
  { "id": "account-1", "name": "Sub Account", "type": "Account", "lockedOperations": ["Updating"] },
  { "id": "wallet-1", "name": "Wallet A", "type": "Wallet", "walletDetails": { "address": "0x..." } }
]

TypeScript Interface

interface AccountSummary {
  id: string;
  name: string;
  type: 'Account' | 'Wallet';
  externalId?: string;
  lockedOperations?: string[];
  walletDetails?: { address: string };
  accessControl?: { isShared: boolean };
}

Error Handling

If the summary fetch fails, account data may still be shown while hierarchy detail is unavailable; present a partial state and a retry option.

Common Error Types

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout.

Permissions & Scopes

Request Parameters

Enumerations

GET /v1/accounts/{accountId}/activities

Sample Request

const params = new URLSearchParams();
params.set('startDate', startDate.toISOString());
params.set('endDate', endDate.toISOString());
if (activityType) params.set('activityType', activityType);
if (network) params.set('network', network);
if (fromWalletId) params.set('fromWalletId', fromWalletId);
if (toWalletId) params.set('toWalletId', toWalletId);
const activitiesResponse = await fetch(
  `${baseUrl}/v1/accounts/${accountId}/activities?${params.toString()}`,
  { headers: { 'Authorization': `Bearer ${access_token}` } }
);
const activities = await activitiesResponse.json();

Response Template

{
  "items": [{
    "ledger": "Ethereum",
    "wallet": { "id": "wallet-1", "name": "Source Wallet", "walletId": "0x..." },
    "primaryCounterWallet": { "id": "wallet-2", "name": "Destination Wallet", "walletId": "0x..." },
    "createdAt": "2026-01-01T00:00:00Z",
    "totalValue": 500,
    "pricedInItem": "TOKEN",
    "status": "Completed",
    "operations": [{ "amount": 500, "token": { "symbol": "TOK" } }]
  }],
  "metadata": { "asOfDate": "2026-01-01T00:00:00Z" }
}

TypeScript Interface

interface AccountActivitiesWithMetaDataApiModel {
  items: AccountActivitiesApiModel[];
  metadata: { asOfDate: string };
}

Activity Types

These are the definitions for the activityType input filter and output values.

Response Metadata

The response includes metadata with asOfDate, indicating the point-in-time represented by the activity data.

Error Handling

Handle invalid filters as 400; expired credentials as 401; access restrictions as 403; service failures as error states with retry. Activity retrieval fails independently of account retrieval, so account detail remains displayable when activity retrieval fails.

Common Error Types

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout. If the activity service is unavailable, show account details without activities rather than failing the whole view.

Permissions & Scopes

Request Parameters

Enumerations

GET /v1/conversion/accounts/{accountId}/balances

Sample Request

const balancesResponse = await fetch(
  `${baseUrl}/v1/conversion/accounts/${accountId}/balances`,
  { headers: { 'Authorization': `Bearer ${access_token}` } }
);
if (!balancesResponse.ok) throw new Error(`Balance retrieval failed: ${balancesResponse.status}`);
const balances = await balancesResponse.json();

Response Template

{
  "items": [
    {
      "cusip": "037833100",
      "security": "Apple Inc. Common Stock",
      "issueSubType": {
        "id": "1",
        "code": "CS",
        "description": "Common Stock"
      },
      "totalQuantity": 131,
      "walletsCount": 2,
      "ledgersCount": 2,
      "holders": [
        {
          "quantity": 101,
          "wallet": {
            "id": "06572a05-8033-4088-8b0a-01faa6ed74df",
            "name": "First Bank EVM Wallet",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
          },
          "ledger": {
            "name": "Ethereum",
            "network": "Ethereum_Mainnet"
          }
        },
        {
          "quantity": 30,
          "wallet": {
            "id": "1b6e961b-6c6a-4726-8f4c-f2330a5782fa",
            "name": "American Bank Besu Wallet",
            "walletAddress": "0x4bDb16A35fc5fdc4A8701Bc5B688D254E99027c0"
          },
          "ledger": {
            "name": "Besu private",
            "network": "Besu"
          }
        }
      ]
    }
  ],
  "metadata": {
    "asOfDate": "2026-05-18T00:00:00Z"
  }
}

TypeScript Interface

interface AccountBalancesResponse {
  items: AccountSecurityBalancesResponse[];
  metadata: AccountBalancesMetadataResponse;
}
interface AccountSecurityBalancesResponse {
  cusip: string;
  security: string;
  issueSubType: { id: string; code: string; description: string };
  totalQuantity: number;
  walletsCount: number;
  ledgersCount: number;
  holders: SecurityBalanceHolder[];
}
interface SecurityBalanceHolder {
  quantity: number;
  wallet: { id: string; name: string; walletAddress: string };
  ledger: { name: string; network: string };
}
interface AccountBalancesMetadataResponse {
  asOfDate: string;
}

Response Metadata

The response includes metadata with asOfDate, indicating the point-in-time represented by the balance data.

Error Handling

Handle 401 by requesting a new JWT access credential and retrying once; handle 403 as either an insufficient permission scope or an account the service account is not authorized for; handle 404 as an unknown or inaccessible account identifier and correct the value rather than retrying.

Common Error Types

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout using exponential backoff with a bounded retry limit. Because this call is expected to run frequently as part of pre-conversion checks and scheduled reconciliation, refresh the JWT access credential proactively ahead of its expiry rather than re-authenticating reactively after a 401.

Permissions & Scopes

This endpoint uses the Service Account Credentials grant, consistent with the rest of this guide. Request the credential from /connect/token with grant_type=urn:dtcc:params:oauth:grant-type:service-account-credentials, type=conveyance, entity context, tenant context via acr_values=tenant:{tenantId}, and service-account credentials before calling this endpoint.

Prerequisites

Provisioned service account, service account password, tenant ID, and a valid account ID. Service accounts and permissions are provisioned by DTCC. The service account must be granted the permission required to access the balances endpoint used in step five.

Test Data

const tenantId = "<tenant-id>";
const accountId = "<account-id>";
const baseUrl = "<base-url>";
const username = "SA-AccountBot";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;

Negative Test Cases

Production Certification Criteria

A customer is certified only on successful authentication, account retrieval, hierarchy retrieval, activity retrieval, and balance retrieval with payload validation, reconciliation, and metadata processing, plus token lifecycle management and a bounded retry strategy, plus proper error handling for invalid credentials, expired credentials, invalid account, insufficient permission, access denied, user lockout, malformed authentication requests, and service failures, plus evidence collection showing each stage completed successfully.

Enumerations

GET /v1/conversion/clients

Sample Request

const accountsResponse = await fetch(`${baseUrl}/v1/conversion/clients`, {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
const accounts = await accountsResponse.json();

Response Template

[
  { "name": "Example Account", "externalId": "external-id", "id": "account-id" }
]

TypeScript Interface

interface AccountDetails { name: string; externalId: string; id?: string; entityId?: string; }

Error Handling

If client reference data fails, wallet context may be incomplete; present a retry path and keep the wallet inventory visible. The reference-data call fails independently of the wallet inventory call.

Common Error Types

Retry Guidance

Reference data GETs are read-only and safe to retry. The call must resolve before inventory review begins.

Permissions & Scopes

Prerequisites

Tenant ID, service account, service account password, base URL, and known wallet data. Required access: /connect/token, /v1/conversion/wallets, /v1/conversion/clients.

Test Data

const tenantId = "<tenant-id>";
const baseUrl = "<base-url>";
const username = "SA-WalletReader";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;

Shared Helper Functions

async function authenticate() {
  const response = await fetch(`${baseUrl}/connect/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "urn:dtcc:params:oauth:grant-type:service-account-credentials",
      type: "conveyance",
      entity: ENTITY_ID_OF_WHICH_SA_IS_MEMBER_OF,
      acr_values: `tenant:${tenantId}`,
      username,
      password
    })
  });
  if (!response.ok) throw new Error(`Authentication failed: ${response.status}`);
  const data = await response.json();
  return data.access_token;
}

async function getWallets(accessToken: string) {
  const response = await fetch(`${baseUrl}/v1/conversion/wallets`, {
    headers: { Authorization: `Bearer ${accessToken}` }
  });
  if (!response.ok) throw new Error(`Wallet retrieval failed: ${response.status}`);
  return response.json();
}

async function getClients(accessToken: string) {
  const response = await fetch(`${baseUrl}/v1/conversion/clients`, {
    headers: { Authorization: `Bearer ${accessToken}` }
  });
  if (!response.ok) throw new Error(`Client retrieval failed: ${response.status}`);
  return response.json();
}

Negative Test Cases

Production Certification Criteria

A customer is certified only on successful authentication, wallet inventory retrieval, client retrieval, inventory review, and wallet-status review, plus proper handling of all negative tests.

Request Parameters

Enumerations

GET /v1/conversion/securities

GET /v1/conversion/wallets

Sample Request

const [securitiesResponse, walletsResponse] = await Promise.all([
  fetch(`${baseUrl}/v1/conversion/securities?status=Active`, { headers: { 'Authorization': `Bearer ${access_token}` } }),
  fetch(`${baseUrl}/v1/conversion/wallets`, { headers: { 'Authorization': `Bearer ${access_token}` } })
]);
const securities = await securitiesResponse.json();
const wallets = await walletsResponse.json();
const eligibleWallets = wallets.filter(w => w.state === 'Idle');

Response Template

{
  "securities": [
    { "id": "security-id", "cusip": "123456789", "issuerName": "Example Issuer", "security": "Example Security", "status": "Active" }
  ],
  "wallets": [
    { "id": "wallet-id", "name": "Example Wallet", "type": "INTERNAL", "network": "DTC_Classic", "walletAddress": "0x...", "state": "Idle" }
  ]
}

TypeScript Interface

interface Security {
  id: string;
  cusip: string;
  issuerName: string;
  security: string;
  securitySymbol?: string;
  issueType: IssueType;
  issueSubType: IssueType;
  status: string;
  trackingTrancheId: string;
}
interface WalletSummary {
  id: string;
  name: string;
  type: string;
  network: string;
  walletAddress: string;
  account: AccountDetails;
  state: string;
  participant?: Participant;
}

Eligibility Rules

Only Active securities are eligible for orders. A wallet is eligible as a source or destination candidate only when its processing state is Idle and conversionEligible is true. Both conditions must hold; an Idle wallet that is not conversion eligible must be excluded.

An Active status is necessary but not sufficient. A security can be Active and still carry a chill or lock, which blocks transfers of its tokens while the restriction is in effect. Before treating an Active security as usable, read its restrictions object and confirm that dOChill, globalLock, and complianceLock all report "enabled": false. See the List Registered Securities and Filter Data card for the full restriction model.

Error Handling

Handle 401 by requesting a new JWT access credential and retrying once; handle 5xx with retry and an error state. If no Active security or no Idle wallet is returned, block order submission rather than submitting an ineligible order.

Common Error Types

Retry Guidance

Both calls are read-only GETs and safe to retry on 5xx or network timeout.

Permissions & Scopes

Request Parameters

GET /v1/conversion/orders

POST /v1/conversion/orders

POST /v1/conversion/async-operations/query

GET /v1/conversion/orders/{orderId}

Batch Query Behavior

The idempotencyKeys field on POST /v1/conversion/async-operations/query accepts an array, and the server processes all keys supplied in a single query. As a best practice, submit no more than 100 idempotency keys per request; submitting very large arrays in a single request may impact performance.

Enumerations

GET /v1/conversion/orders

POST /v1/conversion/async-operations/query

GET /v1/conversion/orders/{orderId}

The submission endpoint POST /v1/conversion/orders returns no response body, so it publishes no response enumerations. The tables above cover the three calls that read order state.

Sample Request

GET /v1/conversion/orders

const query = new URLSearchParams({
  fromWallet: sourceWallet.id,
  toWallet: destinationWallet.id,
  financialSecurityIds: selectedSecurity.id,
  status: 'Processing',
  offset: '0',
  count: '20'
});

const ordersResponse = await fetch(`${baseUrl}/v1/conversion/orders?${query}`, {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
const existingOrders: OrderResponse[] = await ordersResponse.json();

POST /v1/conversion/orders

const idempotencyKey = generateIdempotencyKey();

const orderResponse = await fetch(`${baseUrl}/v1/conversion/orders`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
    'X-Idempotency-Key': idempotencyKey
  },
  body: JSON.stringify({
    financialSecurityId: selectedSecurity.id,
    fromWalletId: sourceWallet.id,
    toWalletId: destinationWallet.id,
    activityType: '040',
    quantity: '500'
  })
});

// 202 Accepted with no response body. Retain idempotencyKey for the async query.
if (orderResponse.status !== 202) {
  throw new Error('Conversion order was not accepted');
}

POST /v1/conversion/async-operations/query

const asyncResponse = await fetch(`${baseUrl}/v1/conversion/async-operations/query`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    idempotencyKeys: [idempotencyKey],
    offset: 0,
    count: 10
  })
});

const operations: AsyncOperationResponse[] = await asyncResponse.json();
const orderId = operations[0]?.resourceId;

GET /v1/conversion/orders/{orderId}

const detailResponse = await fetch(`${baseUrl}/v1/conversion/orders/${orderId}`, {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
const orderDetail: OrderDetailResponse = await detailResponse.json();
// orderDetail.status === 'Processing'

Response Template

GET /v1/conversion/orders

[
  {
    "id": "order-id",
    "symbol": "EXMPL",
    "cusip": "037833100",
    "fromWallet": { "id": "source-wallet-id", "name": "Participant Classic Account", "walletAddress": "00002667-10" },
    "toWallet": { "id": "destination-wallet-id", "name": "First Bank EVM Wallet", "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" },
    "quantity": 500,
    "status": "Processing",
    "errorMessage": null,
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z",
    "activityType": "040",
    "origin": "Participant"
  }
]

POST /v1/conversion/orders returns 202 Accepted with an empty body.

POST /v1/conversion/async-operations/query

[
  {
    "id": "async-operation-id",
    "idempotencyKey": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "objectKind": "Order",
    "status": "Completed",
    "operationName": "Submit",
    "resourceId": "order-id",
    "resourceUrl": "/v1/conversion/orders/order-id",
    "errorCode": null,
    "errorMessage": null,
    "asOfDate": "2026-01-01T00:00:00Z"
  }
]

GET /v1/conversion/orders/{orderId}

{
  "orderId": "order-id",
  "participant": { "id": "participant-id", "participantNumber": "00002667" },
  "financialSecurityInfo": { "cusip": "037833100", "security": "Example Security" },
  "fromWallet": { "id": "source-wallet-id", "name": "Participant Classic Account", "walletAddress": "00002667-10" },
  "toWallet": { "id": "destination-wallet-id", "name": "First Bank EVM Wallet", "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" },
  "quantity": 500,
  "submittedBy": "SA-ConversionBot",
  "status": "Completed",
  "errorMessage": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:05:00Z",
  "activityType": "040",
  "fromTransactionId": "0x639dc5a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d",
  "toTransactionId": "12200cc6f1e2d3c4b5a69788796a5b4c3d2e1f00998877665544332211aabbccdd",
  "check": { "status": "Passed" },
  "origin": "Participant"
}

While an order is in Processing, both fromTransactionId and toTransactionId are null. They are populated with the on-chain ledger transaction hashes once the order reaches Completed and the underlying ledger events settle. See the Transaction Identifiers section below for field-level semantics.

Transaction Identifiers

The order detail response (GET /v1/conversion/orders/{orderId}) is the only endpoint that exposes the on-chain transaction identifiers for a conversion. The orders list endpoint (GET /v1/conversion/orders) does not return these fields.

Both fields are null until the order settles, then carry the ledger-native transaction hash for their respective leg. The hash format follows the convention of the underlying network (for example, a 0x-prefixed 32-byte hex string on Besu/EVM networks). Because a conversion moves between a DTC Classic account and a digital wallet, only the digital-wallet leg corresponds to a blockchain transaction; the DTC Classic leg (identifiers in the {participantId}-10 / {participantId}-11 format) is not an on-chain event, so the transaction identifier that carries an on-chain hash depends on the conversion direction.

TypeScript Interface

interface OrderResponse {
  id: string;
  symbol?: string;
  cusip?: string;
  fromWallet: WalletRefResponse;
  toWallet: WalletRefResponse;
  quantity: number;
  status: string;
  errorMessage?: string;
  createdAt: string;
  obac?: AccessControlInfoResponse;
  activityType?: string;
  updatedAt?: string;
  origin?: string;
}

interface AsyncOperationResponse {
  id: string;
  idempotencyKey: string;
  objectKind: string;
  status: string;
  operationName: string;
  resourceId?: string;
  resourceUrl?: string;
  errorCode?: string;
  errorMessage?: string;
  asOfDate: string;
}

interface OrderDetailResponse {
  orderId: string;
  participant: ParticipantResponse;
  financialSecurityInfo?: OrderFinancialSecurityInfo;
  fromWallet: WalletRefResponse;
  toWallet: WalletRefResponse;
  quantity: number;
  submittedBy?: string;
  submitterEmail?: string;
  submitterComment?: string;
  status: string;
  errorMessage?: string;
  createdAt: string;
  updatedAt?: string;
  activityType?: string;
  fromTransactionId?: string;
  toTransactionId?: string;
  check: CheckInfoResponse;
  origin?: string;
}

Business Rules

Conversion direction must move between DTC_Classic and non-Classic wallets. Orders can be submitted Monday-Friday, 02:00-18:15 ET, with operational-hours enforcement server-side. Query the orders list before submitting to detect whether a prior submission with the same intent already exists, filtering on fromWallet, toWallet, financialSecurityIds, or status.

Error Handling

Handle 400 validation errors, 403 permission or lockout failures, 409 duplicate idempotency key, 422 business rule violations, and 5xx server errors. Submission does not execute the conversion synchronously; a 202 Accepted response confirms only that the order was queued for processing. Treat an async operation status of Failed as a submission failure and surface errorCode and errorMessage.

Common Error Types

HTTP 400 — Bad Request

HTTP 404 — Not Found

HTTP 409 — Conflict

HTTP 500 — Internal Server Error

Unhandled or infrastructure failures. The errorCode value is "500". Not retryable without platform investigation.

Retry Guidance

The submission POST is protected by X-Idempotency-Key. Retrying with the same key is safe and will not create duplicate orders. Do not generate a new key on retry, because the key is also the lookup value for the async operation query. The async operation query and the order detail retrieval are read-only and safe to retry.

Permissions & Scopes

Key Business Rules

Test Data

const tenantId = "<tenant-id>";
const baseUrl = "<base-url>";
const username = "SA-ConversionBot";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;

Shared Helper Functions

async function authenticate() {
  const response = await fetch(`${baseUrl}/connect/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "urn:dtcc:params:oauth:grant-type:service-account-credentials",
      type: "conveyance",
      entity: ENTITY_ID_OF_WHICH_SA_IS_MEMBER_OF,
      acr_values: `tenant:${tenantId}`,
      username,
      password
    })
  });
  if (!response.ok) {
    throw new Error(`Authentication failed: ${response.status}`);
  }
  const data = await response.json();
  return data.access_token;
}

async function loadReferenceData(accessToken: string) {
  const [ordersResponse, securitiesResponse, walletsResponse] = await Promise.all([
    fetch(`${baseUrl}/v1/conversion/orders`, { headers: { Authorization: `Bearer ${accessToken}` } }),
    fetch(`${baseUrl}/v1/conversion/securities`, { headers: { Authorization: `Bearer ${accessToken}` } }),
    fetch(`${baseUrl}/v1/conversion/wallets`, { headers: { Authorization: `Bearer ${accessToken}` } })
  ]);
  return {
    orders: await ordersResponse.json(),
    securities: await securitiesResponse.json(),
    wallets: await walletsResponse.json()
  };
}

async function loadFilterData(accessToken: string) {
  const [issueTypesResponse, issueSubTypesResponse] = await Promise.all([
    fetch(`${baseUrl}/v1/conversion/securities/issue-types`, { headers: { Authorization: `Bearer ${accessToken}` } }),
    fetch(`${baseUrl}/v1/conversion/securities/issue-subtypes`, { headers: { Authorization: `Bearer ${accessToken}` } })
  ]);
  return {
    issueTypes: await issueTypesResponse.json(),
    issueSubTypes: await issueSubTypesResponse.json()
  };
}

function generateIdempotencyKey() {
  return crypto.randomUUID();
}

async function queryOperation(accessToken: string, idempotencyKey: string) {
  const response = await fetch(`${baseUrl}/v1/conversion/async-operations/query`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ idempotencyKeys: [idempotencyKey], offset: 0, count: 10 })
  });
  const [operation] = await response.json();
  return operation;
}

async function getOrder(accessToken: string, orderId: string) {
  const response = await fetch(`${baseUrl}/v1/conversion/orders/${orderId}`, {
    headers: { Authorization: `Bearer ${accessToken}` }
  });
  if (!response.ok) {
    throw new Error(`Order retrieval failed with status ${response.status}`);
  }
  return response.json();
}

Negative Test Cases

Production Certification Criteria

The customer must demonstrate authentication, reference-data retrieval, active-security validation, wallet eligibility validation covering both idle state and the conversion-eligible flag, conversion-order submission, idempotency compliance, async-operation monitoring, async-to-order correlation, final-order retrieval, lifecycle monitoring, audit validation, required negative-test handling, and end-to-end workflow execution.

Request Parameters

Enumerations

GET /v2/corporate-actions/{id}

Enumeration values are defined once in the Corporate Action Enumerations reference at the end of this section.

Sample Request

const eventDetailResponse = await fetch(
  `${baseUrl}/v2/corporate-actions/${eventId}`,
  { headers: { 'Authorization': `Bearer ${access_token}` } }
);
if (!eventDetailResponse.ok) {
  const error = await eventDetailResponse.json();
  throw new Error(`Event detail request failed: ${error.ErrorCode} - ${error.ErrorMessage}`);
}
const eventDetail = await eventDetailResponse.json();

Response Template

{
  "id": "event-record-id",
  "eventId": "123456",
  "eventGroup": "Distribution",
  "eventType": "CashDividend",
  "eventTypeDescription": "Cash Dividend",
  "subEventType": "CDeemedDividend",
  "subEventTypeDescription": "305C - Deemed Dividend",
  "status": "ConditionallyApproved",
  "category": "MandatoryCashDistribution",
  "isSupported": false,
  "dtcMandatory": "Mandatory",
  "security": { "id": "security-id", "cusip": "46625H202", "name": "Example Security", "issuerDescription": "Example Issuer", "assetClass": "Equity", "assetType": "Common Stock", "ticker": "EX" },
  "coreDates": { "exDate": "2026-06-24T00:00:00Z", "recordDate": "2026-06-24T00:00:00Z", "declaredPayableDate": "2026-06-24T00:00:00Z", "allocationDateTime": null }
}

TypeScript Interface

interface CorporateActionEventResponse {
  id: string;
  security: { id: string; cusip: string; name: string; issuerDescription: string; assetClass: string; assetType: string; ticker: string };
  eventId: string;
  eventGroup: string;
  eventType: string;
  eventTypeDescription: string;
  subEventType: string;
  subEventTypeDescription: string;
  status: string;
  category: string;
  isSupported: boolean;
  dtcMandatory: string;
  reconversionDate: string | null;
  coreDates: Record<string, string | null>;
}

Single Endpoint Detail

The event detail response includes security information, event classification, status, category, DTC mandatory classification, support indicator, reconversion date, and coreDates. No separate entitlements endpoint is needed for the workflow described in the source material.

Error Handling

Handle 401 as an expired credential, 403 as lockout or missing detail permission, 404 as an invalid or deleted event, 400 as an invalid event ID format, and 500 with retry. The response body carries ErrorCode and ErrorMessage, which should be surfaced rather than discarded.

Common Error Types

Retry Guidance

Read-only GET; safe to retry on 5xx or network timeout. Use exponential backoff with a maximum of three retries.

Permissions & Scopes

Key Business Rules

Prerequisites

Tenant ID, service account, service account password, base URL, a known corporate action event, and securities access. Required endpoints: /connect/token, POST /v2/corporate-actions, /v2/corporate-actions/event-types, /v1/conversion/securities, /v2/corporate-actions/{id}.

Test Data

const tenantId = "<tenant-id>";
const baseUrl = "<base-url>";
const username = "SA-CorporateActionsBot";
const password = process.env.SERVICE_ACCOUNT_PASSWORD!;

Shared Helper Functions

async function loadCorporateActionsData(accessToken: string) {
  const [eventsResponse, eventTypesResponse, securitiesResponse] = await Promise.all([
    fetch(`${baseUrl}/v2/corporate-actions`, {
      method: "POST",
      headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
      body: JSON.stringify({ offset: 0, count: 25 })
    }),
    fetch(`${baseUrl}/v2/corporate-actions/event-types`, { headers: { Authorization: `Bearer ${accessToken}` } }),
    fetch(`${baseUrl}/v1/conversion/securities`, { headers: { Authorization: `Bearer ${accessToken}` } })
  ]);
  return {
    events: await eventsResponse.json(),
    eventTypes: await eventTypesResponse.json(),
    securities: await securitiesResponse.json()
  };
}

async function getEventDetail(accessToken: string, eventId: string) {
  const response = await fetch(`${baseUrl}/v2/corporate-actions/${eventId}`, {
    headers: { Authorization: `Bearer ${accessToken}` }
  });
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Event detail failed: ${error.ErrorCode} - ${error.ErrorMessage}`);
  }
  return response.json();
}

Negative Test Cases

Production Certification Criteria

The customer must demonstrate authentication, event retrieval, event-type retrieval, securities retrieval, event filtering, event-detail retrieval, context interpretation, category-date interpretation, DTC classification interpretation, negative-test handling, and end-to-end workflow execution.

Authentication and Authorization

• Standardized every documented workflow on the Service Account Credentials grant and removed all references to the OAuth 2.0 Client Credentials grant from the live guide. All token requests now use grant_type=urn:dtcc:params:oauth:grant-type:service-account-credentials, type=conveyance, entity context, and acr_values=tenant:{tenantId}.
• Removed the Authentication panel exception callout that described Conversion Order endpoints using the Client Credentials grant, and simplified the Required Token Inputs note for username / password to state that service-account credentials are always used.
• Added a Sample Token Request code example to the Authentication panel (opened from the Authentication hero button), showing a runnable authenticate() call against /connect/token using the Service Account Credentials grant, consistent with the certification helpers.

Account Management

• Converted the Get Account Balances endpoint Permissions & Scopes from the OAuth 2.0 Client Credentials grant to the Service Account Credentials grant.
• Reworked the Account Management Certification Test so all five steps use a single service-account credential: updated the workflow intro and the balances branch note, removed the clientId / clientSecret / scope test data, rewrote Step 5 to reuse the Step 1 token via getBalances(accessToken, accountId), reworded the Step 5 error envelopes and negative tests (NT-1, NT-6, NT-7) away from client-credential terminology, and changed the production criteria from "invalid scope" to "insufficient permission".

Conversion Orders

• Converted the Conversion Orders authentication pattern callout from the OAuth 2.0 Client Credentials grant to the Service Account Credentials grant.
• Reworked the Conversion Order Certification Tests to authenticate with the service-account grant: updated the certification intro, the Step 1 workflow-diagram label, and the flow-key chip; replaced the clientId / clientSecret / CONVERSION_SCOPE test data with tenantId / username / password; rewrote the authenticate() helper to use the service-account grant; and reworded Step 1, Step 2, Step 5, and negative test NT-1 away from client-credential terminology.
• Added the status input query filter to the List Registered Securities and Filter Data card. Documented it in the Request Parameters table as an optional single-value filter accepting one FinancialSecurityStatus value (Onboarding, Active, Pause, Failed), and added a matching Input (query) row to the GET /v1/conversion/securities Enumerations table.
• Aligned the Conversion Order Certification Tests authenticate() helper with the Account and Wallet certification helpers so it returns data.access_token directly rather than the full token object, and simplified the Step 1 call site to const accessToken = await authenticate();.

Document

• Published as version 4.18. Prior changelog entries that reference the OAuth 2.0 Client Credentials grant are retained as historical record.

Corporate Actions

• Consolidated the corporate action enumerations into a single Corporate Action Enumerations reference block at the end of the section. The event-list, event-types, and event-detail Enumerations tables no longer repeat the full value lists; each row now links to the shared reference.
• Presented EventTypeEnumeration and SubEventTypeEnumeration as value / description tables, collapsed behind a show-all disclosure. Numeric codes are not published in the reference because the OpenAPI enums are declared as plain string enums; the authoritative code mapping is whatever GET /v2/corporate-actions/event-types returns at runtime.
• Defined the smaller shared enumerations (EventStatusEnumeration, DtcMandatory, EventCategory, EventFields, SortOrder) once in the same reference and linked to them from the endpoint tables.
• Added a note that valid type / subType pairings are enumerated by GET /v2/corporate-actions/event-types.

Corporate Actions

• Migrated the corporate action events list from the deprecated GET /v1/corporate-actions to POST /v2/corporate-actions. The filter and pagination fields are now supplied in a JSON request body (EventFilterRequest) rather than query-string parameters.
• Aligned the Request Parameters with the V2 EventFilterRequest schema: offset and count are required; ids filters by internal (GUID) event identifiers and eventIds by external DTC event identifiers; eventTypes is an array of EventTypeFilterItem objects (each with a type and optional subType); added securityIds and securityCusips; retained status, searchFor, orderBy, and sortOrder as body fields.
• Updated the List Corporate Action Events and Reference Data card: changed the method badge to POST, updated the path header, added an endpoint-migration callout, moved all filter fields to the request body, relabeled the Enumerations table to POST /v2/corporate-actions with Input (body) directions (including the EventFields values for orderBy and the nested eventTypes[].type / eventTypes[].subType filter), and rewrote the sample request to issue a POST with a JSON body.
• Corrected the response template and TypeScript interface to the V2 CorporateActionEventResponse schema, using type, typeDescription, subType, subTypeDescription, the DTC date fields, dtcProcessingIndicator, and the SecurityListResponse security shape.
• Updated the Corporate Actions workflow summary, the "Retry and dependencies" callout, and the per-card retry guidance to reflect that the events list is now a read-only POST query while the event-types and securities calls remain GET requests.
• Updated the Corporate Actions Workflow Certification Test: the workflow diagram, prerequisites, shared loadCorporateActionsData helper, and Step 2 now call POST /v2/corporate-actions with a JSON body.

Overview

• Updated the Primary API Journeys table Corporate Actions row to reference /v2/corporate-actions in place of /v1/corporate-actions.

Reference

• Updated the API Families modal Corporate Action APIs box and the Endpoint Catalog to list POST /v2/corporate-actions in place of the deprecated GET /v1/corporate-actions.
• Updated the Pagination Model Endpoint Support table to show POST /v2/corporate-actions, noting that Offset and Count are sent in the request body rather than the query string.

Conversion Orders

• Documented batch behavior for the idempotencyKeys array on POST /v1/conversion/async-operations/query. Clarified that the server processes all keys supplied in a single query, and established a best practice of submitting no more than 100 keys per request to avoid the performance impact of very large arrays.
• Added a Batch Query Behavior section covering unmatched keys (no error is returned and only matched records appear in the response), pagination of results via Count and Offset, and the recommended batch size.

Conversion Orders

• Documented the fromTransactionId and toTransactionId fields on the Submit and Track Conversion Orders card. Added a Transaction Identifiers section defining each field as the on-chain ledger transaction hash for the source (debit) and destination (credit) legs, noting they are null while an order is Processing and populated once the order reaches Completed.
• Recorded that these identifiers appear only on the order detail endpoint GET /v1/conversion/orders/{orderId} and not on the orders list endpoint.
• Explained the direction dependency, that only the digital-wallet leg maps to a blockchain transaction while the DTC Classic leg does not, and the relationship to external custody or validator providers such as Fireblocks, which report the same underlying on-chain hash.
• Updated the order detail response template to show a Completed order with populated fromTransactionId and toTransactionId hashes.

Account Management

• Replaced the plain-text Activity Types list on the Get Account Activities endpoint with a Value and Description table defining each activity type, and stated that the definitions apply to both the activityType input filter and the output values.
• Added an activityType row (ActivityType enumeration) to the Get Account Activities Enumerations table, covering Payment, PaymentReceived, Fee, Mint, Burn, Pause, Unpause, Freeze, Unfreeze, Revoked, Clawedback, and Clawback.

Conversion Orders

• Moved the ConversionOperationsEngine__WalletNotFound error code from the HTTP 404 table to the HTTP 400 table in the Error Code Reference.

Overview

• Removed the /v1/tracking/networks endpoint from the Primary API Journeys table for the Wallet Management and Conversion Orders rows.

Wallet Management

• Removed the /v1/tracking/networks ledger-networks endpoint. Renamed the combined "Load Ledger and Account Reference Data" endpoint to "Load Account Reference Data", now covering only /v1/conversion/clients, and updated the workflow summary and certification test (flow, prerequisites, helper functions, steps, and end-to-end execution) to load account reference data only.

Conversion Orders

• Removed /v1/tracking/networks from the List Registered Securities and Filter Data endpoint, its workflow summary, enumerations, sample request, and certification filter-data helper. The network query filter on the securities list is retained.

Reference

• Removed /v1/tracking/networks from the API Families modal and the Endpoint Catalog.

Conversion Orders

• Expanded the Common Error Types section on the Submit and Track Conversion Orders endpoint. Split the combined 500/503 row into separate 500 and 503 rows and added cross-references from the 400, 404, 409, and 500 rows to the new detail tables.
• Added an Error Code Reference subsection listing the machine-readable errorCode values, causes, and corrections for HTTP 400, 404, 409, and 500.

Conversion Orders

• Added a Status and Restrictions Are Separate Signals section to the List Registered Securities and Filter Data card, explaining that all eligible securities carry an Active status but may still have a chill or lock in effect, that a chill or lock is a transfer restriction applied to the entire security, and how to read the restrictions object to detect it.
• Documented the three restriction types, dOChill, globalLock, and complianceLock, each reported with an enabled flag and an updatedAt timestamp, and noted that the enabled flag should always be tested rather than checking whether a field exists.
• Added the restrictions block to the securities response template and the SecurityRestrictions and RestrictionState types to the TypeScript interface.
• Extended the eligibility rules on the Load Active Securities and Registered Wallets card to state that an Active status is necessary but not sufficient, and that an Active security must be confirmed unrestricted before it is treated as usable.

Account Management

• Replaced the string UUID type with string on the account hierarchy summary and account activities parameter tables.

Conversion Orders

• Replaced the string UUID type with string on the Submit and Track Conversion Orders parameter table.

Corporate Actions

• Added an introductory paragraph noting that the corporate action notification API endpoints leverage DTCC's ISO CANO messages, with a link to DTCC's ISO 20022 Messaging Specifications.

Onboarding

• Removed the workflow summary description sentence and the Entity Creation, Account Provisioning, Service Accounts, and Production Activation labels from the workflow summary.

Wallet Management

• Corrected the ledgers endpoint path from /v1/networks/ledgers to /v1/tracking/networks to match the API specification.
• Updated the response template and TypeScript interface to the flat network model with name, displayName, networkStatus, nodeFormats, and listenerEnabled, and fixed the sample request filter accordingly.
• Renamed the response enumeration field from status to networkStatus and removed the nodeStatus / NetworkNodeStatus row, which the specification does not define.

Pagination Model

• Expanded the Endpoint Support table to list every endpoint in the endpoint catalog, added a Method column, and recorded pagination support for each based on the API specifications.