Skip to main content
POST
Create a one-off transfer

Authorizations

​
x-api-key
string
header
required

Headers

​
x-idempotency-key
string<uuid>
required

Unique key (UUID) to ensure request idempotency on POST, PUT and PATCH requests.

A key is scoped to your client, the HTTP method and the path, and is remembered for 24 hours after a successful (below 400) response. Repeating the same request (same JSON body, whatever the key order or whitespace) with the same key within that window returns the original response with X-Idempotent-Replayed: true instead of executing the request again. Using the same key on the same endpoint with a different body returns 422 with problem type idempotency-key-reused; the request is not executed. Error responses (4xx and 5xx) are not remembered, so a request refused for a fixable reason can be corrected and retried under the same key. Request bodies that are not JSON (for example file uploads) are not compared.

​
X-Sandbox-Scenario
enum<string>

Sandbox-only. Applies a preset failure or behavior mode for the request, selecting a coherent combination of error step, status, and message. The full set of scenarios is also exposed dynamically via GET /sandbox/scenarios along with descriptions and per-rail applicability. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Available options:
happy_path,
delayed_settlement,
insufficient_funds,
compliance_block,
invalid_account,
provider_maintenance,
network_congestion,
kyb_manual_review,
kyb_rejected,
kyb_expired,
network_timeout,
intermittent_errors,
account_frozen,
document_expired,
invalid_swift,
unauthorized
Example:

"insufficient_funds"

​
X-Sandbox-Error-Step
enum<string>

Sandbox-only. Names the pipeline step at which the injected error fires. Pair with X-Sandbox-Error-Status and (optionally) X-Sandbox-Error-Message to drive a deterministic failure mode at a known point in the request lifecycle. Values longer than 100 characters are ignored. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Available options:
transaction_processing,
compliance_check,
account_validation,
provider_call,
kyb_submission,
kyb_approval,
network_call
Maximum string length: 100
Example:

"provider_call"

​
X-Sandbox-Error-Status
integer

Sandbox-only. Sets the HTTP status code returned when the sandbox injects an error at the configured step (see X-Sandbox-Error-Step). Must be a valid HTTP status code in the range 100-599; values outside that range are ignored. Status codes >= 400 cause the request to short-circuit immediately with a structured error response. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Required range: 100 <= x <= 599
Example:

503

​
X-Sandbox-Error-Message
string

Sandbox-only. Sets the human-readable message field of the injected sandbox error response. Truncated values longer than 500 characters are ignored. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Maximum string length: 500
Example:

"Provider temporarily unavailable for maintenance."

​
X-Sandbox-Instant-Completion
boolean
default:false

Sandbox-only. When true, asynchronous simulation flows complete immediately rather than progressing through their normal timed states. Useful for fast end-to-end test runs that do not need to exercise intermediate webhook events. Accepts true/false (also 1/0, yes/no); other values are treated as false. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Example:

true

Body

application/json

Transaction details.

Request to create a one-off transfer. The transfer type is determined by the destination type referenced by destination_id:

  • Offramp when the destination is a fiat bank account (fiat_us or fiat_iban). destination_payment_rail is honored; destination_network_id is ignored.
  • Swap when the destination is a crypto address. destination_network_id is required and selects the destination chain.

The platform generates a single-use deposit address and finalizes the transfer once the source-asset deposit arrives.

​
customer_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
source_network_id
enum<string>
required

Identifier for a blockchain network

Available options:
ethereum-mainnet,
ethereum-sepolia,
ethereum-goerli,
ethereum-holesky,
solana-mainnet,
solana-devnet,
solana-testnet,
base-mainnet,
base-sepolia,
arbitrum-mainnet,
arbitrum-sepolia,
optimism-mainnet,
optimism-sepolia,
polygon-mainnet,
polygon-amoy
Required string length: 1 - 30
Example:

"ethereum-mainnet"

​
source_asset
string
required

Source crypto asset symbol

Example:

"USDC"

​
destination_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
destination_asset
string
required

Destination asset symbol. For offramps this is a fiat currency (e.g. USD, EUR). For swaps this is the destination stablecoin (e.g. USDC, RD).

Example:

"USD"

​
transaction_type
enum<string>

Transaction type for one-off transaction creation.

Available options:
one_off
Example:

"one_off"

​
amount
string

Optional expected destination amount as a decimal string. When omitted, the resulting transaction's destination amount is populated from the actual deposit once funds arrive. When provided, must be at least 0.01 and is enforced by sandbox amount caps where applicable.

Minimum string length: 1
Pattern: ^[0-9]+(\.[0-9]+)?$
Example:

"1.23"

​
destination_network_id
enum<string>

Identifier for a blockchain network

Available options:
ethereum-mainnet,
ethereum-sepolia,
ethereum-goerli,
ethereum-holesky,
solana-mainnet,
solana-devnet,
solana-testnet,
base-mainnet,
base-sepolia,
arbitrum-mainnet,
arbitrum-sepolia,
optimism-mainnet,
optimism-sepolia,
polygon-mainnet,
polygon-amoy
Required string length: 1 - 30
Example:

"ethereum-mainnet"

​
destination_payment_rail
enum<string>

Optional preferred payment rail for bank transfers (offramp). Ignored when the destination is a crypto address. If not specified, the system will automatically select the most appropriate rail based on the destination's supported methods.

Available options:
ach,
fedwire,
swift,
us_bank_account,
fednow
Example:

"ach"

​
payment_reference
string

Optional payment reference message for bank transfers, carried on the payment as the ACH addenda, the wire message, or the SWIFT remittance information. On SWIFT, whether the payee sees it depends on the receiving bank and any intermediaries. Length limits: ACH 1-18 characters (letters/numbers/spaces), wire 1-140 6-140, SWIFT 5-140 across at most 4 lines of 35 characters (the SWIFT character set: letters, numbers, spaces, and / - ? : ( ) . , ' +).

Required string length: 1 - 140
Example:

"Invoice payment for services"

​
external_id
string

Your own label for this one-off transaction in your system, used to look it up with the external_id filter on GET /transactions. Not unique: Dakota does not reject a duplicate, and several one-off transactions can share one value. It is returned on the transaction and in its transaction.one_off.* webhooks. It is not a payment reference: it is never sent to the bank or the payee, so use payment_reference for text the payee must see.

Maximum string length: 255
Pattern: ^[^\x00-\x1f]*$
Example:

"avenia-ticket-8841"

​
developer_fee_bps
integer<int32>

Developer fee for this transaction in basis points (1 bp = 0.01%). Omitted means no developer fee.

Required range: 0 <= x <= 10000
Example:

50

​
developer_fee_fixed
string

Fixed developer fee for this transaction, in units of the asset deposited (for example 10.00 USDC on a USDC deposit). A decimal string such as "10.00", with at most 2 decimal places. Must be greater than 0. Cannot be combined with developer_fee_bps: send one or the other. The depositor must send the destination amount plus this fee; a deposit that does not cover the fee is not converted.

Example:

"10.00"

Response

One-off transaction created successfully

A one-off transaction response. Used for single-use offramp (crypto-to-fiat) and swap (crypto-to-crypto) transfers; the destination type determines which.

​
id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
resource_type
enum<string>
required

Discriminator field. Always "one_off" for one-off transactions.

Available options:
one_off,
wallet,
auto_account
Example:

"one_off"

​
customer_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
crypto_address
string
required

Temporary address where funds should be sent

Example:

"0x1234567890abcdef1234567890abcdef12345678"

​
status
enum<string>
required

Status of a one-off transaction.

failed means the payment stopped and Dakota is not retrying it. A payout Dakota can still retry stays processing, including while Dakota resolves a problem with it, until it is completed, or cancelled or reversed if Dakota stops it. Do not refund your customer or re-send the payment while it is processing. A failed payout moves again only if Dakota operations recover it by hand (for example an on-chain transfer that reverted); it is then reported as processing and later completed. One-off transactions that reported failed before this behaviour shipped may also move on if Dakota retried them.

An international (SWIFT) wire that the receiving bank returns passes through pending_return and returned, and ends as reversed once the returned funds are refunded to the source wallet. reversed therefore also describes a returned SWIFT payout, not only an ACH originator reversal. SWIFT returns are not refunded automatically: the payout stays at returned until the refund is made.

A payout the bank returned carries a failure_code on returned and on the later reversed: the code mapped from the bank's return code when there is one (for example recipient_account_number_invalid), otherwise payment_returned, with return_reason holding Dakota's message for it. reversal_reason stays empty. A reversed payout with a failure_code but no reversal_reason is therefore a bank return that was refunded, not an ACH originator reversal. Payouts returned before this behaviour shipped may carry no failure_code.

A deduction the bank or an intermediary takes from the returned funds is normally borne by the customer. net_recovered_amount is set once the refund is sized, and only when the customer bore a deduction; it is the face amount less that deduction. On pending_return and returned it is absent whatever came back, so its absence there says nothing about the amount. On a reversed payout that was a bank return, its absence means the customer was refunded in full: either nothing was withheld, or Dakota absorbed the deduction because the refund was made before the bank reported what it returned.

Available options:
pending,
processing,
completed,
failed,
cancelled,
reversed,
pending_return,
returned,
pending_reversal
Example:

"pending"

​
source_network_id
enum<string>
required

Identifier for a blockchain network

Available options:
ethereum-mainnet,
ethereum-sepolia,
ethereum-goerli,
ethereum-holesky,
solana-mainnet,
solana-devnet,
solana-testnet,
base-mainnet,
base-sepolia,
arbitrum-mainnet,
arbitrum-sepolia,
optimism-mainnet,
optimism-sepolia,
polygon-mainnet,
polygon-amoy
Required string length: 1 - 30
Example:

"ethereum-mainnet"

​
source_asset
string
required

Source crypto asset symbol

Example:

"USDC"

​
destination_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
destination_asset
string
required

ISO 4217 symbol representing a fiat asset.

Required string length: 3
Pattern: ^[A-Z]{3}$
Example:

"USD"

​
developer_fee_bps
integer<int32>
required

Developer fee for this transaction in basis points (1 bp = 0.01%), as set by developer_fee_bps on the request. 0 when no developer fee was set. One-off transactions created before this field was introduced also report 0, whatever fee they were created with.

Example:

50

​
created_at
integer
required

Unix timestamp when the transaction was created

Example:

1234567890

​
updated_at
integer
required

Unix timestamp when the transaction was last updated

Example:

1234567890

​
fx_pricing
object

How the FX rate and fee on this transaction were priced. Absent when the transaction has no FX pricing, including every transaction created before it was introduced. Transaction and receipt endpoints omit it when there is none. In events (webhooks, GET /events and webhook history) a transaction.auto.updated or transaction.one_off.updated event carries fx_pricing set to null when the provider withdrew a previously quoted price and nothing replaced it; discard any quoted pricing you hold. The null may also appear when the provider repeats a withdrawal. A final pricing is never withdrawn.

​
fx_outgoing_amounts
object

Version 1 foreign outgoing amount_state unknown, with exact known source amount/currency and destination currency. Not a quote.

​
fx_settlement
object

Version 1 verified outgoing native amounts and bank payout evidence. Absent means settlement amount is unknown.

​
send_amount
string

Amount that should be sent (may be higher than requested amount due to fees)

Example:

"1.24"

​
amount
string

Amount to send to crypto_address. Always equal to send_amount. This is not the amount on the request, which is the destination amount you expect; the requested amount is not returned here (transaction.one_off.* webhooks carry it as destination_amount).

Example:

"1.24"

​
developer_fee_fixed
string

Fixed developer fee for this transaction, in units of the asset deposited, as set by developer_fee_fixed on the request. Absent when no fixed fee was set.

Example:

"10.00"

​
failure_reason
string

Dakota's explanation of why the transaction failed, present if status is failed. Descriptive text for display; use failure_code for logic.

​
failure_code
enum<string>

Stable, machine-readable reason a transaction failed, was returned, or was reversed. Pair it with the human-readable failure_reason, return_reason or reversal_reason, which carry Dakota's message for this code. Switch on failure_code, not on the message text, which may be reworded.

failure_code is not a status: read status for the outcome. A returned payout keeps its code on returned and on the later reversed (the refund to the source wallet); payouts returned before this behaviour shipped may carry none. payment_returned is the code for a return whose bank reason does not map to a more specific value, including a return that carried no bank code at all. A payout that completes after a return (for example a resent wire) or after a rejected ACH reversal has no failure_code.

The set of values is open: Dakota may add codes without a new API version, so treat any value you do not recognize like processing_error. processing_error is the general code for anything not listed; contact support with the transaction ID.

Available options:
recipient_account_not_found,
recipient_account_number_invalid,
recipient_account_blocked,
recipient_account_type_unsupported,
recipient_refused,
recipient_name_mismatch,
recipient_details_missing,
recipient_address_invalid,
recipient_bank_routing_invalid,
recipient_bank_bic_invalid,
limit_exceeded,
payment_reversed_duplicate,
payment_reversed_wrong_recipient,
payment_reversed_wrong_amount,
payment_returned,
processing_error
Example:

"recipient_account_not_found"

​
receipt
object | null

Detailed receipt information for a transaction

​
crypto_details
object | null

Blockchain-specific details for crypto transactions

​
sender_details
object

Originating sender details for onramp/offramp/swap transactions. Populated when source-side metadata is available (e.g., from inbound wire/ACH source data).

​
completed_at
integer

Unix timestamp when the transaction was completed

Example:

1234567890

​
destination_payment_rail
enum<string> | null

The payment rail that was selected for this transaction

Available options:
ach,
fedwire,
swift,
us_bank_account,
fednow
Example:

"ach"

​
payment_reference
string | null

Payment reference message for bank transfers (e.g. wire message, SWIFT remittance information, reference)

​
external_id
string

Your own label for this one-off transaction in your system, used to look it up with the external_id filter on GET /transactions. Not unique: Dakota does not reject a duplicate, and several one-off transactions can share one value. Omitted when none was set.

Example:

"avenia-ticket-8841"

​
destination_bank_name
string

Name of the destination bank

Example:

"Chase Bank"

​
destination_account_holder_name
string

Name of the account holder at the destination bank

Example:

"Acme Corporation"

​
destination_account_number_last_four
string

Last four digits of the destination account number

Example:

"6789"

​
destination_routing_number
string

ABA routing number for US bank accounts

Example:

"021000021"

​
destination_iban
string

IBAN for international bank accounts

Example:

"GB82WEST12345698765432"

​
destination_bic
string

BIC/SWIFT code for international transfers

Example:

"BARCGB22XXX"

​
return_code
string

Return code (e.g., R01) when the transaction was returned by the receiving bank. NACHA/Fedwire codes for US bank rails; international (SWIFT) wire returns carry no NACHA code and may return a reduced amount after intermediary fees. A return can arrive with no code; failure_code is still set (to payment_returned). Cleared if the transaction later completes.

Example:

"R01"

​
return_reason
string

Dakota's explanation of why the payment was returned. Descriptive text for display; use failure_code for logic.

Example:

"The recipient account could not be found."

​
return_initiated_at
integer

Unix timestamp when the return was initiated.

Example:

1234567890

​
return_deadline
integer

Unix timestamp deadline for return processing.

Example:

1234567890

​
net_recovered_amount
string | null

Decimal amount recovered when a returned payout came back short and the customer bore the deduction, denominated in the transaction's own currency (the same basis as its face amount), so face amount minus this value is what the customer went without. Present only in that case; it never means zero. It is set once the refund to the source wallet has been sized. It is absent on pending_return and returned whatever came back, can first appear on pending_reversal, and stays on reversed. After the refund is sized, absence means the customer was refunded the face amount in full, because the whole amount came back, Dakota absorbed the bank's deduction (a refund made before the bank reported what it returned), or the rail reports no net figure (ACH never does). Cleared, like the other return fields, if the payout later completes (for example a returned wire that was resent and delivered).

Example:

"24955"

​
reversal_reason
string

ACH reversal reason when the originator reverses the transaction (e.g., duplicate, receiver_incorrect). Not set for an international (SWIFT) wire that the receiving bank returned: that payout ends as reversed once the funds are refunded to the source wallet, reversal_reason stays empty, and failure_code (the mapped bank code, or payment_returned) says it was returned. net_recovered_amount carries the face amount less the bank's deduction when the customer bore one, and return_code the bank's code when it sent one. Cleared if the transaction later completes (the bank rejected the reversal).

Example:

"duplicate"

​
reversal_initiated_at
integer

Unix timestamp when the reversal was initiated. Cleared if the transaction later completes (the bank rejected the reversal).

Example:

1234567890

​
customer_name
string

Display name of the customer associated with this transaction.

Example:

"Acme Corp"