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

# Advanced Flows

> Single-use payouts and swaps, international bank destinations, and other less common Dakota flows.

This page covers flows that branch off the core walkthrough in [Common Flows](/documentation/common-flows). Read that page first — it introduces Customer, Recipient, Destination, and Account. Everything here assumes those are already in place.

**On this page:**

* [One-off Offramp](#one-off-offramp-single-usd-payout)
* [One-off Swap](#one-off-swap-single-cross-chain-swap)

## One-off Offramp (Single USD Payout)

Use a one-off offramp when you need a single USD payout — a vendor invoice, a customer refund, a scheduled disbursement — and want to embed a human-readable reference on the bank wire. One-offs generate a single-use crypto deposit address that's discarded after the transaction completes.

**What one-off offramps give you over a reusable offramp account:**

* `payment_reference` — text carried into the bank wire. Per-rail constraints:

  * **ACH** — up to 18 chars. Letters, digits, and spaces only (no hyphens or punctuation).
  * **Wire** — up to 140 chars. No character restrictions.
  * **SEPA** — 6 to 140 chars. Letters, digits, spaces, and `& - . /`.
  * **SWIFT** — up to 140 chars. Letters, digits, spaces, and `, .`.

  Your recipient sees this on their statement and uses it to reconcile against an invoice number.
* `destination_payment_rail` — override the rail per transaction (e.g. force `fedwire` instead of the destination's default `ach`).
* `developer_fee_bps` — per-transaction developer fee override.

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant Blockchain
    participant Dakota
    participant Bank

    App->>Dakota: POST /transactions (transaction_type: one_off)
    Dakota-->>App: crypto_address + send_amount
    App->>Blockchain: Send exactly send_amount to crypto_address
    Blockchain->>Dakota: Stablecoin received
    Dakota->>App: Webhook: transaction.one_off.created
    Dakota->>Bank: Wire USD with payment_reference
    Dakota->>App: Webhook: transaction.one_off.updated (completed)
```

### Create the One-off Transaction

Prerequisite: a bank Destination (`destination_type: "fiat_us"`) already attached to a Recipient for this Customer — see [Add a Bank Destination](/documentation/common-flows#add-a-bank-destination-for-offramps).

```bash theme={null}
curl -X POST https://api.platform.dakota.xyz/transactions \
  -H "X-API-Key: $DAKOTA_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_type": "one_off",
    "customer_id": "2LfTd6QQrUyPKwRR9qMMyk7CMHS",
    "amount": "1250.00",
    "source_network_id": "ethereum-mainnet",
    "source_asset": "USDC",
    "destination_id": "2LfYm5KMnRvLFtRP7nJJug4zBAN",
    "destination_asset": "USD",
    "destination_payment_rail": "ach",
    "payment_reference": "INV 2024 042"
  }'
```

**Response:**

```json theme={null}
{
  "id": "2LfZn6LNoSvMGuSQ0pLLof1OneA",
  "resource_type": "one_off",
  "status": "awaiting_funds",
  "crypto_address": "0xabc...",
  "source_network_id": "ethereum-mainnet",
  "source_asset": "USDC",
  "send_amount": "1250.00",
  "payment_reference": "INV 2024 042"
}
```

Send exactly `send_amount` to `crypto_address`. The address is single-use and discarded after the transaction completes. Dakota converts the stablecoin and wires USD to the bank Destination with `INV 2024 042` included as the payment reference. Subscribe to `transaction.one_off.created` and `transaction.one_off.updated` to track status.

<Warning>
  Sandbox object-create endpoints reject mainnet network IDs and cap per-request `amount` at \$2 USD. USDT is not yet supported in sandbox (coming soon); USD, USDC, and RD work today. See [Testing — Sandbox restrictions](/documentation/testing#sandbox-restrictions).
</Warning>

***

## One-off Swap (Single Cross-Chain Swap)

Use a one-off swap when the target network varies per swap (a reusable swap account pins `destination_network_id`) or you want to apply a different `developer_fee_bps` on this specific swap. `payment_reference` and `destination_payment_rail` are offramp-only and do not apply to swaps.

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant Source as Source chain
    participant Dakota
    participant Target as Target chain

    App->>Dakota: POST /transactions (transaction_type: one_off)
    Dakota-->>App: crypto_address + send_amount
    App->>Source: Send exactly send_amount to crypto_address
    Source->>Dakota: Source stablecoin received
    Dakota->>App: Webhook: transaction.one_off.created
    Dakota->>Target: Deliver target stablecoin to destination
    Dakota->>App: Webhook: transaction.one_off.updated (completed)
```

### Create the One-off Swap

Prerequisite: a crypto Destination on the target network/asset already attached to a Recipient — see [Add a Crypto Destination](/documentation/common-flows#add-a-crypto-destination-for-onramps-and-swaps).

```bash theme={null}
curl -X POST https://api.platform.dakota.xyz/transactions \
  -H "X-API-Key: $DAKOTA_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_type": "one_off",
    "customer_id": "2LfTd6QQrUyPKwRR9qMMyk7CMHS",
    "amount": "500.00",
    "source_network_id": "ethereum-mainnet",
    "source_asset": "USDC",
    "destination_id": "2LfYm5KMnRvLFtRP7nJJug4zJEP",
    "destination_asset": "USDT",
    "destination_network_id": "polygon-mainnet",
    "developer_fee_bps": 25
  }'
```

**Response:**

```json theme={null}
{
  "id": "2LfZn6LNoSvMGuSQ0pLLswOffOn",
  "resource_type": "one_off",
  "status": "awaiting_funds",
  "crypto_address": "0xabc...",
  "source_network_id": "ethereum-mainnet",
  "source_asset": "USDC",
  "destination_asset": "USDT",
  "destination_network_id": "polygon-mainnet",
  "send_amount": "500.00"
}
```

Send exactly `send_amount` to `crypto_address`. Dakota converts and delivers the destination asset on the target network. Same `transaction.one_off.*` webhooks as one-off offramp.

<Warning>
  Sandbox object-create endpoints reject mainnet network IDs and cap per-request `amount` at \$2 USD. USDT is not yet supported in sandbox (coming soon); USD, USDC, and RD work today. See [Testing — Sandbox restrictions](/documentation/testing#sandbox-restrictions).
</Warning>