Transactions & signing

Request a withdrawal, follow it from request through approval, signing, broadcast and confirmation, and sign digests directly.

Request a withdrawal

curl -X POST https://<api-host>/api/v1/wallets/{wallet_id}/request-withdrawal \
  -H "ACCESS-API-KEY: $KEY" -H "ACCESS-TIMESTAMP: $TS" -H "ACCESS-SIGN: $SIG" \
  -H "X-Idempotency-Key: 0c41…" \
  -H "Content-Type: application/json" \
  -d '{"asset_id": "<catalog asset id>", "amount": "0.25", "recipient_address": "0x…"}'

The response is the withdrawal operation with its withdrawal_id and initial status. Before anything is signed, the API:

• checks the key’s scope (withdrawals:create) and wallet binding;
• validates the recipient (EIP-55 checksum) and confirms the network’s chain ID matches the asset;
• reserves the amount plus fee against the available balance, so concurrent requests cannot overspend;
• applies workspace controls: the kill switch, destination whitelist and new-address hold, per-transaction and daily limits;
• evaluates policies and, if one matches or approval is required, holds the withdrawal for the approval group.

Repeating the request with the same X-Idempotency-Key returns the original withdrawal.

In the console: open the wallet → Withdrawal → asset, amount (or MAX), recipient. The console shows the planned amount and an estimated network fee before you submit.

Lifecycle

Status	Meaning	Event
pending	Recorded and validated; being planned or signed.	withdrawal.created, withdrawal.pending
pending_approval	Held for an approval group.	withdrawal.pending_approval
submitted	Signed and broadcast; waiting for confirmations.	withdrawal.submitted
confirmed	Receipt reached the configured confirmation depth.	withdrawal.confirmed, withdrawal.completed
failed	Rejected by a control, rejected by an approver, signing failed or timed out, or the transaction reverted. status_reason says which.	withdrawal.failed
cancelled	Cancelled before signing.	withdrawal.cancelled

What happens after approval:

1. Planning: the API builds the transaction from trusted state: current nonce, EIP-1559 fee parameters, chain ID and the validated recipient. Clients never supply a transaction or a signing hash on this path.
2. Signing: a signing request goes to the cluster; a threshold of nodes produces the signature. The private key is never assembled.
3. Broadcast: the API assembles the signed transaction, verifies its hash matches the persisted withdrawal, and submits it.
4. Confirmation: the receipt is polled until it reaches the confirmation depth. A submitted transaction with no receipt is rebroadcast unchanged; it is never re-signed with different parameters.

Read withdrawals and transactions

GET /api/v1/withdrawals/{withdrawal_id}
GET /api/v1/wallets/{wallet_id}/withdrawals            # ?status=&limit=&offset=
GET /api/v1/workspaces/{workspace_id}/withdrawals
GET /api/v1/wallets/{wallet_id}/transactions           # deposits and withdrawals
GET /api/v1/workspaces/{workspace_id}/transactions
GET /api/v1/workspaces/{workspace_id}/transaction-details/{transaction_id}

Sign a digest directly

For transactions your own systems build (contract calls, or networks and formats the withdrawal path does not construct) the API can sign a digest with the wallet’s key while keeping the same controls.

Route	Use
POST /api/v1/web3/transaction/{wallet_id}/signTyped	Sign a typed intent. The request is evaluated against policy and, when required, held for approval like a withdrawal.
POST /api/v1/web3/transaction/{wallet_id}/signRaw	Sign an explicit 32-byte digest for a named network. Requires a wallet-bound key with signing:write.
GET /api/v1/web3/{wallet_id}/sign/{signing_id}	Read the status and, when complete, the signature. Requires signing:read.

Signing requests carry their own status and events (signing.created, signing.pending_approval, signing.resumed, signing.rejected, signing.failed). The API signs what it is given; it does not build or broadcast transactions on these routes.