Sign in
latestOpenAPI 3.0.32026-08-20146131.7 MB

672b1916ba61

Payments

Create transfer batch

Executes a custody-signed outbound transfer batch to counterparty crypto-wallet accounts, chunks recipients into Solana transactions, and returns the batch, recipient, and transfer records. Supply an Idempotency-Key to retry safely: an identical resolved request returns the original batch without another on-chain submission, while reusing the key for a different request returns 409.

post/v1/payments/transfer-batches

Headers

x-project-idstring

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Example:prj_example

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Idempotency-Keystring

Idempotency key for safely retrying mutating requests. 1-255 printable ASCII characters; echoed back on the response.

Example:idempotency_example_12345

Idempotency key for safely retrying mutating requests. 1-255 printable ASCII characters; echoed back on the response.

Request body

projectIdstring

Project identifier for the transfer batch context.

externalIdstring

Caller-provided batch correlation ID. Not used as an idempotency key.

sourcestring required

Source wallet — the walletId field returned by GET /v1/wallets. The wallet record id and the public key are not accepted.

tokenstring required

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.

Example request

{
  "projectId": "prj_example",
  "externalId": "payroll_2026_06_30",
  "source": "privy_wallet_123",
  "token": "SOL",
  "recipients": [
    {
      "externalId": "payroll_row_001",
      "counterpartyId": "cp_example",
      "counterpartyAccountId": "cpa_example",
      "amount": "25.00"
    }
  ],
  "options": {
    "maxRecipientsPerTransaction": 20,
    "priorityFee": "auto",
    "preflight": true
  }
}

Response

Transfer batch created

Example response

{
  "data": {
    "batch": {
      "id": "xbatch_example",
      "organizationId": "org_example",
      "projectId": "prj_example",
      "externalId": "payroll_2026_06_30",
      "sourceWalletId": "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": [
      {
        "transferId": "xfr_example",
        "externalId": "payroll_row_001",
        "counterpartyId": "cp_example",
        "counterpartyAccountId": "cpa_example",
        "destination": "So11111111111111111111111111111111111111112",
        "amount": "100.00",
        "status": "pending",
        "createdAt": "2025-01-01T00:00:00.000Z",
        "updatedAt": "2025-01-01T00:00:00.000Z"
      }
    ],
    "transfers": [
      {
        "id": "xfr_example",
        "organizationId": "org_example",
        "walletId": "privy_wallet_123",
        "projectId": "prj_example",
        "type": "transfer",
        "direction": "outbound",
        "status": "confirmed",
        "signature": "sig_example",
        "serializedTx": "base64_tx_example",
        "slot": 123456,
        "blockTime": "2025-01-01T00:00:00.000Z",
        "fee": 5000,
        "error": "Signature failed",
        "initiatedBy": {
          "type": "api_key"
        },
        "source": "So11111111111111111111111111111111111111112",
        "destination": "So11111111111111111111111111111111111111112",
        "rampsMemo": {
          "invoice": "INV-123",
          "po": "PO-9"
        },
        "amount": "100.00",
        "provider": "moonpay",
        "counterpartyId": "counterparty_example",
        "counterpartyDisplayName": "Acme Studio",
        "providerReference": "ramp_quote_example",
        "deliveryMode": "session_widget",
        "fiatCurrency": "USD",
        "fiatAmount": "100.00",
        "risk": {
          "provider": "trm",
          "score": "0.12",
          "level": "low",
          "evaluatedAt": "2025-01-01T00:00:00.000Z"
        },
        "moneygram": {
          "transactionId": "mgi_tx_example",
          "referenceNumber": "12345678",
          "payoutAmount": 25,
          "payoutStatus": "completed",
          "cryptoTransferId": "xfr_moneygram_crypto_leg_example",
          "solanaTxSignature": "sig_moneygram_usdc_transfer_example",
          "lastWidgetError": "Transaction cancelled by user"
        },
        "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"
  }
}