V3 transactions
Use V3 to preview a quote, create a deposit or withdrawal, follow its funding instructions, and read its outcome. Confirm your account’s API access, eligible routes, and integration environment with Adesic support before sending requests that create transactions. The examples use the production hostname and illustrative IDs; replace them with your own authorized account resources.
Authentication and account scope
Send the account’s API key in the api-key header on every request. Keep it on
your server and out of URLs, browser code, and logs. Quote and creation bodies
must use Content-Type: application/json. An optional x-correlation-id must be
a UUID; retain the returned request identity for support.
The API key determines the account. V3 transaction requests do not accept a
subAccountId override. A master account’s key does not select a subaccount by
adding fields to the request. Confirm the appropriate credentials and account
eligibility before integrating customer or subaccount flows.
Use existing wallet and bank-account resource IDs belonging to that account. Resources must be eligible for the selected route; listing a resource does not guarantee it can execute a transaction.
Create a transaction
POST /v3/transactions creates a transaction and may create payment resources.
It requires a UUID Idempotency-Key. Generate one for each new transaction intent
and persist it with the request before sending. Reuse that key and the same
payload when recovering that intent; do not generate a new key after a timeout.
This withdrawal sends a fixed amount of USDC from a wallet to a USD bank account:
curl --request POST 'https://api.adesic.com/v3/transactions' \
--header 'api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: YOUR_PERSISTED_UUID' \
--data '{
"type": "WITHDRAWAL",
"send": {
"amount": "1000.00", "asset": "USDC", "network": "ethereum",
"walletId": "wal-123456785"
},
"receive": {
"asset": "USD", "rail": "wire", "bankAccountId": "bac-123456788"
}
}'For a deposit, the bank account funds USD and the wallet receives crypto. Use this body with the same endpoint and a new persisted UUID for the new intent:
{
"type": "DEPOSIT",
"send": {
"amount": "1000.00", "asset": "USD", "rail": "wire",
"bankAccountId": "bac-123456788"
},
"receive": {
"asset": "USDC", "network": "ethereum", "walletId": "wal-123456785"
}
}As with quotes, supply a positive decimal-string
amount on exactly one side, with at most two decimal places. For a send-fixed
request, you may add receive.minimumAmount; for a receive-fixed request, you
may add send.maximumAmount. These positive decimal strings also allow at most
two decimal places. A breached limit returns PRICE_PROTECTION_FAILED rather
than accepting changed economics.
A newly created transaction returns 201 Created; a successful replay can return
200 OK. Retain its public id (txn-…), status, authoritative send and
receive amounts, exchangeRate, fees, and timestamps. A replay can report the
transaction’s later state. Do not interpret HTTP success as completed settlement.
Optional withdrawal context
Withdrawals may include purpose: { "category": "bills" }. The categories are
gift, bills, groceries, travel, health, entertainment, housing,
school-fees, and other. other requires a description.
When supporting documents are needed, upload each to
POST /v3/transactions/documents using multipart/form-data: one file, a
documentType (invoice, contract, agreement, purchase_order, or other),
and an optional description. PDF, JPEG, and PNG files up to 10 MiB are accepted.
Use the returned public document IDs in the withdrawal’s documents array
(one to three distinct IDs), or omit the array. Deposit requests do not accept
documents. Documents must belong to the authenticated account.
Fund and follow the transaction
Fund only after receiving usable funding instructions for the transaction in
AWAITING_FUNDS, and check expiresAt before sending. Use the returned amounts
and exact instructions; a quote is not a funding instruction.
- For a withdrawal,
fundingidentifies the cryptoasset,network,address, and optionalmemo. Send the required amount on that network and include the memo when present. - For a deposit,
fundingsupplies the USD rail, bank and beneficiary details, account and routing numbers, and anyreferenceorinstruction. Follow these instructions from the selected funding bank account.
Read a transaction with its ID and the same account’s API key:
curl 'https://api.adesic.com/v3/transactions/txn-123456789' \
--header 'api-key: YOUR_API_KEY'Continue reading the detail after funding. COMPLETED confirms completion;
intermediate states such as PENDING, IN_REVIEW, or rail-specific processing
states do not. Inspect any returned failure and contact support for unresolved
outcomes. Do not resend funds because a read is delayed or a transaction is under
review. Do not fund an expired or canceled transaction.
List transactions and historical activity
GET /v3/transactions?limit=25 returns { "transactions": [...], "nextCursor": ... }.
Pass nextCursor back as cursor to continue, keeping filters unchanged. Its
absence means there is no next page. limit defaults to 25 and accepts 1–100.
Optional type filters are DEPOSIT, WITHDRAWAL, and TRADE; status accepts
a transaction status. Send each query parameter once.
The same list and detail routes include supported historical V2 transactions.
Historical records may omit economics or execution details that were never
recorded. Treat absent values as unavailable, not zero, and do not assume a
historical record has actionable funding instructions. Reading a historical
TRADE does not enable creating a new trade.
Cancel a transaction
POST /v3/transactions/:id/cancel must have no request body, including no
empty JSON object:
curl --request POST 'https://api.adesic.com/v3/transactions/txn-123456789/cancel' \
--header 'api-key: YOUR_API_KEY'Cancellation is conditional on the latest funding and processing evidence. A
withdrawal detail may include cancellation.allowed; even when true, the server
rechecks eligibility on submission. A successful response is 200 OK with the
transaction. Check its returned status. A refused or unavailable cancellation
does not mean the transaction was canceled. Read its state again and do not
fund while resolving an uncertain cancellation.
Errors and retries
V3 errors normally contain error.code, error.message, and error.requestId;
creation errors may also include error.transactionId. Keep those identities
with your persisted idempotency key. Transport failures can occur without an
API error body.
| Response | Action |
|---|---|
400 invalid request, precision, route, or UUID | Correct the request. Send only supported fields and exactly one fixed amount. |
401 INVALID_API_KEY or 403 ACCOUNT_NOT_ELIGIBLE / PAYMENT_RAIL_NOT_AVAILABLE | Resolve credentials, account approval, or rail eligibility. |
409 IDEMPOTENCY_CONFLICT | The key was used for a different intent. Reconcile the original transaction before intentionally creating another. |
409 PRICE_PROTECTION_FAILED | Request a fresh quote and obtain acceptance of any changed intent before submitting it. |
409 ACCOUNT_USAGE_CHANGED | Retry the same creation request with its original key. |
409 DEPOSIT_ROUTE_CONFLICT | Resolve the existing awaiting-funds deposit before requesting a different receiving route. |
422 RESOURCE_NOT_EXECUTABLE | Select eligible account resources before creating a new intent. |
Timeout, 504 PROVIDER_OUTCOME_UNKNOWN, or temporary 503 | The outcome may be uncertain. Retain any transaction ID, read it when available, and recover creation with the same key and payload. Never rotate the key to bypass uncertainty. |
409 TRANSACTION_NOT_CANCELABLE / CANCELLATION_CONFLICT or 503 CANCELLATION_UNAVAILABLE | Read the latest transaction; do not assume cancellation succeeded. |
Use retries with backoff and an attempt limit for temporary failures and rate limits. If the outcome remains unclear, contact support with the request and transaction IDs; do not include your API key.
Migrating from V2
V2 transaction quote, create, list, detail, and cancel endpoints are retired.
Use V3 type, send, and receive requests and explicit idempotency instead of
V2 order-shaped bodies. Use the V3 reads above for historical activity.
The wallet, bank-account, subaccount, crypto-catalog, and blockchain-catalog
resource endpoints under /v2/transactions remain available. Continue using
Wallets,
Bank Accounts, and
Subaccounts for those resources; their presence
does not restore V2 transaction execution or grant V3 subaccount delegation.