Skip to main content
POST
/
transactions
Create a one-off transfer
curl --request POST \
  --url https://api.platform.dakota.xyz/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "transaction_type": "one_off",
  "amount": "1.23",
  "customer_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
  "source_network_id": "ethereum-mainnet",
  "source_asset": "USDC",
  "destination_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
  "destination_network_id": "ethereum-mainnet",
  "destination_asset": "USD",
  "destination_payment_rail": "ach",
  "payment_reference": "Invoice payment for services"
}
'
{
  "id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
  "resource_type": "one_off",
  "customer_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
  "crypto_address": "0x1234567890abcdef1234567890abcdef12345678",
  "send_amount": "1.24",
  "status": "pending",
  "amount": "1.23",
  "source_network_id": "ethereum-mainnet",
  "source_asset": "USDC",
  "destination_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
  "destination_asset": "USD",
  "receipt": {
    "imad": "string",
    "omad": "string",
    "input": {
      "amount": "string",
      "asset": "string",
      "network": "string"
    },
    "subtotal": {
      "amount": "string",
      "asset": "string",
      "network": "string"
    },
    "converted": {
      "amount": "string",
      "asset": "string",
      "network": "string"
    },
    "output": {
      "amount": "string",
      "asset": "string",
      "network": "string"
    },
    "exchange_rate": "string",
    "external_fee": {
      "amount": "string",
      "asset": "string",
      "network": "string"
    },
    "dakota_fee": {
      "amount": "string",
      "asset": "string",
      "network": "string"
    },
    "client_fee": {
      "amount": "string",
      "asset": "string",
      "network": "string"
    },
    "gas_fee": {
      "amount": "string",
      "asset": "string",
      "network": "string"
    },
    "payment_reference": "Invoice payment for services"
  },
  "crypto_details": {
    "source_crypto_address": "string",
    "source_network_id": "ethereum-mainnet",
    "destination_crypto_address": "string",
    "destination_network_id": "ethereum-mainnet",
    "deposit_transaction_hash": "string",
    "transaction_hash": "string"
  },
  "created_at": 1234567890,
  "updated_at": 1234567890,
  "completed_at": 1234567890,
  "destination_payment_rail": "ach",
  "payment_reference": "string",
  "destination_bank_name": "Chase Bank",
  "destination_account_holder_name": "Acme Corporation",
  "destination_account_number_last_four": "6789",
  "destination_routing_number": "021000021",
  "destination_iban": "GB82WEST12345698765432",
  "destination_bic": "BARCGB22XXX"
}

Documentation Index

Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt

Use this file to discover all available pages before exploring further.

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

ā€‹
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, DKUSD).

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
Example:

"ach"

ā€‹
payment_reference
string

Optional payment reference message for bank transfers. Length limits: ACH (1-10 chars), Wire (1-140 chars) (6-140 chars), SWIFT (1-140 chars, max 4 lines of 35 chars each)

Required string length: 1 - 140
Example:

"Invoice payment for services"

ā€‹
developer_fee_bps
integer<int32>

Developer fee in basis points (1 bp = 0.01%). Overrides the default client fee for this transaction.

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

50

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

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"

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

ā€‹
send_amount
string

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

Example:

"1.24"

ā€‹
amount
string

Original requested amount

Example:

"1.23"

ā€‹
failure_reason
string

Reason for failure if status is failed

ā€‹
receipt
object

Detailed receipt information for a transaction

ā€‹
crypto_details
object

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
Example:

"ach"

ā€‹
payment_reference
string | null

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

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

NACHA/Fedwire return code (e.g., R01) when the transaction was returned by the receiving bank.

Example:

"R01"

ā€‹
return_reason
string

Human-readable return reason provided by the receiving bank.

Example:

"Insufficient Funds"

ā€‹
return_initiated_at
integer

Unix timestamp when the return was initiated.

Example:

1234567890

ā€‹
return_deadline
integer

Unix timestamp deadline for return processing.

Example:

1234567890

ā€‹
reversal_reason
string

Lead Bank ACH reversal reason when the originator reverses the transaction (e.g., duplicate, receiver_incorrect).

Example:

"duplicate"

ā€‹
reversal_initiated_at
integer

Unix timestamp when the reversal was initiated.

Example:

1234567890

ā€‹
customer_name
string

Display name of the customer associated with this transaction.

Example:

"Acme Corp"