Custody gateway API

The custody gateway routes live under /api/v2/addons/custody-gateways. They form the custodyOps operation group of the Platform API, and the generated API reference lists every route and schema. This page walks the routes in the order a deposit and a withdrawal use them. Deposit and withdrawal stages lists what each stage means and who moves it. Custody gateway explains the model.

Before you call#

• The “Self-custody” module must be on. With it off, every route answers DALP-20531 (platform.module.DISABLED).
• Paths below are relative to /api/v2/addons/custody-gateways. {gatewayAddress} is the client's gateway address.
• Each write carries a walletVerification object that proves the acting wallet. A write answers 200 when it is final and 202 when it waits for a second approver. A write honours an Idempotency-Key header, so a retry with the same key does not repeat it. Idempotency and async settlement says how.
• Gateway manager actions need the gateway manager role on the acting wallet, and the screener actions need the screener role. A client acts with the wallet bound to its gateway.

Bind the client wallet#

A gateway has no client wallet when it is created. Bind one before the client's own routes work:

curl -X PATCH "https://your-instance.example.com/api/v2/addons/custody-gateways/gateways/$GATEWAY/client-wallet" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{"clientWallet": "0x...", "walletVerification": {...}}'

The wallet must belong to the gateway's client identity. The result is { "clientWallet": "0x..." }. GET /gateways/mine then returns the gateway to the client, with the address the client deposits into.

Walk a deposit#

1. The client reads the gateway with GET /gateways/mine and sends coins to its address, or records a deposit from a wallet with POST /gateways/{gatewayAddress}/deposits. The body is { "token", "amount", "walletVerification" }.
2. List the gateway's deposits with GET /gateways/{gatewayAddress}/deposits and read one with GET /gateways/{gatewayAddress}/deposits/{depositId}. A new deposit rests at Quarantined.
3. The screener moves it with POST /gateways/{gatewayAddress}/deposits/{depositId}/transitions:

curl -X POST ".../gateways/$GATEWAY/deposits/$DEPOSIT/transitions" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{"transition": "clear", "walletVerification": {...}}'

4. The operator transitions are confirm-sender, clear, refuse, flag, unfreeze, renew-freeze, report, return, retry, custody-returned and recover. The client transitions are pull-back and exit. recover also takes "to", the wallet that receives the coins.
5. Read GET .../deposits/{depositId}/screening for the screening result and POST .../deposits/{depositId}/notes to add an operator note.

Walk a withdrawal#

1. The client asks for the fee with GET .../withdrawal-fee-quotes, then creates the request with POST /gateways/{gatewayAddress}/withdrawals. The body is { "receiptToken", "shares", "payout", "walletVerification" }. The payout address must be on the gateway's approved payout list.
2. List and read requests with GET .../withdrawals and GET .../withdrawals/{requestId}. Read GET .../withdrawals/{requestId}/screening for the screening result.
3. Move a request with POST .../withdrawals/{requestId}/transitions. The operator transitions are clear, approve, reject, flag, unfreeze, renew-freeze, report, return and unfulfil. The client transitions are cancel, collect, exit and set-payout, and set-payout also takes "payout".
4. The client sets how it is paid with PATCH .../auto-claim ({ "enabled", "walletVerification" }) and PATCH .../default-payout ({ "payout", "walletVerification" }).

curl -X POST ".../gateways/$GATEWAY/withdrawals/$REQUEST/transitions" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{"transition": "collect", "walletVerification": {...}}'

Reinstate a payout address#

A client flag suspends the gateway's payout addresses. Clearing the flag does not reinstate them. After review, a gateway manager reinstates one with the address's transitions route:

curl -X POST ".../gateways/$GATEWAY/approved-payouts/$ADDRESS/transitions" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{"transition": "reinstate", "walletVerification": {...}}'

The other transitions on that route are remove and suspend. GET .../approved-payouts lists the addresses and their state, and POST .../approved-payouts adds one.

Other routes#

Related pages#

• Deposit and withdrawal stages
• Review deposits and withdrawals in the Console
• Calling routes with the SDK