Tollbeam logotollbeam
Get started

Developer sandbox / Quickstart

Sandbox quickstart

Everything below runs against testnet. Sandbox keys route to base-sepolia, optimism-sepolia, arbitrum-sepolia and are blocked from mainnet chains at the router, not just in the UI.

1. Get a sandbox key

Use the signup form or hit the endpoint directly. The key is returned once, in the signup response.

POST /v1/auth/sandbox-signup
curl -X POST https://api.tollbeam.com/v1/auth/sandbox-signup \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "password": "CorrectHorse42Battery",
    "termsAcceptedAt": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"
  }'
# The response includes "api_key" - shown only once.

2. Sponsor a UserOperation

Tollbeam compares Pimlico and Alchemy for every request and returns the cheapest quote with its paymasterAndData.

pm_sponsorUserOperation
curl -X POST https://api.tollbeam.com/v1/base-sepolia/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOLLBEAM_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "pm_sponsorUserOperation",
    "params": [{
      "sender": "0xYourSmartAccount",
      "nonce": "0x0",
      "initCode": "0x",
      "callData": "0x",
      "callGasLimit": "0x30000",
      "verificationGasLimit": "0x30000",
      "preVerificationGas": "0x10000",
      "maxFeePerGas": "0x3b9aca00",
      "maxPriorityFeePerGas": "0x3b9aca00",
      "paymasterAndData": "0x",
      "signature": "0x"
    }]
  }'

3. Re-sign, then submit

The step everyone misses: paymasterAndData is included in the userOpHash. After sponsorship you must re-sign the UserOperation, or the EntryPoint rejects it with an invalid-signature error.
eth_sendUserOperation
curl -X POST https://api.tollbeam.com/v1/base-sepolia/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOLLBEAM_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "eth_sendUserOperation",
    "params": [{ ...signedUserOpWithPaymasterAndData }]
  }'

Full flow with the SDK

@tollbeam/sdk wraps both RPC calls. Bring your own signer and bundler-compatible smart account.

TypeScript
import { sponsorUserOperation, sendUserOperation } from "@tollbeam/sdk";

const baseUrl = "https://api.tollbeam.com";
const chain = "base-sepolia";
const apiKey = process.env.TOLLBEAM_API_KEY;

// 1. Get sponsorship (Tollbeam quotes every provider, returns the cheapest)
const sponsor = await sponsorUserOperation(baseUrl, chain, userOp, { apiKey });

// 2. Apply the sponsor fields
userOp.paymasterAndData = sponsor.paymasterAndData;
userOp.callGasLimit = sponsor.callGasLimit;
userOp.verificationGasLimit = sponsor.verificationGasLimit;
userOp.preVerificationGas = sponsor.preVerificationGas;

// 3. RE-SIGN the userOp. paymasterAndData is part of the userOpHash,
//    so the original signature is no longer valid.
userOp.signature = await signUserOpHash(userOp);

// 4. Submit
const sent = await sendUserOperation(baseUrl, chain, userOp, {
  apiKey,
  quoteId: sponsor.quoteId,
});
console.log(sent.userOpHash, sent.txHash);

Sandbox limits

  • - Testnet chains only: base-sepolia, optimism-sepolia, arbitrum-sepolia.
  • - Hacker tier: $50 signup credit and 10,000 routed ops per month.
  • - Dashboard login (logs, key rotation, webhooks) unlocks after you verify the email we sent at signup.
  • - Ready for mainnet? Verify your email, log in, and create a production app from the dashboard.
Try a live callFull API docs