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

fee, payment, paymentreceived, mint, burn, debit, credit, freeze, unfreeze, partialfreeze, partialunfreeze, revoked, and clawedback.

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 OAuth 2.0 Client Credentials grant with client_id, client_secret, and scope. It does not use the Service Account Credentials grant documented elsewhere in this guide. Request the credential from /connect/token with grant_type=client_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. Step five additionally requires a registered client ID, client secret, and an authorized scope granting access to the balances endpoint.

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!;

// Step 5 only: OAuth 2.0 Client Credentials grant
const clientId = process.env.CLIENT_ID!;
const clientSecret = process.env.CLIENT_SECRET!;
const scope = process.env.API_SCOPE!;

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, invalid scope, access denied, user lockout, malformed authentication requests, and service failures, plus evidence collection showing each stage completed successfully.

Enumerations

GET /v1/tracking/networks

GET /v1/conversion/clients

Sample Request

const [networksResponse, accountsResponse] = await Promise.all([
  fetch(`${baseUrl}/v1/tracking/networks`, { headers: { 'Authorization': `Bearer ${access_token}` } }),
  fetch(`${baseUrl}/v1/conversion/clients`, { headers: { 'Authorization': `Bearer ${access_token}` } })
]);
const networks = await networksResponse.json();
const accounts = await accountsResponse.json();
const availableNetworks = networks.filter(n =>
  n.networkStatus === 'Active' &&
  n.name !== 'Classic' &&
  n.name !== 'Ethereum_Mainnet'
);

Response Template

[
  {
    "name": "Ethereum_Mainnet",
    "displayName": "Ethereum Mainnet",
    "networkStatus": "Active",
    "nodeFormats": ["EVM"],
    "listenerEnabled": true
  },
  {
    "name": "Canton",
    "displayName": "Canton",
    "networkStatus": "Active",
    "nodeFormats": ["Canton"],
    "listenerEnabled": true
  }
]

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

TypeScript Interface

interface NetworkApiModel {
  name: string;
  displayName: string;
  networkStatus: string;
  nodeFormats: string[];
  listenerEnabled: boolean;
}
interface AccountDetails { name: string; externalId: string; id?: string; entityId?: string; }

Error Handling

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

Common Error Types

Retry Guidance

Reference data GETs are read-only and safe to retry. Both calls run in parallel and 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/tracking/networks, /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/json" },
    body: JSON.stringify({
      grant_type: "urn:dtcc:params:oauth:grant-type:service-account-credentials",
      type: "conveyance",
      entity: username,
      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 getLedgers(accessToken: string) {
  const response = await fetch(`${baseUrl}/v1/tracking/networks`, {
    headers: { Authorization: `Bearer ${accessToken}` }
  });
  if (!response.ok) throw new Error(`Ledger 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, ledger 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.

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}

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": "Processing",
  "errorMessage": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "activityType": "040",
  "fromTransactionId": null,
  "toTransactionId": null,
  "check": { "status": "Passed" },
  "origin": "Participant"
}

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

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 baseUrl = "<base-url>";
const clientId = process.env.CLIENT_ID!;
const clientSecret = process.env.CLIENT_SECRET!;
const scope = process.env.CONVERSION_SCOPE!;

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: "client_credentials",
      client_id: clientId,
      client_secret: clientSecret,
      scope
    })
  });
  if (!response.ok) {
    throw new Error("Authentication failed");
  }
  return response.json();
}

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, ledgersResponse] = 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}` } }),
    fetch(`${baseUrl}/v1/tracking/networks`, { headers: { Authorization: `Bearer ${accessToken}` } })
  ]);
  return {
    issueTypes: await issueTypesResponse.json(),
    issueSubTypes: await issueSubTypesResponse.json(),
    ledgers: await ledgersResponse.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}

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, /v1/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}/v1/corporate-actions`, { headers: { Authorization: `Bearer ${accessToken}` } }),
    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.

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.