> Solana Developer Platform docs, served as Markdown. The [docs index](https://platform.solana.com/docs.md) lists every page and [llms.txt](https://platform.solana.com/docs/ai/llms.txt) the key ones; [SKILL.md](https://platform.solana.com/SKILL.md) has the rules for building on SDP. # 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-batches` 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](/docs/developing-with-sdp/authentication) 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](/docs/developing-with-sdp/idempotency). ## 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 - **`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. ## 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. - **`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`. ## Example request ```bash tab="cURL" curl -X POST 'https://api.solana.com/v1/payments/transfer-batches' \ -H "Authorization: Bearer $SDP_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -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" } ], "options": { "maxRecipientsPerTransaction": 20, "priorityFee": "auto", "preflight": true }, "externalId": "payroll_2026_06_30" }' ``` ```ts tab="TypeScript" const res = await fetch("https://api.solana.com/v1/payments/transfer-batches", { method: "POST", headers: { Authorization: `Bearer ${process.env.SDP_API_KEY}`, "Idempotency-Key": crypto.randomUUID(), "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" } ], "options": { "maxRecipientsPerTransaction": 20, "priorityFee": "auto", "preflight": true }, "externalId": "payroll_2026_06_30" }) }); ``` ```python tab="Python" import os, requests, uuid r = requests.post("https://api.solana.com/v1/payments/transfer-batches", headers={"Authorization": f"Bearer {os.environ['SDP_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}, json={ "projectId": "prj_example", "sourceCustodyWalletId": "cwlt_example", "token": "SOL", "recipients": [ { "externalId": "payroll_row_001", "counterpartyId": "cpty_example", "counterpartyAccountId": "cpacct_example", "amount": "25.00" } ], "options": { "maxRecipientsPerTransaction": 20, "priorityFee": "auto", "preflight": True }, "externalId": "payroll_2026_06_30" }) ``` ## Example responses ```json tab="200" { "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": 5000, "error": "Signature failed", "initiatedBy": { "type": "api_key" }, "source": "So11111111111111111111111111111111111111112", "destination": "So11111111111111111111111111111111111111112", "rampsMemo": { "invoice": "INV-123", "po": "PO-9" }, "amount": "100.00", "counterpartyId": "cpty_example", "counterpartyDisplayName": "Acme Studio", "providerReference": "ramp_quote_example", "deliveryMode": "session_widget", "fiatCurrency": "USD", "fiatAmount": "100.00", "fiatPayout": { "amount": "20.82", "currency": "USD", "reportedAt": "2025-01-02T00:00:00.000Z" }, "deliveryMismatch": { "reason": "amount_mismatch", "checkedAt": "2025-01-02T00:00:00.000Z", "reportedAmount": "20", "observedAmount": "0.5" }, "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 tab="403" { "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](/docs/reference/conventions/errors).