Solana Batch Payments

Solana Batch Payments (Spraay Gateway)

Send SOL or any SPL token to up to 1,000 wallets in a single request, non-custodially, paid per-call via x402. No signup, no API key, no private key handed to anyone.

Why this instead of a wallet skill

• Non-custodial by design. Endpoints return base64 unsigned transactions. You sign locally with the sender wallet and submit. The gateway never holds funds or keys.
• Batch is the primitive. 1 recipient or 1,000 — one request, auto-chunked into optimally packed transactions (14 SOL transfers/tx, 7 SPL transfers/tx with ATA creation).
• x402 native. Each call is paid with a tiny USDC payment on Solana. 402 Payment Required → pay → retry with proof. Agents with any x402 client can use it immediately.

Gateways

Discovery manifests: GET /.well-known/x402 on either gateway (free).

Endpoints — Solana Gateway

A 0.3% transfer fee (30 bps) is added as an instruction inside the batch — visible in the returned transactions before you sign. Nothing is hidden.

Endpoints — Solana on the main gateway

Workflow: batch airdrop in 4 steps

1. Quote (optional): GET /solana/quote?recipients=250&token=BONK → tx count + network fees.
2. Build: POST /solana/batch-send-token with mint, recipients[], and sender (the payer public key). Handle the x402 402→pay→retry flow (see reference.md).
3. Sign & submit: Response contains transactions[] (base64, unsigned) + blockhash. Sign each with the sender keypair, submit to any RPC. Helper: scripts/sign-and-send.js.
4. Verify: GET /solana/status/ for each tx.

Example request

curl -X POST https://gateway-solana.spraay.app/solana/batch-send-token \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: " \
  -d '{
    "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "sender": "",
    "recipients": [
      { "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "amount": 1000 },
      { "address": "7S3P4HxJpyyigGzodYwHtCxZyUQe9JiBMHyLWP9SfKFJ", "amount": 500 }
    ]
  }'

sender is required — it's the fee payer and source of funds for the unsigned txs. amount is human-readable units.

Example response (shape)

{
  "success": true,
  "custodial": false,
  "recipients": 2,
  "feeBps": 30,
  "transactionCount": 1,
  "transactions": [""],
  "blockhash": "...",
  "lastValidBlockHeight": 123456789,
  "note": "Sign each transaction with the sender wallet and submit."
}

x402 payment flow

1. Send the request with no payment header → 402 Payment Required with USDC payment instructions (amount, treasury address, network).
2. Pay the requested USDC on Solana.
3. Retry with proof in the X-PAYMENT header.

Facilitators: devnet https://x402.org/facilitator, mainnet https://facilitator.payai.network. Any x402 client library handles this automatically — see reference.md for a manual walkthrough.

MCP option

Prefer tools over raw HTTP? The gateway ships an MCP server:

npx -y spraay-x402-mcp   # main gateway, 183 tools incl. all Solana endpoints

Or from source: node mcp/spraay-solana-mcp.js (repo) — exposes spraay_solana_batch_send_sol, spraay_solana_batch_send_token, spraay_solana_quote, spraay_solana_tx_status.

Guardrails

• Always run /solana/quote first for batches > 50 recipients and show the user the cost before building.
• Validate addresses are base58 Solana pubkeys before submitting; the gateway rejects invalid ones but a pre-check saves the call fee.
• Blockhash expiry: sign and submit promptly after building. If lastValidBlockHeight passes, rebuild (re-call the endpoint).
• Never ask the user for a private key to send to the gateway — it doesn't accept keys, only public keys. Signing happens locally.
• Devnet is available for dry runs; check /health for the active network.

See reference.md for full request/response schemas and error codes.