payout_batch
Payroll and supplier payouts to many wallets in one batch, on Solana and on the nine EVM chains (those with loteSplit true in GET /v1/chains). EVM: up to 50 wallets, in a verified USD stablecoin (USDC, USDT, PYUSD, USDG, USD1) — the batch is ONE transaction through the Vurto IBBs split contract, and the payer pays the exact amounts PLUS a 0.1% Vurto fee on the total. Solana: up to 50 wallets, in any token the payer holds (no swap, no fee), packed into one or a few transactions. The paying wallet and every receiving wallet are screened first (OFAC SDN list and, on Solana, the issuer freeze of six stablecoins); a blocked payer refuses with payer_blocked (403), and one blocked recipient refuses the whole batch with receiver_blocked (403) and details.index of that row, before anything is created. Each recipient becomes a regular invoice (history, on-chain verification). EVM returns { invoices[], evm: { split, invoiceIds[], base, fee, batchRef, deadline, steps[] } }: sign steps IN ORDER with prepare_signing (the approve step first, then the pay transaction step), send them, and call payout_report_payment with the PAY transaction hash and evm.invoiceIds. Solana returns { invoices[], transactions[] }: sign each transactions[i].transaction (prepare_signing, then POST to /v1/svm/execute) and call payout_report_payment with that signature and its invoiceIds. checks (stablecoin token, both families) adds a PAID analysis of every destination, turning the batch into two steps. Scorechain runs on every EVM chain and Solana; Merkle Science (Didit) does not cover Gnosis, Unichain or Avalanche, so a check the chain lacks refuses with check_not_available_on_chain. With checks the response carries no transactions[]: Solana returns { invoices[], charge: { buildId, transaction, loteId, total, token, tokenDecimals, feeWallet, recipients }, reused[] } (prepare_signing with buildId and step {transaction}, POST to /v1/svm/execute); EVM returns the same charge plus charge.step, a transaction step ready for prepare_signing. Sign the charge transaction exactly as returned: it carries the mark that ties the payment to this charge (16 bytes after the transfer arguments on EVM, a memo on Solana). A transfer you build yourself is refused with analysis_payment_rejected, reason charge_not_tied, after the money has left; do not pay again, prove the wallet (destination_challenge with wallet = payer, receiver = details.feeWallet, chargeId = this charge and chargeTxHash = that hash, then destination_authorize) and report the same hash again. A Solana transaction expires in about a minute: POST /v1/payouts/charge/transaction with loteId and payer returns the same charge fresh, without another batch; if it also returns reportedTxHash, send that hash to payout_charge instead of signing, or you may pay twice. To pay the fee with another token, swap_build with tokenOut = charge.token, receiver = charge.feeWallet and loteId, with a minimum between charge.total and 10% above it. Then call payout_charge with that loteId, the charge hash/signature and the payer to analyse every destination, drop the blocked and get the approved send: Solana as transactions[] to sign, EVM as evm (the IBBs approve + pay steps of ONLY the approved, with the 0.1% fee recomputed on the approved base, with buildId, chainId and invoiceIds; if evm.deadline passed, call payout_charge again for a fresh one). Not re-charging a wallet already analysed (reused[]) needs the payer's signed session, which the API does not carry, so via MCP every destination is charged and reused[] is empty. Errors: batch_not_available_on_chain (an EVM chain without the IBBs contract), stablecoin_required (a checks batch in a non-stablecoin token), check_not_available_on_chain (a paid check the chain lacks, e.g. Merkle on Gnosis/Unichain/Avalanche), batch_duplicate_recipient (add the amounts up in one row), batch_self_payment, too_many_recipients, token_not_listed, screening_unavailable (503, try again).
Schema valid · SHA-256 b9ce0a9e20e0…
View input schema
{
"type": "object",
"properties": {
"chainId": {
"type": [
"integer",
"string"
],
"description": "EVM: integer from GET /v1/chains (1, 10, 56, 100, 137, 8453, 42161, 43114, 130). Solana: string from GET /v1/svm/chains (\"solana-mainnet\")."
},
"token": {
"type": "string",
"description": "Mint or symbol of a verified token, e.g. \"USDC\". Every recipient is paid in it. On EVM it must be a USD stablecoin; with checks on Solana it must be a USD stablecoin too."
},
"payer": {
"type": "string",
"description": "The wallet that signs and pays. EVM 0x address, or base58 on Solana."
},
"recipients": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"required": [
"wallet",
"amount"
],
"properties": {
"wallet": {
"type": "string",
"description": "Receiving wallet (EVM 0x address, or base58 on Solana, case-sensitive), or a Vurto user as \"@handle\": the Vurto Profile picks one of that user's wallets marked for regular transfers (the batch transaction carries it). The payer cannot be one of them, and each wallet appears once (up to 50, on EVM and on Solana)."
},
"amount": {
"type": "string",
"description": "Human amount, e.g. \"500\" or \"120.5\". Exactly this reaches the wallet."
},
"memo": {
"type": "string",
"description": "Optional note, up to 80 characters."
}
},
"additionalProperties": false
}
},
"checks": {
"type": "array",
"items": {
"type": "string",
"enum": [
"scorechain",
"merkle-science",
"crystal"
]
},
"description": "Optional, both families, stablecoin token: the paid analysis tools to run on every destination (\"crystal\" only for a payer with an approved KYC, proven by walletProof from kyc_proof: kyc_wallet_signature_required 401 without the proof, kyc_required 403 without the KYC; it adds its own price per destination). Turns the batch into the two-step charge flow above. Since 16/11/2026 charge.total is one consultation at the fixed price per destination (https://docs.vurto.cc/fees), the same with one tool or two, the reused ones included (their analysis comes from the history, the fee stays); a destination below the minimum goes without the paid analysis (free screening only), stays out of the charge and is listed in withoutAnalysis. payout_reuse with the amounts previews the total. A tool that already ran on that wallet for this payer up to 30 days ago, with no movement measured on the wallet since (on EVM: the same nonce, native balance and balance of every dollar stablecoin of the network, and no contract code; on Solana: no new confirmed signature and the same SOL and associated dollar stablecoin accounts; a read that fails, or any other token or NFT, is not seen, and then the provider is called), comes from the history instead of the provider; approved[].analyzedAt has, the day it ran."
},
"walletProof": {
"type": "string",
"description": "Only with \"crystal\": the walletProof of THIS wallet (the receiver on invoice_create, the payer on payout_batch) from kyc_proof (vkp_..., 30 minutes). Secret. It proves the wallet is yours; the KYC itself is read from that wallet."
}
},
"required": [
"chainId",
"token",
"payer",
"recipients"
],
"additionalProperties": false
}