{
  "subscriptionId": "00000000-0000-4000-8000-000000000001",
  "notificationId": "11111111-1111-4111-8111-111111111101",
  "notificationType": "custody.transfer",
  "notification": {
    "id": "22222222-2222-4222-8222-222222222201",
    "source": {
      "type": "wallet",
      "id": "1000000001"
    },
    "destination": {
      "type": "wallet",
      "id": "1000000002"
    },
    "amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "status": "complete",
    "createDate": "2026-08-25T19:17:02.027Z",
    "nickname": "Example workspace",
    "walletDescription": "Example account"
  },
  "timestamp": "2026-08-25T19:17:02.429598683Z",
  "version": 2
}

Transfer state change

Sent when a stablecoin transfer changes state. A blockchain source is an inbound crypto deposit into a subaccount. A blockchain destination is an outbound crypto transfer. A wallet source with a wallet destination is an internal transfer between subaccounts. status is one of pending, complete, or failed. A transfer denied by a policy decision reports failed.

The payload also carries transactionHash, fees, message, errorCode, riskEvaluation, policyEvaluation, and identities when those values apply.

WEBHOOK

custodyTransfer

{
  "subscriptionId": "00000000-0000-4000-8000-000000000001",
  "notificationId": "11111111-1111-4111-8111-111111111101",
  "notificationType": "custody.transfer",
  "notification": {
    "id": "22222222-2222-4222-8222-222222222201",
    "source": {
      "type": "wallet",
      "id": "1000000001"
    },
    "destination": {
      "type": "wallet",
      "id": "1000000002"
    },
    "amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "status": "complete",
    "createDate": "2026-08-25T19:17:02.027Z",
    "nickname": "Example workspace",
    "walletDescription": "Example account"
  },
  "timestamp": "2026-08-25T19:17:02.429598683Z",
  "version": 2
}

Body

application/json

The envelope every v2 webhook notification arrives in. The product-specific fields live in notification.

subscriptionId

string<uuid>

required

ID of the webhook subscription that produced this notification.

notificationId

string<uuid>

required

Unique ID for this event. Stable across retries of the same delivery, so use it to deduplicate.

notificationType

enum<string>

required

The type of notification.

Available options:

custody.transfer

notification

any

required

The event payload. The schema of this object depends on notificationType.

timestamp

string<date-time>

required

When the notification was produced.

version

integer

required

The version of the notification schema. Always 2.

Response

200

Webhook received successfully

API overview

Custody API

Mint API

Cross-currency API

Reserve management API

Credit API

Digital Asset-Backed Borrowing

Webhook events

Transfer state change

Body

Response