Before processing transactions, you need to set up recipients and their associated destinations. Recipients represent entities that can receive payments, while destinations specify the exact accounts (crypto addresses, bank accounts) where funds should be sent.

Overview

The Dakota Platform uses a two-level structure for payment routing:

Recipients: Business entities or individuals that can receive payments
Destinations: Specific accounts (crypto addresses, bank accounts) associated with recipients

This structure allows you to manage multiple payment destinations for the same recipient while maintaining clear records for compliance and reporting.

Conceptual Model: The Payment Chain

Understanding the complete payment chain is crucial for successful integration:

Customer → Recipient → Destination
   ↓           ↓          ↓
Who pays   Who receives  Where money goes

The Three-Level Hierarchy

Customer (Your User)
- Your application’s user who wants to send money
- Must complete KYB verification
- Can have multiple recipients
- Example: “Acme Corp” (your business customer)
Recipient (Payment Target Entity)
- Legal entity that will receive the payment
- Has compliance information (name, address)
- Can have multiple destinations for different asset types
- Example: “Supplier XYZ Ltd” (the business being paid)
Destination (Specific Account)
- The actual account where money is sent
- Can be crypto address, bank account, etc.
- Linked to exactly one recipient
- Example: “0x742d…” (USDC wallet address)

Why This Structure?

Compliance & Reporting

Recipients provide legal entity information for compliance
Clear audit trail for who is being paid
Supports anti-money laundering requirements

Flexibility

One recipient can have multiple destinations (different currencies/networks)
Easy to add new payment methods to existing relationships
Supports complex business relationships

Organization

Group related payment accounts by business relationship
Cleaner user interfaces for managing multiple accounts
Better record-keeping for accounting purposes

Real-World Example

Let’s say your customer “Acme Corp” wants to pay their supplier “Global Manufacturing Ltd”:

Customer: Acme Corp
└── Recipient: Global Manufacturing Ltd
    ├── Destination 1: Bank Account (USD payments)
    │   ├── Type: fiat_us
    │   ├── Account: ****6789
    │   └── Routing: 021000021
    ├── Destination 2: Ethereum Wallet (USDC payments)  
    │   ├── Type: crypto
    │   ├── Address: 0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2
    │   └── Network: ethereum-mainnet
    └── Destination 3: Solana Wallet (SOL/USDC payments)
        ├── Type: crypto
        ├── Address: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
        └── Network: solana

When processing a transaction, you specify:

Customer ID: Who is paying (31Tgw0zSyDVo4Az66kmzUjMuwxx)
Destination ID: Where money should go (31TgvweTHSjWNxfARrnhjmBKSem)

The system automatically knows the recipient context through the destination relationship.

Complete Workflow Guide

Follow this step-by-step process to set up the complete payment chain:

Step 1: Start with an Approved Customer

First, verify that your customer exists and has been KYB-approved:

cURL

curl -X GET https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx \
  -H "X-API-Key: your-api-key"

JavaScript

const response = await fetch('https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx', {
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

const customer = await response.json();
console.log('Customer KYB Status:', customer.data.kyb_status);

Python

import requests

response = requests.get(
    'https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx',
    headers={'X-API-Key': 'your-api-key'}
)

customer = response.json()
print(f'Customer KYB Status: {customer["data"]["kyb_status"]}')

package main

import (
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx", nil)
    
    req.Header.Add("X-API-Key", "your-api-key")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    
    let response = client
        .get("https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx")
        .headers(headers)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class DakotaCustomerStatus {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx"))
            .header("X-API-Key", "your-api-key")
            .GET()
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Expected response:

{
  "id": "cust_acme123",
  "name": "Acme Corp",
  "customer_type": "business",
  "kyb_status": "active",
  "kyb_links": [],
  "application_id": "2WGC9cKv9P4K8eGzqY6qJ3Xz7Qm",
  "created_at": 1705320600,
  "updated_at": 1705324200
}

Step 2: Create a Recipient

cURL

curl -X POST https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx/recipients \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Global Manufacturing Ltd",
    "address": {
      "street1": "456 Industrial Blvd",
      "city": "Detroit",
      "region": "MI",
      "postal_code": "48201",
      "country": "US"
    }
  }'

JavaScript

const recipient = await fetch('https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx/recipients', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Global Manufacturing Ltd',
    address: {
      street1: '456 Industrial Blvd',
      city: 'Detroit',
      region: 'MI',
      postal_code: '48201',
      country: 'US'
    }
  })
});
// Result: 31TgvwFzi3rstV0DEDzQtuBfwFR

Python

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx/recipients',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Global Manufacturing Ltd',
        'address': {
            'street1': '456 Industrial Blvd',
            'city': 'Detroit',
            'region': 'MI',
            'postal_code': '48201',
            'country': 'US'
        }
    }
)
# Result: recp_global_mfg_789

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "name": "Global Manufacturing Ltd",
        "address": {
            "street1": "456 Industrial Blvd",
            "city": "Detroit",
            "region": "MI",
            "postal_code": "48201",
            "country": "US"
        }
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx/recipients", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    // Result: 31TgvwFzi3rstV0DEDzQtuBfwFR
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "name": "Global Manufacturing Ltd",
        "address": {
            "street1": "456 Industrial Blvd",
            "city": "Detroit",
            "region": "MI",
            "postal_code": "48201",
            "country": "US"
        }
    });
    
    let response = client
        .post("https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx/recipients")
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    // Result: 31TgvwFzi3rstV0DEDzQtuBfwFR
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaRecipientCreator {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "name": "Global Manufacturing Ltd",
              "address": {
                "street1": "456 Industrial Blvd",
                "city": "Detroit",
                "region": "MI",
                "postal_code": "48201",
                "country": "US"
              }
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/customers/31Tgw0zSyDVo4Az66kmzUjMuwxx/recipients"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        // Result: 31TgvwFzi3rstV0DEDzQtuBfwFR
    }
}

Step 3: Add Payment Destinations

Crypto Destination

cURL

curl -X POST https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "crypto",
    "name": "USDC Wallet",
    "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
    "network_id": "ethereum-mainnet"
  }'

JavaScript

const cryptoDestination = await fetch('https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination_type: 'crypto',
    name: 'USDC Wallet',
    crypto_address: '0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2',
    network_id: 'ethereum-mainnet'
  })
});
// Result: 31TgvySz1ARnqMZUdbuxykqqxGV

Python

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'destination_type': 'crypto',
        'name': 'USDC Wallet',
        'crypto_address': '0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2',
        'network_id': 'ethereum-mainnet'
    }
)
# Result: dest_crypto_usdc_456

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "destination_type": "crypto",
        "name": "USDC Wallet",
        "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
        "network_id": "ethereum-mainnet"
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    // Result: 31TgvySz1ARnqMZUdbuxykqqxGV
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "destination_type": "crypto",
        "name": "USDC Wallet",
        "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
        "network_id": "ethereum-mainnet"
    });
    
    let response = client
        .post("https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations")
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    // Result: 31TgvySz1ARnqMZUdbuxykqqxGV
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaCryptoDestination {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "destination_type": "crypto",
              "name": "USDC Wallet",
              "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
              "network_id": "ethereum-mainnet"
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        // Result: 31TgvySz1ARnqMZUdbuxykqqxGV
    }
}

Bank Destination

cURL

curl -X POST https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "fiat_us",
    "name": "Primary Business Account",
    "aba_routing_number": "021000021",
    "account_number": "987654321",
    "account_type": "checking",
    "account_holder_name": "Acme Corporation",
    "bank_name": "Chase Bank"
  }'

JavaScript

const bankDestination = await fetch('https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination_type: 'fiat_us',
    name: 'Primary Business Account',
    aba_routing_number: '021000021',
    account_number: '987654321',
    account_type: 'checking',
    account_holder_name: 'Acme Corporation',
    bank_name: 'Chase Bank'
  })
});
// Result: 31TgvtxUdXi95dUN4M8X1rhSCNS

Python

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'destination_type': 'fiat_us',
        'name': 'Primary Business Account',
        'aba_routing_number': '021000021',
        'account_number': '987654321',
        'account_type': 'checking',
        'account_holder_name': 'Acme Corporation',
        'bank_name': 'Chase Bank'
    }
)
# Result: dest_bank_usd_789

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "destination_type": "fiat_us",
        "name": "Primary Business Account",
        "aba_routing_number": "021000021",
        "account_number": "987654321",
        "account_type": "checking",
        "account_holder_name": "Acme Corporation",
        "bank_name": "Chase Bank"
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    // Result: 31TgvtxUdXi95dUN4M8X1rhSCNS
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "destination_type": "fiat_us",
        "name": "Primary Business Account",
        "aba_routing_number": "021000021",
        "account_number": "987654321",
        "account_type": "checking",
        "account_holder_name": "Acme Corporation",
        "bank_name": "Chase Bank"
    });
    
    let response = client
        .post("https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations")
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    // Result: 31TgvtxUdXi95dUN4M8X1rhSCNS
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaBankDestination {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "destination_type": "fiat_us",
              "name": "Primary Business Account",
              "aba_routing_number": "021000021",
              "account_number": "987654321",
              "account_type": "checking",
              "account_holder_name": "Acme Corporation",
              "bank_name": "Chase Bank"
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/recipients/recp_global_mfg_789/destinations"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        // Result: 31TgvtxUdXi95dUN4M8X1rhSCNS
    }
}

Step 4: Create Transaction Accounts

Crypto Transaction

cURL

curl -X POST https://api.platform.dakota.xyz/transactions \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "31Tgw0zSyDVo4Az66kmzUjMuwxx",
    "destination_id": "31TgvySz1ARnqMZUdbuxykqqxGV",
    "source_asset": "USD",
    "source_network_id": "fiat",
    "destination_asset": "USDC",
    "destination_network_id": "ethereum-mainnet",
    "amount": "1000.00"
  }'

JavaScript

const cryptoTransaction = await fetch('https://api.platform.dakota.xyz/transactions', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: '31Tgw0zSyDVo4Az66kmzUjMuwxx',
    destination_id: 'dest_crypto_usdc_456',
    source_asset: 'USD',
    source_network_id: 'fiat',
    destination_asset: 'USDC',
    destination_network_id: 'ethereum-mainnet',
    amount: '1000.00'
  })
});

Python

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/transactions',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'customer_id': '31Tgw0zSyDVo4Az66kmzUjMuwxx',
        'destination_id': 'dest_crypto_usdc_456',
        'source_asset': 'USD',
        'source_network_id': 'fiat',
        'destination_asset': 'USDC',
        'destination_network_id': 'ethereum-mainnet',
        'amount': '1000.00'
    }
)

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "customer_id": "31Tgw0zSyDVo4Az66kmzUjMuwxx",
        "destination_id": "31TgvySz1ARnqMZUdbuxykqqxGV",
        "source_asset": "USD",
        "source_network_id": "fiat",
        "destination_asset": "USDC",
        "destination_network_id": "ethereum-mainnet",
        "amount": "1000.00"
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/transactions", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "customer_id": "31Tgw0zSyDVo4Az66kmzUjMuwxx",
        "destination_id": "31TgvySz1ARnqMZUdbuxykqqxGV",
        "source_asset": "USD",
        "source_network_id": "fiat",
        "destination_asset": "USDC",
        "destination_network_id": "ethereum-mainnet",
        "amount": "1000.00"
    });
    
    let response = client
        .post("https://api.platform.dakota.xyz/transactions")
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaCryptoTransaction {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "customer_id": "31Tgw0zSyDVo4Az66kmzUjMuwxx",
              "destination_id": "31TgvySz1ARnqMZUdbuxykqqxGV",
              "source_asset": "USD",
              "source_network_id": "fiat",
              "destination_asset": "USDC",
              "destination_network_id": "ethereum-mainnet",
              "amount": "1000.00"
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/transactions"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Bank Transaction

cURL

curl -X POST https://api.platform.dakota.xyz/transactions \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "31Tgw0zSyDVo4Az66kmzUjMuwxx",
    "destination_id": "31TgvtxUdXi95dUN4M8X1rhSCNS",
    "source_asset": "USDC",
    "source_network_id": "ethereum-mainnet",
    "destination_asset": "USD",
    "destination_network_id": "fiat",
    "amount": "500.00"
  }'

JavaScript

const bankTransaction = await fetch('https://api.platform.dakota.xyz/transactions', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: '31Tgw0zSyDVo4Az66kmzUjMuwxx',
    destination_id: 'dest_bank_usd_789',
    source_asset: 'USDC',
    source_network_id: 'ethereum-mainnet',
    destination_asset: 'USD',
    destination_network_id: 'fiat',
    amount: '500.00'
  })
});

Python

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/transactions',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'customer_id': '31Tgw0zSyDVo4Az66kmzUjMuwxx',
        'destination_id': 'dest_bank_usd_789',
        'source_asset': 'USDC',
        'source_network_id': 'ethereum-mainnet',
        'destination_asset': 'USD',
        'destination_network_id': 'fiat',
        'amount': '500.00'
    }
)

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "customer_id": "31Tgw0zSyDVo4Az66kmzUjMuwxx",
        "destination_id": "31TgvtxUdXi95dUN4M8X1rhSCNS",
        "source_asset": "USDC",
        "source_network_id": "ethereum-mainnet",
        "destination_asset": "USD",
        "destination_network_id": "fiat",
        "amount": "500.00"
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/transactions", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "customer_id": "31Tgw0zSyDVo4Az66kmzUjMuwxx",
        "destination_id": "31TgvtxUdXi95dUN4M8X1rhSCNS",
        "source_asset": "USDC",
        "source_network_id": "ethereum-mainnet",
        "destination_asset": "USD",
        "destination_network_id": "fiat",
        "amount": "500.00"
    });
    
    let response = client
        .post("https://api.platform.dakota.xyz/transactions")
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaBankTransaction {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "customer_id": "31Tgw0zSyDVo4Az66kmzUjMuwxx",
              "destination_id": "31TgvtxUdXi95dUN4M8X1rhSCNS",
              "source_asset": "USDC",
              "source_network_id": "ethereum-mainnet",
              "destination_asset": "USD",
              "destination_network_id": "fiat",
              "amount": "500.00"
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/transactions"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Best Practices for Payment Chain Management

Recipient Organization

Use clear, descriptive recipient names matching legal business names
Keep recipient addresses current for compliance
Group destinations by recipient to maintain clear relationships

Destination Naming

Use descriptive destination names: “Primary USDC Wallet”, “Backup Bank Account”
Include asset type in names for clarity: “EUR Business Account”, “USDC Wallet”
Maintain consistent naming conventions across your application

Relationship Management

One recipient per business entity (don’t create duplicates)
Multiple destinations per recipient for different payment methods
Delete old destinations for security

Error Prevention

Validate crypto addresses before creating destinations
Test small transactions to new destinations first
Implement approval workflows for new high-value destinations
Monitor destination usage patterns for anomalies

This hierarchical structure provides the foundation for secure, compliant, and organized payment processing through Dakota Platform’s API.

Recipients

Recipients represent the entities that will receive payments. Each recipient must have a name and physical address for compliance purposes.

Creating Recipients

Create a recipient for a customer.

Recipient Fields

Field	Type	Required	Description	Example
`name`	string	✅	Legal name of the recipient entity	`"Acme Corporation"`
`address`	object	✅	Physical address for compliance	See address fields below
`external_id`	string	❌	Your internal identifier for this recipient	`"acme_recipient_001"`

Address Fields

Field	Type	Required	Description	Example
`street1`	string	✅	Street address line 1	`"123 Business Ave"`
`street2`	string	❌	Street address line 2	`"Suite 456"`
`street3`	string	❌	Street address line 3	`"Floor 2"`
`city`	string	✅	City name	`"New York"`
`region`	string	✅	State/province/region code	`"NY"`
`postal_code`	string	❌	ZIP/postal code	`"10001"`
`country`	string	✅	ISO 3166-1 alpha-2 country code	`"US"`

Request Example

cURL

curl -X POST https://api.platform.dakota.xyz/customers/{customer_id}/recipients \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "address": {
      "street1": "123 Business Ave",
      "city": "New York",
      "region": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  }'

JavaScript

const response = await fetch(`https://api.platform.dakota.xyz/customers/${customerId}/recipients`, {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation',
    address: {
      street1: '123 Business Ave',
      city: 'New York',
      region: 'NY',
      postal_code: '10001',
      country: 'US'
    }
  })
});

const recipient = await response.json();
console.log('Created recipient:', recipient.data.id);

Python

import requests
import uuid

response = requests.post(
    f'https://api.platform.dakota.xyz/customers/{customer_id}/recipients',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Acme Corporation',
        'address': {
            'street1': '123 Business Ave',
            'city': 'New York',
            'region': 'NY',
            'postal_code': '10001',
            'country': 'US'
        }
    }
)

recipient = response.json()
print(f'Created recipient: {recipient["data"]["id"]}')

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "name": "Acme Corporation",
        "address": {
            "street1": "123 Business Ave",
            "city": "New York",
            "region": "NY",
            "postal_code": "10001",
            "country": "US"
        }
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/customers/" + customerId + "/recipients", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "name": "Acme Corporation",
        "address": {
            "street1": "123 Business Ave",
            "city": "New York",
            "region": "NY",
            "postal_code": "10001",
            "country": "US"
        }
    });
    
    let response = client
        .post(&format!("https://api.platform.dakota.xyz/customers/{}/recipients", customer_id))
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaRecipientsExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "name": "Acme Corporation",
              "address": {
                "street1": "123 Business Ave",
                "city": "New York",
                "region": "NY",
                "postal_code": "10001",
                "country": "US"
              }
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/customers/" + customerId + "/recipients"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Response:

{
  "data": {
    "id": "31TgvwFzi3rstV0DEDzQtuBfwFR",
    "name": "Acme Corporation",
    "address": {
      "street1": "123 Business Ave",
      "city": "New York",
      "region": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Listing Recipients

Get all recipients for a customer:

cURL

curl -X GET https://api.platform.dakota.xyz/customers/{customer_id}/recipients \
  -H "X-API-Key: your-api-key"

JavaScript

const response = await fetch(`https://api.platform.dakota.xyz/customers/${customerId}/recipients`, {
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

const recipients = await response.json();

Python

import requests

response = requests.get(
    f'https://api.platform.dakota.xyz/customers/{customer_id}/recipients',
    headers={'X-API-Key': 'your-api-key'}
)

recipients = response.json()

package main

import (
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.platform.dakota.xyz/customers/" + customerId + "/recipients", nil)
    
    req.Header.Add("X-API-Key", "your-api-key")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    
    let response = client
        .get(&format!("https://api.platform.dakota.xyz/customers/{}/recipients", customer_id))
        .headers(headers)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class DakotaListRecipientsExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/customers/" + customerId + "/recipients"))
            .header("X-API-Key", "your-api-key")
            .GET()
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Response:

{
  "data": [
    {
      "id": "31TgvwFzi3rstV0DEDzQtuBfwFR",
      "name": "Global Manufacturing Ltd",
      "address": {
        "street1": "456 Industrial Blvd",
        "city": "Detroit",
        "region": "MI",
        "postal_code": "48201",
        "country": "US"
      },
      "external_id": "supplier_001",
      "created_at": "2024-01-10T14:20:00Z"
    },
    {
      "id": "31TgvwGHm8PqtV2DEDzQtuBfwFS",
      "name": "Tech Solutions Inc",
      "address": {
        "street1": "789 Silicon Valley Dr",
        "street2": "Suite 200",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94105",
        "country": "US"
      },
      "external_id": null,
      "created_at": "2024-01-12T09:15:00Z"
    },
    {
      "id": "31TgvwJKn9QrtV3DEDzQtuBfwFT",
      "name": "European Consulting GmbH",
      "address": {
        "street1": "Hauptstraße 123",
        "city": "Berlin",
        "region": "BE",
        "postal_code": "10117",
        "country": "DE"
      },
      "external_id": "vendor_eu_007",
      "created_at": "2024-01-14T16:45:00Z"
    }
  ]
}

Destinations

Destinations are the specific accounts where funds will be sent. Each destination is associated with a recipient and specifies either a cryptocurrency address or traditional bank account details.

Destination Types

Dakota Platform supports three destination types:

Crypto: Cryptocurrency addresses on supported networks
Fiat US: US bank accounts (ACH transfers)
Fiat IBAN: International bank accounts

Creating Crypto Destinations

Add a cryptocurrency destination to a recipient.

Crypto Destination Fields

Field	Type	Required	Description	Example
`destination_type`	string	✅	Must be `"crypto"` for cryptocurrency destinations	`"crypto"`
`name`	string	✅	Descriptive name for the destination	`"Primary USDC Wallet"`
`crypto_address`	string	✅	Valid cryptocurrency address for the specified network	`"0x742d35Cc..."`
`network_id`	string	✅	Network identifier. See supported networks below	`"ethereum-mainnet"`
`assets`	array	❌	Specific assets this destination accepts (optional)	`["USDC", "USDT"]`

Supported Networks

Network ID	Name	Supported Assets
`ethereum-mainnet`	Ethereum	USDC, USDT
`polygon-mainnet`	Polygon	USDC
`arbitrum-mainnet`	Arbitrum	USDC
`base-mainnet`	Base	USDC
`optimism-mainnet`	Optimism	USDC
`solana-mainnet`	Solana	USDC

In sandbox, replace each mainnet ID with its testnet equivalent (ethereum-sepolia, polygon-amoy, arbitrum-sepolia, base-sepolia, solana-devnet); mainnet IDs are rejected. See Testing — Sandbox restrictions.

Request Example

cURL

curl -X POST https://api.platform.dakota.xyz/recipients/{recipient_id}/destinations \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "crypto",
    "name": "Primary USDC Wallet",
    "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
    "network_id": "ethereum-mainnet"
  }'

JavaScript

const response = await fetch(`https://api.platform.dakota.xyz/recipients/${recipientId}/destinations`, {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination_type: 'crypto',
    name: 'Primary USDC Wallet',
    crypto_address: '0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2',
    network_id: 'ethereum-mainnet'
  })
});

Python

import requests
import uuid

response = requests.post(
    f'https://api.platform.dakota.xyz/recipients/{recipient_id}/destinations',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'destination_type': 'crypto',
        'name': 'Primary USDC Wallet',
        'crypto_address': '0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2',
        'network_id': 'ethereum-mainnet'
    }
)

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "destination_type": "crypto",
        "name": "Primary USDC Wallet",
        "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
        "network_id": "ethereum-mainnet"
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/recipients/" + recipientId + "/destinations", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "destination_type": "crypto",
        "name": "Primary USDC Wallet",
        "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
        "network_id": "ethereum-mainnet"
    });
    
    let response = client
        .post(&format!("https://api.platform.dakota.xyz/recipients/{}/destinations", recipient_id))
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaCryptoDestinationExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "destination_type": "crypto",
              "name": "Primary USDC Wallet",
              "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
              "network_id": "ethereum-mainnet"
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/recipients/" + recipientId + "/destinations"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Response Example

{
  "data": {
    "id": "31TgvySz1ARnqMZUdbuxykqqxGV",
    "destination_type": "crypto",
    "name": "Primary USDC Wallet",
    "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
    "network_id": "ethereum-mainnet",
    "assets": ["USDC", "USDT"],
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

API Reference: For complete details on crypto destination creation, see Create Crypto Destination

Creating US Bank Account Destinations

Add a US bank account destination.

US Bank Account Destination Fields

Field	Type	Required	Description	Example
`destination_type`	string	✅	Must be `"fiat_us"` for US bank accounts	`"fiat_us"`
`name`	string	✅	Descriptive name for the destination	`"Primary Business Account"`
`aba_routing_number`	string	✅	9-digit ABA routing number	`"123456789"`
`account_number`	string	✅	Bank account number	`"9876543210"`
`account_type`	string	✅	Type of account. Must be `"checking"` or `"savings"`	`"checking"`
`account_holder_name`	string	✅	Name on the bank account, 3–35 characters	`"Acme Corporation"`
`bank_name`	string	✅	Name of the bank, up to 35 characters	`"Chase Bank"`
`account_holder_address`	object	❌	Address of the account holder	See Address fields
`bank_address`	object	❌	Address of the bank. Optional for US domestic transfers	See Address fields
`assets`	array	❌	Supported fiat currencies (optional)	`["USD"]`

ACH caps account_holder_name at 22 characters. The schema accepts up to 35 characters, but the ACH network (NACHA) limits the account holder name field to 22 characters. A payout over the ach rail to a destination with a longer name is rejected with a 400 error (account_holder_name must be at most 22 characters for ACH). This is a network constraint, not a Dakota setting, and cannot be extended. For account holder names longer than 22 characters, route the payout over fedwire instead.

Request Example

cURL

curl -X POST https://api.platform.dakota.xyz/recipients/{recipient_id}/destinations \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "fiat_us",
    "name": "Primary Business Account",
    "aba_routing_number": "123456789",
    "account_number": "9876543210",
    "account_type": "checking",
    "account_holder_name": "Acme Corporation",
    "bank_name": "Chase Bank",
    "assets": ["USD"]
  }'

JavaScript

const response = await fetch(`https://api.platform.dakota.xyz/recipients/${recipientId}/destinations`, {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination_type: 'fiat_us',
    name: 'Primary Business Account',
    aba_routing_number: '123456789',
    account_number: '9876543210',
    account_type: 'checking',
    account_holder_name: 'Acme Corporation',
    bank_name: 'Chase Bank',
    assets: ['USD']
  })
});

Python

import requests
import uuid

response = requests.post(
    f'https://api.platform.dakota.xyz/recipients/{recipient_id}/destinations',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'destination_type': 'fiat_us',
        'name': 'Primary Business Account',
        'aba_routing_number': '123456789',
        'account_number': '9876543210',
        'account_type': 'checking',
        'account_holder_name': 'Acme Corporation',
        'bank_name': 'Chase Bank',
        'assets': ['USD']
    }
)

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "destination_type": "fiat_us",
        "name": "Primary Business Account",
        "aba_routing_number": "123456789",
        "account_number": "9876543210",
        "account_type": "checking",
        "account_holder_name": "Acme Corporation",
        "bank_name": "Chase Bank",
        "assets": ["USD"]
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/recipients/" + recipientId + "/destinations", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "destination_type": "fiat_us",
        "name": "Primary Business Account",
        "aba_routing_number": "123456789",
        "account_number": "9876543210",
        "account_type": "checking",
        "account_holder_name": "Acme Corporation",
        "bank_name": "Chase Bank",
        "assets": ["USD"]
    });
    
    let response = client
        .post(&format!("https://api.platform.dakota.xyz/recipients/{}/destinations", recipient_id))
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaBankDestinationExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "destination_type": "fiat_us",
              "name": "Primary Business Account",
              "aba_routing_number": "123456789",
              "account_number": "9876543210",
              "account_type": "checking",
              "account_holder_name": "Acme Corporation",
              "bank_name": "Chase Bank",
              "assets": ["USD"]
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/recipients/" + recipientId + "/destinations"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Response Example

{
  "data": {
    "id": "31TgvtxUdXi95dUN4M8X1rhSCNS",
    "destination_type": "fiat_us",
    "name": "Primary Business Account",
    "aba_routing_number": "*****6789",
    "account_number": "*******3210",
    "account_type": "checking",
    "account_holder_name": "Acme Corporation",
    "bank_name": "Chase Bank",
    "assets": ["USD"],
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

API Reference: For complete details on US bank account destination creation, see Create US Bank Destination

Creating IBAN Destinations

Add an IBAN destination for international transfers.

IBAN Destination Fields

Field	Type	Required	Description	Example
`destination_type`	string	✅	Must be `"fiat_iban"` for IBAN accounts	`"fiat_iban"`
`name`	string	✅	Descriptive name for the destination	`"European Business Account"`
`iban`	string	✅	Valid IBAN (International Bank Account Number)	`"DE89370400440532013000"`
`account_holder_name`	string	✅	Name on the bank account, 3–140 characters	`"Acme GmbH"`
`account_holder_address`	object	✅	Address of the account holder	See Address fields
`bank_name`	string	✅	Name of the bank	`"Commerzbank"`
`assets`	array	✅	Fiat currency codes (ISO 4217, three letters). `"USD"` is always available; foreign currencies require FX access to be enabled for the account	`["USD"]`
`capabilities`	array	✅	Payment rails the destination supports: `"swift"` or `"sepa"`	`["swift"]`
`bic`	string	❌	BIC/SWIFT code. Required for SWIFT payouts	`"COBADEFFXXX"`
`bank_address`	object	❌	Address of the bank. Required if `bic` is provided	See Address fields

SWIFT payouts require the customer’s international_wire capability and can settle in USD or, when FX access is enabled for the account, in a foreign currency priced by quote (see POST /fx/quotes and GET /customers/{customer_id}/fx-currencies). See Foreign exchange (FX) for currencies, availability checks and quote examples. In sandbox, FX access is enabled for every client (see FX Access). The beneficiary’s bank and intermediary banks can deduct their fees from a SWIFT payout, so the account holder can receive less than the amount sent. SEPA can be listed as a destination capability but is not currently offered as a payout rail. See SWIFT payouts for the full flow.

Request Example

cURL

curl -X POST https://api.platform.dakota.xyz/recipients/{recipient_id}/destinations \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_type": "fiat_iban",
    "name": "European Business Account",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "account_holder_name": "Acme GmbH",
    "account_holder_address": {
      "street1": "Mainzer Landstrasse 11",
      "city": "Frankfurt",
      "country": "DE"
    },
    "bank_name": "Commerzbank",
    "bank_address": {
      "street1": "Kaiserplatz 1",
      "city": "Frankfurt",
      "country": "DE"
    },
    "assets": ["USD"],
    "capabilities": ["swift"]
  }'

JavaScript

const response = await fetch(`https://api.platform.dakota.xyz/recipients/${recipientId}/destinations`, {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination_type: 'fiat_iban',
    name: 'European Business Account',
    iban: 'DE89370400440532013000',
    bic: 'COBADEFFXXX',
    account_holder_name: 'Acme GmbH',
    account_holder_address: {
      street1: 'Mainzer Landstrasse 11',
      city: 'Frankfurt',
      country: 'DE'
    },
    bank_name: 'Commerzbank',
    bank_address: {
      street1: 'Kaiserplatz 1',
      city: 'Frankfurt',
      country: 'DE'
    },
    assets: ['USD'],
    capabilities: ['swift']
  })
});

Python

import requests
import uuid

response = requests.post(
    f'https://api.platform.dakota.xyz/recipients/{recipient_id}/destinations',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'destination_type': 'fiat_iban',
        'name': 'European Business Account',
        'iban': 'DE89370400440532013000',
        'bic': 'COBADEFFXXX',
        'account_holder_name': 'Acme GmbH',
        'account_holder_address': {
            'street1': 'Mainzer Landstrasse 11',
            'city': 'Frankfurt',
            'country': 'DE'
        },
        'bank_name': 'Commerzbank',
        'bank_address': {
            'street1': 'Kaiserplatz 1',
            'city': 'Frankfurt',
            'country': 'DE'
        },
        'assets': ['USD'],
        'capabilities': ['swift']
    }
)

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "destination_type": "fiat_iban",
        "name": "European Business Account",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "account_holder_name": "Acme GmbH",
        "account_holder_address": {
            "street1": "Mainzer Landstrasse 11",
            "city": "Frankfurt",
            "country": "DE"
        },
        "bank_name": "Commerzbank",
        "bank_address": {
            "street1": "Kaiserplatz 1",
            "city": "Frankfurt",
            "country": "DE"
        },
        "assets": ["USD"],
        "capabilities": ["swift"]
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/recipients/" + recipientId + "/destinations", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "destination_type": "fiat_iban",
        "name": "European Business Account",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "account_holder_name": "Acme GmbH",
        "account_holder_address": {
            "street1": "Mainzer Landstrasse 11",
            "city": "Frankfurt",
            "country": "DE"
        },
        "bank_name": "Commerzbank",
        "bank_address": {
            "street1": "Kaiserplatz 1",
            "city": "Frankfurt",
            "country": "DE"
        },
        "assets": ["USD"],
        "capabilities": ["swift"]
    });
    
    let response = client
        .post(&format!("https://api.platform.dakota.xyz/recipients/{}/destinations", recipient_id))
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaIBANDestinationExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "destination_type": "fiat_iban",
              "name": "European Business Account",
              "iban": "DE89370400440532013000",
              "bic": "COBADEFFXXX",
              "account_holder_name": "Acme GmbH",
              "account_holder_address": {
                "street1": "Mainzer Landstrasse 11",
                "city": "Frankfurt",
                "country": "DE"
              },
              "bank_name": "Commerzbank",
              "bank_address": {
                "street1": "Kaiserplatz 1",
                "city": "Frankfurt",
                "country": "DE"
              },
              "assets": ["USD"],
              "capabilities": ["swift"]
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/recipients/" + recipientId + "/destinations"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Response Example

{
  "data": {
    "id": "31TgvuBMp7RstU4XEDzQtuBfwGU",
    "destination_type": "fiat_iban",
    "name": "European Business Account",
    "iban": "DE89****0440****3000",
    "bic": "COBADEFFXXX",
    "account_holder_name": "Acme GmbH",
    "bank_name": "Commerzbank",
    "assets": ["USD"],
    "capabilities": ["swift"],
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

API Reference: For complete details on IBAN destination creation, see Create IBAN Destination

Listing Destinations

Get all destinations for a recipient:

cURL

curl -X GET https://api.platform.dakota.xyz/recipients/{recipient_id}/destinations \
  -H "X-API-Key: your-api-key"

JavaScript

const response = await fetch(`https://api.platform.dakota.xyz/recipients/${recipientId}/destinations`, {
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

const destinations = await response.json();

Python

import requests

response = requests.get(
    f'https://api.platform.dakota.xyz/recipients/{recipient_id}/destinations',
    headers={'X-API-Key': 'your-api-key'}
)

destinations = response.json()

package main

import (
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.platform.dakota.xyz/recipients/" + recipientId + "/destinations", nil)
    
    req.Header.Add("X-API-Key", "your-api-key")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Rust

use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    
    let response = client
        .get(&format!("https://api.platform.dakota.xyz/recipients/{}/destinations", recipient_id))
        .headers(headers)
        .send()
        .await?;
    
    Ok(())
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class DakotaListDestinationsExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/recipients/" + recipientId + "/destinations"))
            .header("X-API-Key", "your-api-key")
            .GET()
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Response Example

{
  "data": [
    {
      "id": "31TgvySz1ARnqMZUdbuxykqqxGV",
      "destination_type": "crypto",
      "name": "Primary USDC Wallet",
      "crypto_address": "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
      "network_id": "ethereum-mainnet",
      "assets": ["USDC", "USDT"],
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "31TgvtxUdXi95dUN4M8X1rhSCNS",
      "destination_type": "fiat_us",
      "name": "Primary Business Account",
      "aba_routing_number": "*****6789",
      "account_number": "*******3210",
      "account_type": "checking",
      "account_holder_name": "Acme Corporation",
      "bank_name": "Chase Bank",
      "assets": ["USD"],
      "status": "active",
      "created_at": "2024-01-15T11:15:00Z",
      "updated_at": "2024-01-15T11:15:00Z"
    },
    {
      "id": "31TgvuBMp7RstU4XEDzQtuBfwGU",
      "destination_type": "fiat_iban",
      "name": "European Business Account",
      "iban": "DE89****0440****3000",
      "bic": "COBADEFFXXX",
      "assets": ["USD"],
      "status": "active",
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

Best Practices

Recipient Management

Use descriptive names for recipients
Keep address information current for compliance
Organize recipients logically (e.g., by business relationship)
Regular audits of recipient data

Destination Security

Validate cryptocurrency addresses before saving
Use test transactions for new crypto destinations
Implement approval workflows for new destinations
Monitor destination usage for suspicious activity

Compliance Considerations

Maintain accurate recipient addresses for reporting
Document the business relationship with each recipient
Regular compliance reviews of recipient and destination data
Implement proper access controls for destination management

Next Steps

Once you have recipients and destinations set up:

Create Transactions - Process payments to your configured destinations
Webhook Integration - Get notified about payment status changes (see the full event list for all available events)
Testing - Test your integration with sandbox data

For detailed API reference information, see the Recipients API Reference and Destinations API Reference sections.

​Overview

​Conceptual Model: The Payment Chain

​The Three-Level Hierarchy

​Why This Structure?

​Real-World Example

​Complete Workflow Guide

​Step 1: Start with an Approved Customer

​Step 2: Create a Recipient

​Step 3: Add Payment Destinations

​Crypto Destination

​Bank Destination

​Step 4: Create Transaction Accounts

​Crypto Transaction

​Bank Transaction

​Best Practices for Payment Chain Management

​Recipient Organization

​Destination Naming

​Relationship Management

​Error Prevention

​Recipients

​Creating Recipients

​Recipient Fields

​Address Fields

​Request Example

​Listing Recipients

​Destinations

​Destination Types

​Creating Crypto Destinations

​Crypto Destination Fields

​Supported Networks

​Request Example

​Response Example

​Creating US Bank Account Destinations

​US Bank Account Destination Fields

​Request Example

​Response Example

​Creating IBAN Destinations

​IBAN Destination Fields

​Request Example

​Response Example

​Listing Destinations

​Response Example

​Best Practices

​Recipient Management

​Destination Security

​Compliance Considerations

​Next Steps

Overview

Conceptual Model: The Payment Chain

The Three-Level Hierarchy

Why This Structure?

Real-World Example

Complete Workflow Guide

Step 1: Start with an Approved Customer

Step 2: Create a Recipient

Step 3: Add Payment Destinations

Crypto Destination

Bank Destination

Step 4: Create Transaction Accounts

Crypto Transaction

Bank Transaction

Best Practices for Payment Chain Management

Recipient Organization

Destination Naming

Relationship Management

Error Prevention

Recipients

Creating Recipients

Recipient Fields

Address Fields

Request Example

Listing Recipients

Destinations

Destination Types

Creating Crypto Destinations

Crypto Destination Fields

Supported Networks

Request Example

Response Example

Creating US Bank Account Destinations

US Bank Account Destination Fields

Request Example

Response Example

Creating IBAN Destinations

IBAN Destination Fields

Request Example

Response Example

Listing Destinations

Response Example

Best Practices

Recipient Management

Destination Security

Compliance Considerations

Next Steps