Getting started

Welcome to the Tollbeam docs

Tollbeam is an ERC-4337 paymaster aggregator. Instead of integrating with a single paymaster, you point your account abstraction client at Tollbeam and we route your UserOperations to multiple providers based on price, latency, and health.

These docs will help you create an account, obtain an API key, and send your first sponsored UserOperation in just a few minutes.

Core concepts

Projects, keys, and environments

A project represents a single integration, such as your wallet SDK, Telegram mini-app, or game. Each project has its own API keys, routing configuration, and usage reports.

• API keys authenticate requests from your app to Tollbeam.
• Environments let you separate testnets and mainnets.
• Partner projects can earn a 15% share of net fees on adopted traffic.

UserOperations & sponsorship

For each sponsored UserOperation, Tollbeam records key data used to power your dashboard and partner reports:

• Timestamp and chain (e.g. OP Mainnet, Base, Arbitrum).
• Status (sponsored / failed).
• Fee charged to your project in USD terms.
• Underlying provider cost and net margin before rev-share.

API reference

Base URL & authentication

All API calls must be authenticated with a project-scoped API key. Include it in the Authorization header as a Bearer token.

POST https://api.tollbeam.xyz/v1/op-sepolia/rpc
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Example: create smart account

This example calls the underlying pimlico_createSmartAccountmethod via Tollbeam on OP Sepolia. Tollbeam will route this request to an appropriate provider and return the underlying result.

curl -X POST "https://api.tollbeam.xyz/v1/op-sepolia/rpc"   -H "Content-Type: application/json"   -H "Authorization: Bearer <YOUR_API_KEY>"   --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "pimlico_createSmartAccount",
    "params": [ { "owner": "0xYourEOA..." } ]
  }'

Response shape

In addition to the underlying paymaster response fields, Tollbeam may include extra metadata that describes how the request was routed.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "userOpHash": "0x...",
    "paymaster": "tollbeam",
    "routed_to": ["pimlico", "stackup"],
    "final_fee_usd": 0.014,
    "chain": "OP Sepolia",
    "status": "sent"
  }
}

SDKs

JavaScript / TypeScript SDK

The @tollbeam/sdk package provides a thin client for interacting with the Tollbeam paymaster aggregator from Node.js or browser-based dapps.

npm install @tollbeam/sdk

import { createClient } from "@tollbeam/sdk";

const tb = createClient({
  apiKey: process.env.TOLLBEAM_KEY!,
  chain: "op-sepolia",
  bundlerUrl: "https://<your-bundler>",
});

const res = await tb.paymaster.sponsor(userOp);
console.log(res.userOpHash);

Additional language bindings and framework integrations (wagmi, ethers v6 helpers, etc.) are on the roadmap.

Webhooks

Delivery of events to your backend

Tollbeam can notify your backend when UserOperations are sponsored, fail, or when your project balance crosses a threshold. Webhooks are signed with an HMAC secret configured in the dashboard.

• userop.sponsored – a UserOperation was successfully sponsored.
• userop.failed – a UserOperation failed permanently.
• balance.low – your prepaid balance dropped below a configured threshold.

Example payload

{
  "type": "userop.sponsored",
  "project_id": "proj_5u9...d0x",
  "userOpHash": "0x...",
  "chain": "op-mainnet",
  "fee_usd": 0.0148,
  "provider_cost_usd": 0.0061,
  "net_before_revshare_usd": 0.0087,
  "created_at": "2025-06-01T12:04:11Z"
}

Partner program

15% net fee share for adopted traffic

Wallets, SDKs, and toolkits that adopt Tollbeam as their default paymaster endpoint can enroll in the partner program. Partners earn 15% of net fees generated by projects attributed to their integration.

Net per UserOperation is computed as:

net_per_UO = fee_per_UO × (1 − 0.15) − provider_cost_per_UO

Aggregated partner earnings and payout history can be viewed in the dashboard under Partner rewards.

Changelog

Recent updates

• 2025-06-01
  Initial public docs
  Added getting started guide, API reference overview, SDK usage, webhook payloads, and partner program description.
• 2025-05-15
  Internal beta
  Onboarded first internal projects, connected OP/Base/Arbitrum testnets, and wired basic usage reporting.