Create transfer batch

Executes an outbound transfer batch from one exact SDP Wallet ID, chunks recipients into Solana transactions, and returns the batch, recipient, and transfer records.

POST/v1/payments/transfer-batchesRun in dashboard

Requires an Idempotency-Key: a retry with the same key and request returns the original batch without another on-chain submission. Recipient order does not change the request. A native SOL batch is refused with 409 AMOUNT_BELOW_RENT_MINIMUM, before anything is written or sent, when a recipient whose address has no account gets less than the rent-exempt minimum (details.recipientIndexes) or the source wallet would be left holding more than nothing but less than the minimum (details.sourceRemainder). A token batch is refused with 409 SPONSORED_RENT_OVER_CAP when one recipient's new token account costs more rent than the sponsor funds in a transaction (details.recipientIndex). A recipient's counterparty account archived while the batch is being prepared returns 404, and one whose address changed returns 409 TRANSFER_BATCH_DESTINATION_CHANGED (details.counterpartyAccountIds); either way nothing is written or sent, so the same request can be sent again. A chunk the source wallet cannot fund fails its recipients and transfer with the reason in error (the wallet does not have enough funds); the batch still returns 200. An externalId already used by a batch on the same project and source wallet never pays again: the same request from the same credential returns that batch, and any other returns 409 TRANSFER_BATCH_RUN_EXISTS with its batchId in error.details. To finish a batch after a partial failure, call POST /v1/payments/transfer-batches/{batchId}/retry: it sends only the batch's failed recipients. Never resend the whole batch under a new Idempotency-Key, which pays the recipients that succeeded again.

Requires an API key with the transfer_batches.execute action.

Headers

x-project-id · string · min length 1 · example prj_example

Required for dashboard sessions. API keys use their assigned project.
Idempotency-Key · string · required

Use a unique 1–255 printable ASCII key per operation. Reuse it with the same request on retries. An in-flight attempt returns 409; a changed request returns 422. Retry and recovery rules.

Request body

application/json · required

Create a custody-executed outbound transfer batch.

projectId · string · min length 1 · example prj_example

Project identifier for the transfer batch context.
sourceCustodyWalletId · string · required · min length 1 · example cwlt_example

Exact SDP Wallet ID (id from GET /v1/wallets).
token · string · required · example SOL

Token to transfer. Pass SOL for the native token, a well-known token symbol (e.g. USDC) resolved to the configured cluster's mint, or a base58 SPL mint address. Custom tokens must be specified by their on-chain mint.
recipients · object[] · required · min items 1 · max items 500

Counterparty-account recipients to pay in this batch.
- externalId · string · min length 1 · max length 256
- counterpartyId · string · min length 1
- counterpartyAccountId · string · required · min length 1
- amount · string · required
externalId · string · required · min length 1 · max length 256 · example payroll_2026_06_30

Your ID for this payout run, unique per project and source wallet. Derive it from your own data so a restarted worker computes the same value (for example payroll-2026-05); never generate it at random, which gives no protection. Sending the same request again with this externalId, from the same credential, under any Idempotency-Key returns the existing batch; a different request with it returns 409 TRANSFER_BATCH_RUN_EXISTS with the existing batch's batchId in error.details. Neither pays anyone again. New recipients go in a new run with a new externalId. Required: it is what stops a resend under a new Idempotency-Key from paying the same recipients twice.

Responses

200 Transfer batch created
- data · object · required
  
  Transfer batch response payload.
  - batch · object · required
    
    Transfer batch details.
    - id · string · required · example xbatch_example
      
      Transfer batch identifier.
    - organizationId · string · required · min length 1 · example org_example
      
      Organization identifier.
    - projectId · string · required · min length 1 · example prj_example
      
      Project identifier for the transfer batch.
    - externalId · string | null · required · example payroll_2026_06_30
      
      Caller-provided batch correlation ID.
    - sourceCustodyWalletId · string | null · required · example cwlt_example
      
      Exact source SDP Wallet ID, or null for unresolved legacy batches.
    - sourceProviderWalletId · string · required · min length 1 · example privy_wallet_123
      
      Source Provider wallet ID retained as evidence.
    - sourceAddress · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Source custody wallet address.
    - token · string · required · example SOL
      
      Token symbol or mint address.
    - status · string · required · one of pending, processing, confirmed, failed, partially_failed, archived · example processing
      
      Transfer batch status.
    - totalAmount · string | null · required · example 1000.00
      
      Total requested batch amount in UI units, when computed.
    - recipientCount · integer · required · example 20
      
      Number of recipient rows in the batch.
    - transactionCount · integer · required · example 1
      
      Number of Solana transaction chunks for the batch.
    - createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      ISO 8601 timestamp.
    - updatedAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      ISO 8601 timestamp.
  - recipients · object[]
    
    Recipient rows for the batch, included on detail responses.
    - id · string · required
      
      Transfer batch recipient identifier.
    - batchId · string · required
      
      Parent transfer batch identifier.
    - transferId · string | null · required · min length 1 · example xfr_example
      
      Payment transfer chunk that settled this recipient, once assigned.
    - externalId · string | null · required · example payroll_row_001
      
      Caller-provided recipient correlation ID.
    - counterpartyId · string · required · example cpty_example
      
      Counterparty identifier for the recipient.
    - counterpartyAccountId · string · required · example cpacct_example
      
      Counterparty account identifier for the recipient.
    - destination · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Resolved Solana destination address.
    - amount · string · required · example 100.00
      
      Token amount in UI units (decimal string).
    - status · string · required · one of pending, processing, confirmed, failed, archived · example pending
      
      Transfer batch recipient status.
    - error · string | null · required
      
      Recipient-level failure reason, when available. A recipient the source wallet could not fund reads "The wallet used for this payment does not have enough funds. Add funds and try again."
    - createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      ISO 8601 timestamp.
    - updatedAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      ISO 8601 timestamp.
  - transfers · object[]
    
    Payment transfer chunk records associated with this batch.
    - fireblocks · object
      
      Native Fireblocks transfer tracking. A processing payment may await approval in Fireblocks; network fees are paid by its source vault. A missing transaction ID means submission is still being reconciled. Do not create a replacement payment while its outcome is unknown.
      - transactionId · string | null · required
      - status · string · required
      - subStatus · string | null · required
    - id · string · required · min length 1 · example xfr_example
      
      Transfer identifier (SDP record ID, not the on-chain signature).
    - organizationId · string · required · min length 1 · example org_example
      
      Organization identifier.
    - custodyWalletId · string | null · required · example cwlt_example
      
      Exact SDP Wallet ID associated with the persisted transfer, or null for unresolved legacy and observed rows.
    - providerWalletId · string · required · min length 1 · example privy_wallet_123
      
      Provider wallet ID retained as evidence; not an execution selector.
    - projectId · string · min length 1 · example prj_example
      
      Project identifier for the transfer.
    - type · string · required · example transfer
      
      Transfer type.
    - kind · string · required
      
      Dashboard transaction kind derived from the transfer type and originating Payments resource.
    - direction · string · required · one of inbound, outbound · example outbound
      
      Transfer direction.
    - status · string · required · example confirmed
      
      Transfer status.
    - signature · string | null · required · example sig_example
      
      Solana transaction signature (tx id/hash).
    - serializedTx · string | null · required · min length 1 · example base64_tx_example
      
      Base64-encoded transaction payload, if available. Always null for transfer batch chunks, whose signed bytes stay server-side.
    - slot · integer | null · required · example 123456
      
      Slot number, if confirmed.
    - blockTime · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      Block time, if confirmed.
    - confirmedAt · string · format date-time · example 2025-01-01T00:00:00.000Z
      
      When SDP confirmed the transfer on chain.
    - fee · integer | null · required · example 0
      
      Network fee the source wallet paid, in lamports: 0 when SDP sponsored the transaction, null when not known.
    - error · string | null · required · example Signature failed
      
      Error message if the transaction failed.
    - initiatedBy · object
      
      Initiator that triggered the transfer.
      - type · string · required · one of api_key, user, system · example api_key
        
        Initiator type.
      - id · string
        
        Initiator identifier if applicable.
      - display · string
        
        Human-friendly label for the initiator.
    - source · string · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Source wallet address.
    - destination · string · min length 32 · max length 44 · example So11111111111111111111111111111111111111112
      
      Destination wallet address.
    - memo · string · max length 256
      
      Optional memo for the transfer.
    - token · string
      
      Token symbol or mint address.
    - amount · string · example 100.00
      
      Token amount in UI units (decimal string).
    - counterpartyId · string · example cpty_example
      
      Counterparty tied to the transfer record, when available.
    - counterpartyDisplayName · string · example Acme Studio
      
      Current display name of the counterparty tied to the transfer.
    - risk · object
      
      Optional risk evaluation for the transfer.
      - provider · string · required · example trm
        
        Risk scoring provider.
      - score · string · required · example 0.12
        
        Provider-specific risk score.
      - level · string · required · one of low, medium, high, unknown · example low
        
        Risk level classification.
      - evaluatedAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
        
        Timestamp when risk was evaluated.
    - createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z
      
      Creation timestamp.
    - updatedAt · string · required · format date-time · example 2025-01-02T00:00:00.000Z
      
      Last update timestamp.
- meta · object · required
  
  Response metadata.
  - requestId · string · required · min length 1 · example req_example
    
    Request identifier for tracing.
  - timestamp · string · required · format date-time · example 2025-01-01T00:00:00.000Z
    
    ISO 8601 timestamp.
400 Bad Request
- error · object · required
  
  Standard error payload.
  - code · string · required
    
    Machine-readable error code.
  - message · string · required
    
    Human-readable error message.
  - details · object
    
    Optional error details for debugging.
    - * · any
- meta · object
  - requestId · string · min length 1 · example req_example
    
    Request identifier for tracing.
401 Unauthorized

Same fields as 400.
403 Forbidden. Requires the transfer_batches.execute action: an API key must hold it (a module's manage or execute also covers its read), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and error.details.action names the action. Any other 403 names its own reason.

Same fields as 400.
404 Not Found

Same fields as 400.
409 Conflict

Same fields as 400.
422 Unprocessable Entity

Same fields as 400.
500 Internal Server Error

Same fields as 400.
502 Bad Gateway

Same fields as 400.
503 Service Unavailable

Same fields as 400.

Example request

IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST 'https://api-beta.solana.com/v1/payments/transfer-batches' \
  -H "Authorization: Bearer $SDP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_example",
    "sourceCustodyWalletId": "cwlt_example",
    "token": "SOL",
    "recipients": [
      {
        "externalId": "payroll_row_001",
        "counterpartyId": "cpty_example",
        "counterpartyAccountId": "cpacct_example",
        "amount": "25.00"
      }
    ],
    "externalId": "payroll_2026_06_30"
  }'

// Reuse this key when you retry this request.
const idempotencyKey = crypto.randomUUID();
const res = await fetch("https://api-beta.solana.com/v1/payments/transfer-batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SDP_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "projectId": "prj_example",
    "sourceCustodyWalletId": "cwlt_example",
    "token": "SOL",
    "recipients": [
      {
        "externalId": "payroll_row_001",
        "counterpartyId": "cpty_example",
        "counterpartyAccountId": "cpacct_example",
        "amount": "25.00"
      }
    ],
    "externalId": "payroll_2026_06_30"
  })
});

import os, requests, uuid

# Reuse this key when you retry this request.
idempotency_key = str(uuid.uuid4())
r = requests.post("https://api-beta.solana.com/v1/payments/transfer-batches",
  headers={"Authorization": f"Bearer {os.environ['SDP_API_KEY']}", "Idempotency-Key": idempotency_key},
  json={
    "projectId": "prj_example",
    "sourceCustodyWalletId": "cwlt_example",
    "token": "SOL",
    "recipients": [
      {
        "externalId": "payroll_row_001",
        "counterpartyId": "cpty_example",
        "counterpartyAccountId": "cpacct_example",
        "amount": "25.00"
      }
    ],
    "externalId": "payroll_2026_06_30"
  })

Example responses

JSON

{
  "data": {
    "batch": {
      "id": "xbatch_example",
      "organizationId": "org_example",
      "projectId": "prj_example",
      "externalId": "payroll_2026_06_30",
      "sourceCustodyWalletId": "cwlt_example",
      "sourceProviderWalletId": "privy_wallet_123",
      "sourceAddress": "So11111111111111111111111111111111111111112",
      "token": "SOL",
      "status": "processing",
      "totalAmount": "1000.00",
      "recipientCount": 20,
      "transactionCount": 1,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    },
    "recipients": [
      {
        "id": "_example",
        "batchId": "batch_example",
        "transferId": "xfr_example",
        "externalId": "payroll_row_001",
        "counterpartyId": "cpty_example",
        "counterpartyAccountId": "cpacct_example",
        "destination": "So11111111111111111111111111111111111111112",
        "amount": "100.00",
        "status": "pending",
        "error": "example",
        "createdAt": "2025-01-01T00:00:00.000Z",
        "updatedAt": "2025-01-01T00:00:00.000Z"
      }
    ],
    "transfers": [
      {
        "fireblocks": {
          "transactionId": "transaction_example",
          "status": "example",
          "subStatus": "example"
        },
        "id": "xfr_example",
        "organizationId": "org_example",
        "custodyWalletId": "cwlt_example",
        "providerWalletId": "privy_wallet_123",
        "projectId": "prj_example",
        "type": "transfer",
        "kind": "example",
        "direction": "outbound",
        "status": "confirmed",
        "signature": "sig_example",
        "serializedTx": "base64_tx_example",
        "slot": 123456,
        "blockTime": "2025-01-01T00:00:00.000Z",
        "confirmedAt": "2025-01-01T00:00:00.000Z",
        "fee": 0,
        "error": "Signature failed",
        "initiatedBy": {
          "type": "api_key"
        },
        "source": "So11111111111111111111111111111111111111112",
        "destination": "So11111111111111111111111111111111111111112",
        "amount": "100.00",
        "counterpartyId": "cpty_example",
        "counterpartyDisplayName": "Acme Studio",
        "risk": {
          "provider": "trm",
          "score": "0.12",
          "level": "low",
          "evaluatedAt": "2025-01-01T00:00:00.000Z"
        },
        "createdAt": "2025-01-01T00:00:00.000Z",
        "updatedAt": "2025-01-02T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

JSON

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Missing action: transfer_batches.execute",
    "details": {
      "action": "transfer_batches.execute"
    }
  },
  "meta": {
    "requestId": "req_example"
  }
}

Error responses use the standard error shape.

Create transfer batch

HeadersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Example requestCopy Anchor Link

Example responsesCopy Anchor Link

Headers

Request body

Responses

Example request

Example responses