TDAB Partner API

1. Get onboarded. The TDAB team registers an environment for you and hands over everything the integration needs: an API key scoped to your endpoints, your webhook base URL, a signing secret and an outbound auth header, and the X25519 public key you seal bank details against. You send back the public egress addresses your calls will come from: the sandbox admits allowlisted sources only, so nothing works until yours are registered. There is no self-serve signup yet.
2. Create your user. POST /api/create-user with your own externalId, adding the user's wallet address then or later (it must be on file before any deposit mints). externalId must be a UUID.
3. Have the user complete KYC. proposed POST /api/kyc-new with the user's UUID from the previous step, then pass what it returns to your frontend: an sdk_token for the Sumsub SDK embedded in your own app, or a websdk_url you deliver however you already reach your users. Verification (KYC) is not instant. POST /withdraw is refused until the status is verified; POST /deposit is accepted earlier and held as pending_kyc until the verdict lands proposed, see Deposits before the KYC verdict. See KYC verification. Until the main-API route ships, verification runs on its own host with a signed request; the current release documents that flow.
4. Move money. POST /deposit to pull dollars from the user's external bank account (tokens mint automatically when it settles), or POST /withdraw to redeem tokens back to dollars.
5. Track status. Receive webhooks at your registered base URL. With a known deposit ID, poll GET /api/account/deposit?userId=…&id=…; for a withdrawal, poll GET /withdraw/status?intentId=…. See deposit recovery if you missed the deposit ID.

curl -s -X POST "https://api.sandbox.tdab.tech/api/create-user" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalId":"3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d" }'

await fetch("https://api.sandbox.tdab.tech/api/create-user", {
  method: "POST",
  headers: {
    Authorization: process.env.TDAB_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ externalId: "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d" }),
});

import os, requests

requests.post(
    "https://api.sandbox.tdab.tech/api/create-user",
    headers={"Authorization": os.environ["TDAB_API_KEY"]},
    json={"externalId": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d"},
)

{
  "success": true,
  "userId": "usr_2f9c81a0",
  "created": true,
  "updatedFields": [],
  "noopFields": []
}

Every request carries your API key, raw, in the Authorization header:

Authorization: 51h8qzby4uwn…

Keys are scoped by endpoint, not all-or-nothing. Each key carries an allow-list matched against the path you call, with exactly three pattern forms:

A deposits-only partner might hold a key scoped to /deposit and /api/account/deposit, with no access to withdrawals or account info. Keys are issued with least privilege by default.

Every authentication failure, whether the key is missing, unknown, disabled, out of scope for the path, or tied to a disabled environment, returns the same response: 401 with {"error":"Unauthorized"}. The reason is logged server-side but never returned, so a failing integration should check the key value and its scope with the TDAB team rather than parse the body.

# Incorrect: the Bearer prefix causes a 401.
curl -s "https://api.sandbox.tdab.tech/api/account-info?userId=3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d" \
  -H "Authorization: Bearer $TDAB_API_KEY"

await fetch("https://api.sandbox.tdab.tech/api/account-info?userId=3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d", {
  headers: { Authorization: "Bearer " + process.env.TDAB_API_KEY }, // Incorrect: use the raw key.
});

import os, requests

requests.get(
    "https://api.sandbox.tdab.tech/api/account-info?userId=3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
    headers={"Authorization": "Bearer " + os.environ["TDAB_API_KEY"]},  # Incorrect: use the raw key.
)

{ "error": "Unauthorized" }

Register each of your users with TDAB before their first deposit or withdrawal. This call creates the identity record only. KYC and the bank account follow from it, covered in Opening the account.

Upserts by your own externalId, scoped to your environment. Calling it again with new fields updates the record rather than erroring, unless a field conflicts with what is already on file.

Returns 201 on create and 200 on update, with created, updatedFields, and noopFields telling you which happened. A conflict (for example a wallet address already owned by another user) returns 409 with a conflicts array; a malformed wallet address returns 400.

The response userId is TDAB's internal record ID. Keep your original externalId: use it as user_id for KYC and money movement, and as userId for account lookups. Do not substitute the internal response ID in those requests.

curl -s -X POST "https://api.sandbox.tdab.tech/api/create-user" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalId":"3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
       "network":"polygon",
       "walletAddress":"0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C" }'

await fetch("https://api.sandbox.tdab.tech/api/create-user", {
  method: "POST",
  headers: {
    Authorization: process.env.TDAB_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalId: "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
    network: "polygon",
    walletAddress: "0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C",
  }),
});

import os, requests

requests.post(
    "https://api.sandbox.tdab.tech/api/create-user",
    headers={"Authorization": os.environ["TDAB_API_KEY"]},
    json={
        "externalId": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
        "network": "polygon",
        "walletAddress": "0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C",
    },
)

{
  "success": true,
  "userId": "usr_2f9c81a0",
  "created": true,
  "updatedFields": [],
  "noopFields": []
}

{
  "success": false,
  "error": "Field conflict — use separate update endpoints or resolve the conflicting value",
  "userId": "usr_2f9c81a0",
  "conflicts": [{ "field": "walletAddress", "ownerUserId": "usr_7a12ef90" }],
  "noopFields": []
}

KYC verification

TDAB verifies users with Sumsub, and the integration reflects that: the credential you get back is a Sumsub session, and if you embed the flow you are embedding the Sumsub Web SDK. Applicants are created under TDAB's Sumsub account against a TDAB-configured verification level, so you need no Sumsub account, contract or credentials of your own.

Every enrollment works the same way: call the API, get a short-lived credential back, and present it to your user. You choose the form it takes:

• An sdk_token to mount the Sumsub Web SDK inside your app, so the user never leaves your interface and you own the surrounding UX. Sumsub's own Web SDK documentation covers the mount.
• A websdk_url you deliver yourself. Nothing to integrate, and you control how it is delivered.

/api/kyc-existing is the same call with the applicant pre-populated: a share token from your own Sumsub account seeds the applicant with documents your user has already supplied, so the session asks only for what is still missing. It is not a way to skip the session.

Verification is part of the main API and authenticates exactly like every other call on this page proposed: your API key, raw, in the Authorization header, no Bearer prefix and nothing alongside it. Failures return the same 401 with {"error":"Unauthorized"}. See Authentication.

Start verification proposed

Creates the verification session and hands you a short-lived credential for it. You choose the form proposed: a token to feed the Sumsub Web SDK embedded in your own app, so the user never leaves your interface, or a hosted URL you deliver however you already reach your users, in-app, by text, by email. Either way the artifact is yours to hand to your frontend. TDAB sends nothing to your users directly, so all communication with them stays in your product's voice.

Returns exactly one of the two, never both proposed: { "sdk_token": "…" }, or { "websdk_url": "…" } if you asked for that instead. Both point at the same session and both expire 30 minutes after issue, so fetch one when you are ready to use it. Treat either as a session secret: anyone holding it can open that user's verification.

The applicant is created on the first call and reused after that, so calling again for the same user_id resumes the same verification rather than starting a second one. That also means you can call again with the other access_method if the user abandons one route and comes back through another.

Reusing an existing applicant proposed

If your user already verified with Sumsub elsewhere and you hold a share token for them, send it as share_token alongside user_id (same UUID rule), with the same optional access_method. You get back exactly what /api/kyc-new returns.

What transfers is the data, not the decision. The share token hands TDAB's Sumsub the documents and details your user already supplied, so they are not asked for them twice. Everything else is unchanged: your user still opens the session to fill whatever gaps TDAB's level requires, TDAB's Sumsub still verifies the result itself, the status still starts at pending, and the outcome can differ from the approval you already hold.

Verification outcome

Verification is not instant. Approval reaches you as an account event: TDAB opens the user's bank account and pushes its routing and account details to your base URL, once, see Opening the account. Until it arrives, POST /withdraw returns 400 with User KYC not verified. POST /deposit is different proposed: it accepts the deposit and holds it as pending_kyc, then pulls the funds once the account opens, see Deposits before the KYC verdict. A rejected verdict fails any held deposit with kyc_rejected.

A rejection produces no event of its own. No webhook reports a failed verification directly, so a user with nothing in flight who has been rejected looks exactly like one still in progress. Poll for the outcome rather than waiting on an event that never arrives. The one indirect signal is a held deposit proposed: if the user submitted a deposit before the verdict, rejection fails it and you receive a deposit-status event with status: "failed" and errorMessage: "kyc_rejected", see Deposits before the KYC verdict.

To check at any point, or to render progress in your own UI, poll GET /api/kyc-status?userId=… proposed:

The last two matter because both gate money movement: a user can be verified and still not be ready for a deposit.

curl -s -X POST "https://api.sandbox.tdab.tech/api/kyc-new" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id":"3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d" }'

await fetch("https://api.sandbox.tdab.tech/api/kyc-new", {
  method: "POST",
  headers: {
    Authorization: process.env.TDAB_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ user_id: "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d" }),
});

import os, requests

requests.post(
    "https://api.sandbox.tdab.tech/api/kyc-new",
    headers={"Authorization": os.environ["TDAB_API_KEY"]},
    json={"user_id": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d"},
)

{ "sdk_token": "_act-sbx-jwt-..." }

curl -s -X POST "https://api.sandbox.tdab.tech/api/kyc-new" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id":"3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
       "access_method":"websdk_url" }'

{ "websdk_url": "https://in.sumsub.com/websdk/p/sbx_..." }

curl -s -X POST "https://api.sandbox.tdab.tech/api/kyc-existing" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id":"3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
       "share_token":"_act-sbx-share-..." }'

{ "error": "Unauthorized" }

{ "error": "Invalid JSON payload" }

curl -s "https://api.sandbox.tdab.tech/api/kyc-status?userId=3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d" \
  -H "Authorization: $TDAB_API_KEY"

{
  "success": true,
  "userId": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
  "kycStatus": "pending",
  "walletAddressOnFile": true,
  "bankAccountReady": false
}

Self-custody wallets proposed

This section does not apply if TDAB issues the wallets for your users. It applies when your users hold their own keys, for example MetaMask, Ledger or a Safe.

Redeeming burns tokens out of the user's wallet, and the burn contract can only do that against an on-chain ERC-20 allowance. A wallet TDAB issued is recognized and skips that check; a self-custody wallet is not, so without an allowance the burn reverts on-chain and the withdrawal fails late, after the user has already asked for their money.

The allowance is therefore granted once, at linking, rather than per withdrawal. Two calls: ask for the message, then send back the signature.

1. Ask for the message

TDAB builds the message because the signature must cover the spender and the wallet's current on-chain nonce. The spender is a burner vault resolved per token contract, and the nonce is read from the contract at request time.

Returns permitRequired, and when it is true, a permitRequestId, an expiresAt, and a typedData object you can pass straight to eth_signTypedData_v4.

Check permitRequired before prompting. A wallet that already holds the allowance comes back false with nothing to sign, and a user who granted it once should never see the prompt again.

Requests are single-use and expire after 15 minutes. The window is short because the nonce is read at the moment of issue, and any permit accepted for that wallet in between invalidates an outstanding signature. If it lapses, ask for a new one and sign that.

2. Send back the signature

Render the typed data in the user's wallet, then pass the signature to POST /api/create-user as the permit object:

If you hold the user's keys, there is no wallet UI to render. Compute the EIP-712 digest of typedData from the domain, types and message exactly as returned, and sign that 32-byte hash directly with the private key; do not sign it as a text message. The types object carries only Permit, which is the shape typed-data encoders expect. Send back v as 27 or 28, and r and s as 0x-prefixed 32-byte hex.

TDAB submits the permit with the exact values it gave you, so nothing you send back can change what is submitted on-chain. Linking without a valid permit is rejected with PERMIT_REQUIRED: onboarding a user who could never redeem is a worse outcome than a failed link, so this fails closed.

The allowance granted is unlimited and non-decrementing, so it survives every later withdrawal and the user signs once.

curl -s -X POST "https://api.sandbox.tdab.tech/api/permit-request" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "wallet_address":"0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C" }'

await fetch("https://api.sandbox.tdab.tech/api/permit-request", {
  method: "POST",
  headers: {
    Authorization: process.env.TDAB_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ wallet_address: "0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C" }),
});

import os, requests

requests.post(
    "https://api.sandbox.tdab.tech/api/permit-request",
    headers={"Authorization": os.environ["TDAB_API_KEY"]},
    json={"wallet_address": "0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C"},
)

{
  "success": true,
  "permitRequired": true,
  "permitRequestId": "k57f2h9a1b0c",
  "expiresAt": 1787900400000,
  "typedData": {
    "domain": {
      "name": "eUSD",
      "version": "1",
      "chainId": 137,
      "verifyingContract": "0x4d3B..."
    },
    "primaryType": "Permit",
    "types": {
      "Permit": [
        { "name": "owner", "type": "address" },
        { "name": "spender", "type": "address" },
        { "name": "value", "type": "uint256" },
        { "name": "nonce", "type": "uint256" },
        { "name": "deadline", "type": "uint256" }
      ]
    },
    "message": {
      "owner": "0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C",
      "spender": "0x77aE...",
      "value": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
      "nonce": "0",
      "deadline": 1787900400
    }
  }
}

{ "success": true, "permitRequired": false }

// No wallet UI: hash the typed data TDAB returned, then sign the hash.
import { SigningKey, TypedDataEncoder } from "ethers"; // v6

const { domain, types, message } = res.typedData;
const digest = TypedDataEncoder.hash(domain, types, message);
const sig = new SigningKey(userPrivateKey).sign(digest);
// sig.v is already 27 or 28; sig.r and sig.s are 0x-prefixed 32-byte hex.
const permit = { permitRequestId: res.permitRequestId, v: sig.v, r: sig.r, s: sig.s };

// Python (eth_account): encode_typed_data(full_message=res["typedData"]),
// then Account.sign_message(signable, key) gives v (27 or 28), r and s.

curl -s -X POST "https://api.sandbox.tdab.tech/api/create-user" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalId":"3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
       "walletAddress":"0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C",
       "permit": { "permitRequestId":"k57f2h9a1b0c",
                   "v":28, "r":"0x…", "s":"0x…" } }'

{ "success": false, "error": "PERMIT_REQUIRED" }

Registration is the identity step. The account is what follows: the user completes KYC, and TDAB provisions a US bank account on the core ledger. You are notified as each step completes.

• Account registration push. Once the account exists, TDAB POSTs the user's routing and account details to your registered base URL, once. See status updates for the payload.
• Re-fetch on demand. GET /api/account-info?userId=… returns the same routing and account number any time after that, so a missed push is recoverable.

To change a user's preferredNetwork or preferredCurrency later, call POST /api/user/preferences with their userId (your externalId) and whichever field is changing; at least one is required.

curl -s "https://api.sandbox.tdab.tech/api/account-info?userId=3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d" \
  -H "Authorization: $TDAB_API_KEY"

await fetch("https://api.sandbox.tdab.tech/api/account-info?userId=3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d", {
  headers: { Authorization: process.env.TDAB_API_KEY },
});

import os, requests

requests.get(
    "https://api.sandbox.tdab.tech/api/account-info?userId=3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
    headers={"Authorization": os.environ["TDAB_API_KEY"]},
)

{
  "success": true,
  "userId": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
  "accountNumber": "4821009273",
  "routingNumber": "071000301"
}

A deposit pulls dollars from your user's external bank account over ACH (Automated Clearing House) and mints tokens to their wallet once the money settles. You make one call; the mint is never a second call, it happens automatically when the bank leg clears.

Returns 200 with an intentId and a status of pending. The user must already be registered under your environment and have a wallet address on file; either of those missing returns a 400 with a plain-English error. KYC does not have to be complete proposed: a user whose verdict is still undecided gets 200 with status: "pending_kyc" and the deposit is held, while a user who has already been rejected gets 400 with code: "kyc_rejected". Withdrawals are different and still require a verified user.

Deposit lifecycle

The ACH pull is submitted, posts at the bank, the funds are swept into the reserve, and the tokens mint to the user's wallet. You see that as a sequence of deposit-status events:

created → unposted → posted → swept → minted or failed

created proposed means TDAB has accepted the deposit but the ACH pull has not yet been initiated. minted is the terminal success and the only status that carries the on-chain txHash; failed carries an errorMessage. ACH means minutes to days depending on the rail, so build for the pending window rather than a synchronous result.

Deposit lookup and recovery. GET /api/account/deposit?userId=…&id=… returns one deposit. Supply your original externalId as userId and the depositId from a deposit-status event as id. Both parameters are required. This endpoint does not list deposits or accept an intentId or transferId in place of the deposit ID.

Deposit-status events do not contain a traceId, so GET /deposit/status?traceId=… is not a recovery path from those events. If you never received the deposit ID, contact TDAB with your environment, external user ID, transfer_id, and the intentId returned by POST /deposit. Keep those identifiers and do not submit a new transfer ID while the outcome is unknown.

No further action is required for the money to arrive. Once the bank leg clears, the sweep and the mint proceed automatically and you are notified at each step, so the user's balance updates without a second call from you.

Standard ACH settles in about two banking days. Faster handling is possible and depends on the risk and collateral arrangement agreed with you, so treat two days as the default to design against rather than a fixed number.

There is no currency or network listing endpoint. Confirm supported currencies and networks for your production and sandbox environments during onboarding before setting user preferences or initiating money movement.

curl -s -X POST "https://api.sandbox.tdab.tech/deposit" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id":"3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
       "token_symbol":"eUSD",
       "network":"polygon",
       "amount":25000,
       "transfer_id":"your-idempotency-key-001",
       "sealed_bank_details":"c2VhbGVkX2JveF9jaXBoZXJ0ZXh0...",
       "balance":993770,
       "balance_timestamp":"2026-08-31T18:20:34Z" }'

await fetch("https://api.sandbox.tdab.tech/deposit", {
  method: "POST",
  headers: {
    Authorization: process.env.TDAB_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    user_id: "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
    token_symbol: "eUSD",
    network: "polygon",
    amount: 25000,
    transfer_id: "your-idempotency-key-001",
    sealed_bank_details: "c2VhbGVkX2JveF9jaXBoZXJ0ZXh0...",
    balance: 993770,
    balance_timestamp: "2026-08-31T18:20:34Z",
  }),
});

import os, requests

requests.post(
    "https://api.sandbox.tdab.tech/deposit",
    headers={"Authorization": os.environ["TDAB_API_KEY"]},
    json={
        "user_id": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
        "token_symbol": "eUSD",
        "network": "polygon",
        "amount": 25000,
        "transfer_id": "your-idempotency-key-001",
        "sealed_bank_details": "c2VhbGVkX2JveF9jaXBoZXJ0ZXh0...",
        "balance": 993770,
        "balance_timestamp": "2026-08-31T18:20:34Z",
    },
)

{ "intentId": "di_1755781200000_k3f9x", "status": "pending" }

{ "intentId": "di_1755781200000_k3f9x", "status": "pending_kyc" }

{ "success": false, "error": "User KYC rejected", "code": "kyc_rejected" }

Encrypting bank details

sealed_bank_details is a libsodium sealed box (crypto_box_seal: X25519 with a fresh ephemeral keypair per message, XSalsa20-Poly1305), base64-encoded with standard RFC 4648 padding. You seal the user's bank details against TDAB's public key, so only TDAB can open them. No proprietary cryptography is involved, so any standard libsodium binding interoperates.

Seal a compact UTF-8 JSON object with exactly these two string fields. Both are strings so leading zeros survive:

An acknowledgement is not bank-detail validation. Missing or empty sealed_bank_details is rejected with 400. A nonempty payload that cannot be opened or fails the decrypted-field checks can still receive 200 with status: "pending", although it has not produced an ACH pull. Repeating the same transfer_id does not resubmit corrected details. If an intent remains pending without progress, use the deposit recovery procedure before submitting another transfer.

TDAB's public key

TDAB gives you its X25519 public key as a base64 string, 44 characters decoding to exactly 32 bytes. Validate it on load and fail closed if it is missing or malformed: never fall back to sending details unencrypted. Rotation is a configuration change on your side, and because every message uses a fresh ephemeral keypair it needs no coordination beyond the cutover.

Sealed boxes are randomized, so identical details seal to different ciphertexts every time. To check your integration, seal the sample payload and have TDAB confirm it round-trips.

import base64, json
from nacl.public import PublicKey, SealedBox

def seal_bank_details(account_number, routing_number, tdab_pk_b64):
    pk = PublicKey(base64.b64decode(tdab_pk_b64))
    plaintext = json.dumps({
        "account_number": account_number,
        "routing_number": routing_number,
    }, separators=(",", ":")).encode()
    return base64.b64encode(SealedBox(pk).encrypt(plaintext)).decode()

const sodium = require('libsodium-wrappers');

async function sealBankDetails(accountNumber, routingNumber, tdabPkB64) {
  await sodium.ready;
  const pk = sodium.from_base64(tdabPkB64, sodium.base64_variants.ORIGINAL);
  const plaintext = JSON.stringify({
    account_number: accountNumber,
    routing_number: routingNumber,
  });
  const sealed = sodium.crypto_box_seal(sodium.from_string(plaintext), pk);
  return sodium.to_base64(sealed, sodium.base64_variants.ORIGINAL);
}

{"account_number":"1234567890","routing_number":"021000021"}

A withdrawal redeems tokens back to dollars: the tokens leave the user's wallet, and the dollars pay out to their external bank account over ACH. One call is enough, and the request has the same shape as a deposit: the amount and the sealed payout account travel together, and TDAB orchestrates everything after that. proposed

Returns 200 with an intentId, your transferId echoed if you sent one, and a status of pending. An insufficient on-chain balance returns a 400 up front.

If your users hold their own keys, the on-chain allowance that makes the burn possible is granted once at wallet linking, not here. See Self-custody wallets. Passing permit on this call is only a fallback for a wallet that somehow has no allowance, and it covers just that one withdrawal.

curl -s -X POST "https://api.sandbox.tdab.tech/withdraw" \
  -H "Authorization: $TDAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id":"3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
       "token_symbol":"eUSD",
       "network":"polygon",
       "amount":10000,
       "transfer_id":"your-idempotency-key-002",
       "sealed_bank_details":"c2VhbGVkX2JveF9jaXBoZXJ0ZXh0..." }'

await fetch("https://api.sandbox.tdab.tech/withdraw", {
  method: "POST",
  headers: {
    Authorization: process.env.TDAB_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    user_id: "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
    token_symbol: "eUSD",
    network: "polygon",
    amount: 10000,
    transfer_id: "your-idempotency-key-002",
    sealed_bank_details: "c2VhbGVkX2JveF9jaXBoZXJ0ZXh0...",
  }),
});

import os, requests

requests.post(
    "https://api.sandbox.tdab.tech/withdraw",
    headers={"Authorization": os.environ["TDAB_API_KEY"]},
    json={
        "user_id": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
        "token_symbol": "eUSD",
        "network": "polygon",
        "amount": 10000,
        "transfer_id": "your-idempotency-key-002",
        "sealed_bank_details": "c2VhbGVkX2JveF9jaXBoZXJ0ZXh0...",
    },
)

{
  "intentId": "wi_1755781260000_p7q2m",
  "transferId": "your-idempotency-key-002",
  "status": "pending"
}

Serving the payout beneficiary

A withdrawal pays out to the user's bank account, and you are the source of truth for those details. TDAB asks you for them per withdrawal, at the moment of payout, by calling an endpoint you serve.

Serve it at this exact path on your registered base URL. TDAB calls it with your environment's outbound auth header:

The current callback sends an array containing one withdrawal identifier. How you source the account details is up to you: pull them live from whatever bank-linking provider you use, or read them from your own records. TDAB requires only the routing and account number.

This runs before the burn, as a pre-flight check. If you respond that no payout account is available, the withdrawal fails while the user still holds their tokens, so nothing irreversible has happened. A 5xx or a timeout is treated as transient and retried: the withdrawal is held, not failed.

What you return is recorded against that withdrawal, encrypted, so a return or a dispute can be traced back to the account that was actually paid. It is not reused as the destination for a later withdrawal: you are asked again every time, because only you know whether the user has changed banks.

POST {your_base_url}/withdrawal-auth/batch

{ "tx_identifiers": [
    "wi_1755781260000_p7q2m"
] }

{ "results": [
    { "transaction_id": "wi_1755781260000_p7q2m",
      "routing_number": "021000021",
      "account_number": "123456789" }
] }

Withdrawal lifecycle

After the response, TDAB resolves the payout account (the sealed box if the request carried one, otherwise your beneficiary endpoint), burns the tokens, and submits the payout. proposed The payout account is validated before the burn, so an unusable one, including a sealed box that fails to open, fails the withdrawal while the user still holds their tokens. You see the lifecycle as withdrawal-status events:

pending → processing → completed or failed

Several internal steps (payout-account check, burn, in-flight ACH transfer) all report as processing, so expect more than one processing event. completed means the payout actually settled, not that the burn was confirmed on-chain. If the payout account cannot be used, the withdrawal fails before anything irreversible happens.

You can poll the same lifecycle at any time with GET /withdraw/status?intentId=….

Payouts settle over ACH today. RTP and FedNow are coming as additional rails, and batched withdrawals with them. The rail is chosen on the TDAB side, so none of that changes how you call POST /withdraw: build against the status events rather than assuming ACH timing, and you will not need to revisit this when the faster rails become available.

curl -s "https://api.sandbox.tdab.tech/withdraw/status?intentId=wi_1755781260000_p7q2m" \
  -H "Authorization: $TDAB_API_KEY"

await fetch("https://api.sandbox.tdab.tech/withdraw/status?intentId=wi_1755781260000_p7q2m", {
  headers: { Authorization: process.env.TDAB_API_KEY },
});

import os, requests

requests.get(
    "https://api.sandbox.tdab.tech/withdraw/status?intentId=wi_1755781260000_p7q2m",
    headers={"Authorization": os.environ["TDAB_API_KEY"]},
)

{
  "success": true,
  "intent": {
    "intentId": "wi_1755781260000_p7q2m",
    "transferId": "your-idempotency-key-002",
    "status": "processing",
    "amount": 10000,
    "tokenSymbol": "eUSD",
    "network": "polygon",
    "walletAddress": "0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C",
    "createdAt": 1755781260000,
    "updatedAt": 1755781295000
  }
}

Your environment registers one base URL at onboarding. Event notifications POST JSON to the paths below. Callback questions and the diagnostic probe have different header requirements.

Everything TDAB calls on your base URL

You register one baseUrl. The paths below distinguish blocking questions, push notifications, and the diagnostic probe:

A push is a notification: TDAB does not read your response body, and a failure to deliver does not stop anything. A blocking call is a question TDAB waits on, and the answer determines what happens next. If a blocking call fails, the money movement behind it stops rather than proceeding on a guess.

The /webhook/* notifications and /accounts/updated carry an Idempotency-Key derived from the event. Deduplicate those deliveries on that key. The header is not sent on the original account-registration push or the wallet and beneficiary callbacks.

Registration and /user/wallet use your configured outbound auth header and include X-Signature when a signing secret is configured. The beneficiary callback uses the configured outbound auth header and does not generate X-Signature. The diagnostic probe sends neither auth nor event headers. Configure validation separately for each path; the signature example below applies to signed deliveries.

Make account registration idempotent using current_user_id and tdab_partner_account_id. Wallet and beneficiary callbacks must return their JSON answer again when repeated; a duplicate acknowledgement without that answer does not satisfy the callback.

• Idempotency-Key: a stable key per event, so a duplicate delivery is detectable. Dedupe on it rather than assuming exactly-once.
• X-Signature: an HMAC-SHA256 hex digest of the exact request body, keyed with your environment's signing secret. Verify it before trusting the payload: compute the digest over the raw bytes you received (not re-serialized JSON) and compare in constant time; the accompanying example includes a Node implementation. If your environment has no signing secret configured, events arrive unsigned; ask for one.
• Your environment's configured auth header, if one was registered, echoed on event deliveries and the blocking callbacks.

Deposits

Deposit events carry your transfer_id back as transferId, plus the externalUserId and depositId. Store these identifiers for reconciliation. minted is the only status with a txHash; failed carries errorMessage, which is kyc_rejected when a deposit held for KYC fails because the user was rejected (that event's depositId is the intentId) proposed. With a known depositId, GET /api/account/deposit?userId=…&id=… returns the same payload shape. If you never received that ID, follow deposit recovery.

Withdrawals

Withdrawal events wrap the intent in the same shape the /withdraw/status poll returns. Because several internal steps all map to processing, you will receive multiple processing events with distinct idempotency keys; treat them as heartbeats, not duplicates. completed means the fiat payout settled.

Users & accounts

The account-registration push POSTs to your bare base URL (no sub-path) with the user's routing and account details in snake_case; it is also the only event with automatic retries today (up to three total attempts, with waits of 1s and 2s before the second and third attempts; a 4xx response is treated as permanent and not retried). account.verification reports micro-deposits: trust sendingBank for the counterparty; routingNumber in that payload is TDAB's own receiving account by design, not the sender's.

Amount is not one format across events. Check each integration point against the examples rather than assuming one convention.

{
  "depositId": "dep_9f21ac04",
  "intentId": "di_1755781200000_k3f9x",
  "transferId": "your-idempotency-key-001",
  "externalUserId": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
  "status": "minted",
  "amount": "25000",
  "currency": "USD",
  "txHash": "0xa9c3f21e7b6d4c8a0f1e2d3c4b5a69788f0e1d2c3b4a5968f7e6d5c4b3a29180"
}

{
  "success": true,
  "intent": {
    "intentId": "wi_1755781260000_p7q2m",
    "transferId": "your-idempotency-key-002",
    "status": "processing",
    "network": "polygon",
    "txHash": "0xa9c3f21e7b6d4c8a0f1e2d3c4b5a69788f0e1d2c3b4a5968f7e6d5c4b3a29180",
    "fiatTransferId": "ach_9182x"
  }
}

{
  "current_user_id": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
  "tdab_partner_account_id": "j97f2b1c4e8a09d3",
  "beneficiary_name": "Jordan Lee",
  "account_number_last4": "4821",
  "full_routing_number": "071000301",
  "bank_name": "Battle Creek State Bank",
  "account_type": "Primary"
}

{
  "type": "account_verification",
  "verification": {
    "traceId": "achtrc_20260819_0091",
    "externalUserId": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
    "routingNumber": "071000301",
    "accountLast4": "7734",
    "amount": 0.31,
    "sendingBank": "CAPITAL ONE",
    "createdAt": "2026-08-19T09:14:02Z",
    "debitOrCredit": "credit"
  }
}

{
  "externalUserId": "3f9c81a0-7d2e-4b8a-9c1d-5e6f7a8b9c0d",
  "fields": {
    "walletAddress": "0x9F2A1c3De45b8F001B7C4a2D9E6f1234ABCD4B7C"
  },
  "updatedAt": 1755781320000
}

import crypto from "node:crypto";

// rawBody: the exact bytes received.
// Re-serializing the parsed JSON breaks the digest.
function verifySignature(rawBody, header, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(header ?? "", "hex");
  return a.length === b.length &&
    crypto.timingSafeEqual(a, b);
}

There is no cross-endpoint error-code enum. Money-movement and user endpoints return {"success": false, "error": "…"} with a plain-English message; the deposit pull endpoint returns {"error": "…"}. Branch on the HTTP status, and log the message.

{
  "success": false,
  "error": "Amount must be a positive integer (cents) as number or string"
}

{ "error": "Unauthorized" }