Skip to main content
POST

Authorizations

ā€‹
x-api-key
string
header
required

Headers

ā€‹
x-idempotency-key
string<uuid>
required

Unique key to ensure request idempotency. If the same key is used within a certain time window, the original response will be returned instead of executing the request again.

ā€‹
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
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."

Body

application/json

Unified account create request for onramp/offramp/swap.

One schema serves all three account types, so its properties are the UNION of the three shapes: account_type decides which of them are read. account_type is therefore the only field this schema can mark required ā€” everything else is required per type, and that contract is this table:

"Ignored" means the field is accepted and has no effect ā€” sending it does not create the routing it names, so do not rely on it. The one exception is payment_reference, which is REJECTED rather than ignored on the types that cannot deliver it (see that field).

rail on an onramp is optional because the account's inbound rails come from capabilities. swift and sepa must appear in capabilities and narrow the account to that rail. ach, fedwire and fednow must also appear in capabilities, but all resolve to us_bank_account ā€” the same result as omitting rail when the capabilities include a US rail. us_bank_account itself is accepted as rail regardless of the capabilities list.

A required field that you omit returns 400 (invalid-request or invalid-identifier, depending on the field), with a detail that identifies the problem.

ā€‹
account_type
enum<string>
required

Unified account family for account resources.

Available options:
onramp,
offramp,
swap
Example:

"onramp"

ā€‹
capabilities
enum<string>[]

List of payment capabilities supported by a rail. Multiple values may be supplied; the list is not limited to one entry. Which values are valid depends on the resource: on-ramp accounts accept any rail and expand us_bank_account to ach and fedwire; IBAN destinations accept swift and sepa only.

Minimum array length: 1

Type of payment rail capability supported. For onramp accounts, us_bank_account indicates the account accepts ACH, Wire (Fedwire), and FedNow deposits interchangeably. fednow is the FedNow instant US-domestic USD rail for payouts and deposits ā€” $500k per-transaction cap on payouts; a payout destination whose bank cannot receive FedNow is rejected at account creation with problem type https://docs.dakota.xyz/api-reference/errors#fednow-destination-unreachable ā€” route that destination over ach instead. swift is the international USD wire rail: gated on the customer's international_wire capability, USD only, payouts target fiat_iban destinations, and deposit instructions carry the BIC and the beneficiary address. Intermediary banks may deduct fees en route, so the amount received can be lower than the amount sent. sepa is not currently offered.

Available options:
ach,
fedwire,
swift,
us_bank_account,
fednow
Example:
ā€‹
rail
enum<string>

Type of payment rail capability supported. For onramp accounts, us_bank_account indicates the account accepts ACH, Wire (Fedwire), and FedNow deposits interchangeably. fednow is the FedNow instant US-domestic USD rail for payouts and deposits ā€” $500k per-transaction cap on payouts; a payout destination whose bank cannot receive FedNow is rejected at account creation with problem type https://docs.dakota.xyz/api-reference/errors#fednow-destination-unreachable ā€” route that destination over ach instead. swift is the international USD wire rail: gated on the customer's international_wire capability, USD only, payouts target fiat_iban destinations, and deposit instructions carry the BIC and the beneficiary address. Intermediary banks may deduct fees en route, so the amount received can be lower than the amount sent. sepa is not currently offered.

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

"ach"

ā€‹
crypto_destination_id
string

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"

ā€‹
fiat_destination_id
string

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_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"

ā€‹
source_network_id
string

Source network ID or wildcard network for crypto input.

Example:

"ethereum-mainnet"

ā€‹
source_asset
string

Asset to send into the account.

Minimum string length: 1
Example:

"USDC"

ā€‹
destination_asset
string

Asset to receive at the destination.

Minimum string length: 1
Example:

"USDC"

ā€‹
return_address
Crypto Resource Identifier Ā· object

A unique identifier for a specific account on a specific blockchain. When rendered as a string, it has the syntax: :// (e.g., ethereum-mainnet://0x165cd37b4c644c2921454429e7f9358d18a45e14)

ā€‹
return_crypto_address
Crypto Resource Identifier Ā· object

A unique identifier for a specific account on a specific blockchain. When rendered as a string, it has the syntax: :// (e.g., ethereum-mainnet://0x165cd37b4c644c2921454429e7f9358d18a45e14)

ā€‹
developer_fee_bps
integer<int32>

Developer fee in basis points (1 bp = 0.01%).

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

50

ā€‹
max_transactions
integer<int32>

Hard cap on how many transactions this account may ever create. A transaction is one convert-and-forward of funds received at the account through to its destination, so 1 makes the account a one-off and N lets one account serve N payments.

Omit for the default, which is unchanged: the account is uncapped and keeps sweeping every deposit indefinitely (a durable, standing account).

Reaching the cap refuses further deposits; it does not turn the deposit details off. Once the cap is used up:

  • Deposits sent to the account are refused. They are not returned to the sender ā€” the funds still arrive and are then held pending manual intervention. Nothing is converted, nothing is forwarded, and no transaction appears on the account for them. Stop sending to the deposit details once the cap is reached.
  • The account is closed and stops serving new payments.
  • This is not recoverable through this API. max_transactions is immutable ā€” it cannot be raised, and a closed account cannot be reopened ā€” so a capped-out account is finished. Create a new account (with new deposit details) to keep receiving.

A slot is consumed by any transaction in flight or delivered, not only a successful one. A slot is released only when a transaction ends with the value not staying with the recipient: canceled, rejected, reversed, or refunded. A failed or returned transaction keeps its slot, because its funds are still held and it can still be retried, until it is refunded. Size the cap against the number of deposits you expect, not the number of successes you need. Releasing a slot does not reopen a closed account.

The cap is checked as each deposit arrives, so deposits that race each other can briefly overshoot N; the account closes on the next one.

Required range: x >= 1
Example:

1

ā€‹
payment_reference
string

Reference carried on the outbound fiat transfers this account makes. It is passed through to the bank as the payment's reference ā€” the wire message to the creditor, or the ACH addenda ā€” so it is what the payee sees against the credit. Some payees and rails require one to reconcile an incoming payment at all.

This is ACCOUNT-LEVEL, unlike the payment_reference on a one-off transaction, which is per payment: EVERY sweep out of this account carries the SAME reference. If each payment needs its own reference, use a one-off transaction, or one account per reference.

Only an outbound FIAT leg carries it, so this applies to offramp accounts. Setting it on an onramp or swap account is REJECTED with a 400: those sweep to a crypto address, where no reference is delivered, so accepting it would store a value the payee can never see. On SWIFT the reference is carried as the wire's remittance information; whether the payee sees it depends on the receiving bank and any intermediaries, so do not rely on it for payee-side reconciliation. ACH and wire (fedwire, us_bank_account) deliver it as the addenda / wire message.

Validated against the account's rail with the same per-rail rules as a one-off's payment_reference ā€” ACH at most 18 characters and letters/numbers/spaces only, wire (fedwire, us_bank_account) at most 140 characters 6-140, SWIFT 5-140 across at most 4 lines of 35 characters (letters, numbers, spaces, commas, and periods only).

Omit for the default, which is unchanged: no reference is attached. An empty string means the same thing and is accepted ā€” a client that always sends the field should not have to omit it to say "none", and an empty value must never be the thing that rejects an otherwise valid crypto account.

Maximum string length: 140
Example:

"Invoice 12345"

Response

Account created successfully.

Unified account response for onramp/offramp/swap.

ā€‹
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"

ā€‹
account_type
enum<string>
required

Unified account family for account resources.

Available options:
onramp,
offramp,
swap
Example:

"onramp"

ā€‹
bank_account
Bank Account Ā· object

Unified schema for bank accounts.

ā€‹
destination
Crypto Destination Response Ā· object

Response for a crypto destination.

ā€‹
source_crypto_address
string

Source crypto address for offramp/swap accounts.

Example:

"0x1234"

ā€‹
source_family
enum<string>

Blockchain family for the crypto account.

Available options:
evm,
solana
Example:

"evm"

ā€‹
source_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"

ā€‹
source_asset
string

Asset sent into the account.

Example:

"USDC"

ā€‹
destination_asset
string

Asset received at the destination.

Example:

"USDC"

ā€‹
rail
enum<string>

Type of payment rail capability supported. For onramp accounts, us_bank_account indicates the account accepts ACH, Wire (Fedwire), and FedNow deposits interchangeably. fednow is the FedNow instant US-domestic USD rail for payouts and deposits ā€” $500k per-transaction cap on payouts; a payout destination whose bank cannot receive FedNow is rejected at account creation with problem type https://docs.dakota.xyz/api-reference/errors#fednow-destination-unreachable ā€” route that destination over ach instead. swift is the international USD wire rail: gated on the customer's international_wire capability, USD only, payouts target fiat_iban destinations, and deposit instructions carry the BIC and the beneficiary address. Intermediary banks may deduct fees en route, so the amount received can be lower than the amount sent. sepa is not currently offered.

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

"ach"

ā€‹
destination_rail
enum<string>

Type of payment rail capability supported. For onramp accounts, us_bank_account indicates the account accepts ACH, Wire (Fedwire), and FedNow deposits interchangeably. fednow is the FedNow instant US-domestic USD rail for payouts and deposits ā€” $500k per-transaction cap on payouts; a payout destination whose bank cannot receive FedNow is rejected at account creation with problem type https://docs.dakota.xyz/api-reference/errors#fednow-destination-unreachable ā€” route that destination over ach instead. swift is the international USD wire rail: gated on the customer's international_wire capability, USD only, payouts target fiat_iban destinations, and deposit instructions carry the BIC and the beneficiary address. Intermediary banks may deduct fees en route, so the amount received can be lower than the amount sent. sepa is not currently offered.

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

"ach"