Skip to main content
POST
Create an account

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.

ā€‹
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. Currently, as input, you can only request one in this list. This constraint will be loosened in the future.

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.

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.

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. SWIFT is validated but NOT delivered: a SWIFT transfer carries no payment reference at all, and a one-off is no different ā€” both reach the same send path, which has nowhere to put one. Do not plan on a reference reaching a SWIFT payee by any route today. ACH and wire (fedwire, us_bank_account) do deliver it.

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. A swift account validates the value but, per above, never delivers it.

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.

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.

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

"ach"