Overview

Tollbeam web client documentation

This page is intentionally scoped to what the current web client is actually wired to do. If a route, endpoint, or workflow is not described here, it is not currently integrated by this frontend.

The current app covers authentication, account profile management, password reset, application management, the public RPC integration example, transaction and budget reports, event logs, webhook configuration, and dashboard views for routing, billing, admin plan management, and admin account plan assignment.

Auth and session

Base URL, public routes, and protected access

Frontend API calls use NEXT_PUBLIC_API_BASE_URL. When that variable is not set, the code falls back to https://every-koalas.metalseed.io/v1.

Successful login stores a bearer token in local storage under tollbeam_token. Protected dashboard requests send that token in the Authorization header.

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

// Expected response shape used by the frontend
{
  "token": "jwt-or-session-token",
  "expiresAt": "2026-03-24T12:00:00Z",
  "user": {
    "email": "user@example.com"
  }
}

POST /auth/signup
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "companyName": "MyWallet Labs",
  "appName": "My First App",
  "role": "developer",
  "marketingOptIn": true,
  "termsAcceptedAt": "2026-03-17T15:00:00.000Z"
}

GET /auth/verify?token=<email-token>
GET /auth/me
POST /auth/logout

POST /auth/password-reset/request
{
  "email": "user@example.com"
}

POST /auth/password-reset/confirm
{
  "token": "<token-from-email>",
  "password": "NewPassword123"
}

Apps API

Manage application records and keys

The Apps screen at /dashboard/apps lists apps and supports create, update, and delete flows. The frontend is currently wired to GET /apps, POST /apps, and PUT /apps/:id, DELETE /apps/:id, plus POST /apps/:id/rotate-key.

API keys are now treated as one-time secrets. The full key is only shown from the create response or the rotate response. After that, the UI only displays api_key_prefix and api_key_last4.

GET /apps
Authorization: Bearer <token>

// Frontend expects masked key fields from list/detail responses
[
  {
    "id": "app_123",
    "name": "My Production App",
    "status": "active",
    "api_key_prefix": "abcd1234",
    "api_key_last4": "9xyz"
  }
]

POST /apps
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Production App",
  "status": "active",
  "daily_cap_wei": "5000000000000000000",
  "rev_share_bps": 250,
  "per_action_fee_minor": 100,
  "allowlist": ["0x1234..."],
  "denylist": ["0xabcd..."]
}

// Full API key is only returned here, on creation
{
  "id": "app_123",
  "name": "My Production App",
  "status": "active",
  "api_key": "FULL-KEY-ONLY-ONCE",
  "api_key_prefix": "abcd1234",
  "api_key_last4": "9xyz"
}

POST /apps/:id/rotate-key
Authorization: Bearer <token>

// Full replacement key is only returned here, on rotation
{
  "api_key": "NEW_FULL_KEY_ONLY_ONCE",
  "api_key_prefix": "wxyz5678",
  "api_key_last4": "1abc"
}

PUT /apps/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Renamed App",
  "status": "paused"
}

DELETE /apps/:id
Authorization: Bearer <token>

{
  "status": "deleted"
}

RPC endpoint

Primary JSON-RPC gateway for client traffic

The primary client load target is POST /v1/:chain/rpc. Current production examples use /v1/alchemy/rpc and /v1/pimlico/rpc for the supported mainnet routes. This is the JSON-RPC gateway your AA client points to; it is not a dashboard CRUD endpoint.

Requests use your app API key in the Authorization: Bearer <app api_key> header. The documented supported methods are pm_sponsorUserOperation and eth_sendUserOperation. The public docs now use the provider-backed mainnet route values alchemy and pimlico in the RPC path examples.

POST /v1/alchemy/rpc
Authorization: Bearer <app api_key>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "pm_sponsorUserOperation",
  "params": ["<userOperation>", "<entryPoint>", "<context>"]
}

// JSON-RPC response shape
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "...": "..." }
}

Reports API

Transactions, budgets, and CSV export

The usage dashboard at /dashboard is currently backed by transaction and budget report endpoints. Transactions support limit, date, and appId query parameters. Budgets support appId. Both report types can be exported with format=csv.

GET /reports/transactions?limit=200&date=2026-03-17&appId=app_123
Authorization: Bearer <token>

// Frontend expects
{
  "data": [
    {
      "id": "tx_01",
      "appId": "app_123",
      "chain": "Arbitrum One",
      "chainId": 42161,
      "txHash": "0x...",
      "status": "sponsored",
      "provider": "alchemy",
      "sponsoredWei": "1000000000000000",
      "feeMinor": "2000000000000000",
      "createdAt": "2026-03-17T12:00:00Z"
    }
  ],
  "count": 1
}

GET /reports/budgets?appId=app_123
Authorization: Bearer <token>

// Frontend expects
{
  "data": [
    {
      "appId": "app_123",
      "dailyCapWei": "5000000000000000000",
      "usedTodayWei": "1200000000000000000",
      "resetsAt": "2026-03-18T00:00:00Z"
    }
  ],
  "count": 1
}

GET /reports/transactions?format=csv&limit=200
GET /reports/budgets?format=csv

Logs API

Filterable event log stream

The Event Logs page at /dashboard/logs fetches /logs with optional filters for app, event type, status, and date range. The UI accepts either a bare array or an object containing data.

GET /logs?appId=app_123&eventType=userop.sponsored&status=success&startDate=2026-03-01&endDate=2026-03-17
Authorization: Bearer <token>

Webhooks API

Per-app webhook config, testing, and secret rotation

The webhooks screen uses /webhooks/config to list app webhook settings, update a webhook URL, and rotate signing secrets. Test deliveries are sent through /webhooks/test.

GET /webhooks/config
Authorization: Bearer <token>

PUT /webhooks/config?appId=app_123
Authorization: Bearer <token>
Content-Type: application/json

{
  "webhookUrl": "https://your-app.com/webhooks/tollbeam"
}

POST /webhooks/config/rotate-secret?appId=app_123
Authorization: Bearer <token>

POST /webhooks/test?appId=app_123
Authorization: Bearer <token>
Content-Type: application/json

{
  "eventType": "userop.sponsored"
}

Dashboard coverage

What the current web client exposes

Some dashboard pages in this repo are primarily UI surfaces rather than fully wired CRUD integrations. This section captures the current state so the docs stay accurate.

• Usage and reports: live transactions, budgets, CSV export, and app/date filtering are wired.
• Apps: list, create, update, and API key rotation are wired; delete is also supported from the edit flow. Full API keys are only revealed once on create or rotate, then only prefix and last4 are shown.
• Logs: filterable event stream with a detail modal is wired.
• Webhooks: list, URL update, test send, and secret rotation are wired.
• Account profile: PATCH /users/me is wired for profile updates.
• Account security: the page currently sends a password reset email for the signed-in user; it is not a direct in-app password change form.
• Routing and chains: the page is now a trimmed-back read-only reference that links to public status and docs. The dashboard is not wired to a dedicated routing admin API yet, and the documented mainnet RPC routes remain /v1/alchemy/rpc and /v1/pimlico/rpc.
• Billing: summary, public tiers, account plan changes, top-up checkout, subscription checkout, and the transaction ledger are wired in the current client.
• Admin billing plans: GET /billing/admin/tiers, PUT /billing/admin/tiers/:key, and DELETE /billing/admin/tiers/:key are wired for admin sessions.
• Admin users: GET /admin/users, GET /admin/users/:userId, PATCH /admin/users/:userId, and PUT /admin/users/:userId/enterprise-plan are wired for admin sessions.
• Admin plan assignment: GET /billing/admin/tiers and PATCH /billing/admin/accounts/:userId/tier are wired from the admin user detail screen, including the returned subscriptionMismatch warning state.
• Browser access: hosted frontend origins must be allowlisted by backend CORS settings such as FRONTEND_BASE_URL or CORS_ALLOWED_ORIGINS, or browser requests will fail with origin_not_allowed.

Changelog

Documentation releases

• March 17, 2026
  Version 1.0.0
  First complete docs pass aligned to the current frontend: auth flows, password reset, apps, hosted RPC example, reports, logs, webhooks, and dashboard coverage.