Crypto custody & compliance · engineering reference
A provider should be mapped into your model—not allowed to become it. Your immutable transaction ID, policy decision, ledger, polling reconciler, and exit package remain authoritative.
A custody platform sells you signing, key storage, and chain coverage. It does not sell you a wallet system. This sheet is about the seam between their API and your ledger, which is where the integration bugs live.
Threshold-signing implementation and its audit burden, HSM and enclave operations, and the pace of adding new chains. It removes approximately none of the ledger, deposit detection, reconciliation, nonce management, compliance placement, or the withdrawal pipeline.
Trusting webhooks. They arrive at least once, out of order, and sometimes not at all. Treat a webhook as a hint that something changed, and let a polling reconciler be the thing that decides what is true.
A create call that times out has an unknown outcome. It may already have been accepted. Without a key on the request, your retry is a second withdrawal.
It is the one place your own code sits inside the signing path. It lets you check that the transaction being signed matches the intent your ledger recorded, which is the only real defence against a compromised caller holding valid credentials.
If you remember one lineThe webhook is a hint. The reconciler is the source of truth.
A provider should be mapped into your model, not allowed to become it. These cardinalities are the anti-corruption layer.
Persist internal ID and ledger hold.
Send external/idempotency ID once.
Provider policy + independent callback.
Exact decoded payload only.
Webhook v2 into durable queue.
Poll provider + chain; settle actuals.
one internal intent → 0..n API attempts → 0..n chain hashes → exactly one final ledger outcome
The cardinality mismatch between your ledger and a provider API is where duplicate and lost withdrawals live.
Vendor terminology is dated August 2026. Build an anti-corruption layer so your ledger and state machine do not inherit vendor names.
| Generic concept | Fireblocks | BitGo | Coinbase Prime | Build invariant |
|---|---|---|---|---|
| Custody container | Vault account / asset wallet | Wallet / enterprise | Portfolio / wallet / address group | Your internal account ID remains authoritative |
| Transfer intent | Transaction + externalTxId | Transfer / send request | Onchain transaction | Client idempotency ID before API call |
| Policy | Policies / TAP terminology | Wallet/enterprise policy + webhook rule | Portfolio/user controls | Default deny in your domain too |
| Signer hook | API Co-Signer callback | Webhook policy / signing architecture | Platform-managed API flow | Independent payload-vs-ledger validation |
| Event | Webhook v2 transaction events | Wallet/transfer webhooks | WebSocket/REST state | Hint only; reconciler is truth |
| Chain evidence | txHash + status/subStatus | Transfer hash/state | Transaction state | Many hashes may map to one intent |
Read, create, approve/sign, policy-admin, and workspace-admin capabilities belong in different keys and stores.
Concrete use: A reconciler key can list transactions but cannot create or approve one.
Failure mode: One omnipotent key turns a reporting host into a withdrawal host.
Bind method, path, body hash, nonce/time, and short expiry to the caller identity.
Concrete use: Hash raw JSON bytes, issue JWT jti=req_8291, and reject clock skew outside the documented window.
Failure mode: Re-serializing JSON can change the signed bytes.
Generate and persist the client external ID before the first network attempt.
Concrete use: Retry wd_8291 after timeout and query by the same ID before any second create.
Failure mode: A timeout has unknown outcome; blind retry can pay twice.
Verify webhook signature and timestamp over exact received bytes before parsing.
Concrete use: Queue the verified envelope, return 2xx quickly, then process asynchronously.
Failure mode: Signing parsed JSON breaks when whitespace/key order changes.
Deduplicate event IDs, tolerate reordering, and compare polled authoritative state.
Concrete use: A late PENDING_SIGNATURE event cannot regress a locally reconciled COMPLETED transaction.
Failure mode: Webhook arrival order is not transaction order.
No events can mean no activity or a broken integration; only polling distinguishes them.
Concrete use: Poll every 60 seconds and alert when webhook silence exceeds 5 minutes while state changes exist.
Failure mode: A green HTTP endpoint does not prove events are arriving.
Fireblocks primary status and sub-status enums change. Parse unknown values safely, retain raw payload, and alert instead of crashing or treating unknown as success.
| Status family | Meaning | Terminal? | Ledger action | Operator focus |
|---|---|---|---|---|
| SUBMITTED / PENDING_* | Created; policy/approval/signing work remains | No | Reserve/hold only | Read exact current status and subStatus |
| QUEUED | Waiting for processing/resource | No | Keep hold | Queue age and dependency |
| BROADCASTING | Submission in progress | No | Keep hold; no settlement | Unknown hash/outcome window |
| CONFIRMING | On chain, confirmation policy pending | No | Attach hash/version | Reorg and replacement |
| COMPLETED | Provider completion criteria met | Yes for provider flow | Settle actual amount/fee after reconciliation | Verify chain evidence |
| BLOCKED | Policy/compliance stopped | Yes unless new intent | Release/retain hold per case | Rule number / sanctions context |
| REJECTED | User, AML, or workflow rejection | Yes | Release hold | Sub-status is the explanation |
| CANCELLED | Cancelled before completion | Yes | Release only after chain query | May have prior hash/state |
| FAILED | Provider/chain operation failed | Yes for this attempt | Reconcile; compensating entry | Fee, nonce, connectivity, authorization |
These are documented Fireblocks examples as read August 2026. Always store unknown sub-status strings verbatim.
| Sub-status | Likely domain | Response |
|---|---|---|
| BLOCKED_BY_POLICY | Policy order / sanctions | Record rule, do not mutate policy to force retry |
| AUTHORIZATION_FAILED | API Co-Signer callback | Check authentication and callback availability |
| REJECTED_AML_SCREENING | Compliance | Freeze/route case; preserve provider evidence |
| AUTO_FREEZE | Transaction screening | Treat as blocked-property workflow |
| ADDRESS_WHITELISTING_SUSPENDED | Destination activation | Wait for configured activation; never bypass |
| ACTUAL_FEE_TOO_HIGH | Fee policy / market | Re-estimate within ceiling; create linked attempt |
| AMOUNT_TOO_SMALL | Dust/minimum/net fee | Reject before provider call using adapter limits |
| 3RD_PARTY_PROCESSING | Exchange/network dependency | Poll provider and third party; do not duplicate |
| ON_PREMISE_CONNECTIVITY_ERROR | Self-hosted component | Fail closed and execute co-signer failover |
Your code compares decoded vendor request to the immutable ledger intent before allowing the co-signer share to act.
Concrete use: Require exact chain, source, destination, asset, amount, fee ceiling, case ID, and policy version.
Failure mode: If callback and transaction creator share one credential/host, the independence is cosmetic.
Callback uptime becomes withdrawal signing uptime, so failure must be observable and closed.
Concrete use: Deploy across two fault domains, use bounded timeouts, and test that timeout rejects rather than approves.
Failure mode: A fail-open callback nullifies the strongest integration control.
Fireblocks can auto-fuel EVM vault accounts so token sweeps have native gas.
Concrete use: Enable autoFuel only on intended deposit vaults; monitor source balance and unexpected funding volume.
Failure mode: The gas source can run dry exactly when sweep backlog peaks.
Provider disappearance is a designed failure, not a contract footnote.
Concrete use: Restore keys/shares, derivation data, policies, address inventory, pending transactions, and audit evidence in isolation.
Failure mode: Key export without path and address metadata may be unusable.
No ranking or pricing. Capabilities are product/configuration specific and must be reverified in public docs and contracts; absence from a public page is not evidence of absence.
| Platform | Public integration surface | Custody/signing model to verify | Policy/signer hook | Exit question |
|---|---|---|---|---|
| Fireblocks | REST/SDK + Webhooks v2 | MPC-CMP / workspace configuration | Policies + API Co-Signer callback | Can customer reshare/export each wallet class? |
| BitGo | REST SDK + webhooks | Multisig/TSS by product | Wallet policies + webhook policy | Which keys and metadata remain customer-held? |
| Coinbase Prime | REST/FIX/WebSocket | Qualified-custody/platform paths | Portfolio/user controls | How are wallets and transaction history exported? |
| Copper | Public docs/API where available | MPC/custody product-specific | Verify documented policy hook | Independent recovery/export package? |
| Anchorage Digital | Public API/docs where available | Institutional custodian | Verify programmatic approval surface | Asset return and history format? |
| Dfns | API + webhooks | Wallet-as-a-service MPC | Policy/approval surface | Key export/reshare per network? |
| Turnkey | API + policy engine | Secure enclave / sub-organization model | Signed policy operations | Root quorum and export path? |
| Safe | Smart-contract accounts + SDK | On-chain owner threshold | Modules/guards | Can owners operate without hosted service? |
| Self-build | Your API | Chosen open protocol + HSM/enclave | Your policy/callback | You own every audit and chain adapter |
Buying signing infrastructure does not buy your ledger, reconciler, compliance placement, nonce allocator, support operation, or exit plan.
Failures that pass a vendor demo. Expand each for the control and the reason it fails.
Delivery can duplicate, reorder, delay, or disappear.
Concrete use: Poll and reconcile.
Failure mode: Exactly-once is an application invariant, not a transport guarantee.
The verified bytes differ from received bytes.
Concrete use: Capture raw body first.
Failure mode: Framework middleware often destroys the evidence.
The actionable reason is discarded.
Concrete use: Persist and route both.
Failure mode: “Failed” cannot tell fee from policy from co-signer outage.
Contractual capability may not restore a live wallet.
Concrete use: Execute isolated exit annually.
Failure mode: Vendor failure is the worst time to discover format gaps.
Operational and volatile claims were checked against these first-party documents on 2026-08-31. Examples are illustrative controls, not legal, investment, or vendor-selection advice.