Create transfer batch

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

HeadersCopy Anchor Link

• 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 bodyCopy Anchor Link

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

• options · object

  Execution options for transaction chunking, priority fees, and preflight validation.

  • maxRecipientsPerTransaction · integer · min 1 · max 64

  • priorityFee · string · one of none, low, medium, high, auto

  • preflight · boolean

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

ResponsesCopy Anchor Link

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

      • 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 · one of pending, processing, confirmed, finalized, failed, awaiting_payment, settling, completed, canceled, expired · 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. A ramp is confirmed once its delivery is verified onchain.

      • fee · integer | null · required · example 5000

        Transaction fee in lamports.

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

      • rampsMemo · object · required

        Free-form key-value memo for offchain reconciliation of ramp transfers. At most 20 entries.

        • * · string · min length 1 · max length 256

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

      • providerReference · string · example ramp_quote_example

        Provider quote or transaction reference used for ramp correlation.

      • deliveryMode · string · one of hosted, manual_instructions, session_widget · example session_widget

        Ramp delivery mode. Hosted flows require the customer to complete a provider-hosted UI; manual instructions require the customer to fund displayed instructions; session widgets use a provider SDK session.

      • fiatCurrency · string · example USD

        Fiat currency for the ramp leg.

      • fiatAmount · string · example 100.00

        Quoted fiat amount for the ramp leg: what the customer pays on an on-ramp, the payout quoted on an off-ramp. It never changes after the quote; an off-ramp's final payout is fiatPayout.

      • fiatPayout · object

        What the provider reports paying out once it settles an off-ramp sale. Provider-reported: SDP cannot verify a bank payout.

        • amount · string · required · example 20.82

          Fiat paid out, in display units. Differs from the quoted fiatAmount when the provider re-prices the sale at receipt.

        • currency · string · required · example USD

          ISO currency of the payout, as the provider reports it.

        • reportedAt · string · format date-time · example 2025-01-02T00:00:00.000Z

          When the provider reported the payout.

      • deliveryMismatch · object

        Present while SDP holds a provider-settled ramp in settling because the chain contradicts the provider's delivery. A new provider report clears it.

        • reason · string · required · one of provider_report_mismatch, transaction_failed, predates_transfer, not_delivered, amount_mismatch, transaction_not_found · example amount_mismatch

          Why the chain contradicts the provider: provider_report_mismatch (its report contradicts SDP's record), transaction_failed, predates_transfer (the transaction landed before the transfer), not_delivered (nothing of the quoted asset reached the quoted wallet), amount_mismatch, or transaction_not_found (no finalized transaction an hour after the report; SDP keeps checking, and a later delivery completes the transfer).

        • checkedAt · string · required · format date-time · example 2025-01-02T00:00:00.000Z

          When SDP's delivery check reached this verdict.

        • reportedAmount · string · example 20

          What the provider reported delivering, in display units.

        • observedAmount · string · example 0.5

          What the chain shows the quoted wallet received, in display units.

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