Skip to Content
APIsTransactions

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, funding identifies the crypto asset, network, address, and optional memo. Send the required amount on that network and include the memo when present.
  • For a deposit, funding supplies the USD rail, bank and beneficiary details, account and routing numbers, and any reference or instruction. 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.

ResponseAction
400 invalid request, precision, route, or UUIDCorrect the request. Send only supported fields and exactly one fixed amount.
401 INVALID_API_KEY or 403 ACCOUNT_NOT_ELIGIBLE / PAYMENT_RAIL_NOT_AVAILABLEResolve credentials, account approval, or rail eligibility.
409 IDEMPOTENCY_CONFLICTThe key was used for a different intent. Reconcile the original transaction before intentionally creating another.
409 PRICE_PROTECTION_FAILEDRequest a fresh quote and obtain acceptance of any changed intent before submitting it.
409 ACCOUNT_USAGE_CHANGEDRetry the same creation request with its original key.
409 DEPOSIT_ROUTE_CONFLICTResolve the existing awaiting-funds deposit before requesting a different receiving route.
422 RESOURCE_NOT_EXECUTABLESelect eligible account resources before creating a new intent.
Timeout, 504 PROVIDER_OUTCOME_UNKNOWN, or temporary 503The 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_UNAVAILABLERead 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.

© Adesic LLC. All Rights Reserved