ERC-4337 Sponsor Proxy Server Specification

ERC-4337 Sponsor Proxy Server — API Specification

API specification for a proxy server operated by a gas sponsorship service. WAIaaS agents register this proxy as a custom provider to send sponsored transactions.

1. Overview

Purpose

• Allow sponsorship service operators to sponsor gas fees without exposing their Pimlico/Alchemy API keys to agents
• Agents only need a proxy URL and a scope token to send sponsored transactions

Architecture

[WAIaaS Agent] --scope token--> [Sponsor Proxy] --API Key+PolicyId--> [Pimlico/Alchemy]

WAIaaS Integration

{
  "aaProvider": "custom",
  "aaBundlerUrl": "https://{proxy-host}/rpc/{chainId}?token={scope_token}",
  "aaPaymasterUrl": "https://{proxy-host}/rpc/{chainId}?token={scope_token}"
}

bundlerUrl and paymasterUrl may point to the same endpoint or be separated.

2. Authentication: Scope Token

A restricted-permission token issued to agents. The proxy manages issuance and validation internally.

Recommended Token-Bound Fields

Authentication Method

The scope token is passed as a URL query parameter:

POST /rpc/sepolia?token=scope_abc123

Header-based auth (Authorization: Bearer) is also possible, but query parameter is the most convenient for WAIaaS custom provider URLs which embed the token directly.

3. Endpoint

POST /rpc/{chainId}

A single endpoint handling both bundler and paymaster JSON-RPC methods.

Path Parameter:

Query Parameter:

Request Body: JSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendUserOperation",
  "params": [...]
}

Response: The backend provider's JSON-RPC response, forwarded as-is.

4. Supported Methods

4.1 Bundler Methods (ERC-4337) — Forward As-Is

Processing: Forward the request body to the backend provider without modification.

4.2 Paymaster Methods (ERC-7677) — Inject Context, Then Forward

Processing: Inject the scope token's policyId into params[3] (context), then forward.

Context Injection Logic

params[3] = ERC-7677 context object (optional parameter)

Provider-specific context field mapping:

Pseudocode:

function injectContext(method, params, scope) {
  if (method !== 'pm_getPaymasterData' && method !== 'pm_getPaymasterStubData') {
    return params; // Bundler method — no transformation
  }
  if (!scope.policyId) {
    return params; // No policyId — no injection needed
  }

  const context = scope.provider === 'pimlico'
    ? { sponsorshipPolicyId: scope.policyId }
    : { policyId: scope.policyId };

  // params[3] is the context position (ERC-7677)
  params[3] = { ...params[3], ...context };
  return params;
}

5. Error Responses

Proxy Errors

Return errors in standard JSON-RPC format.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Invalid or expired scope token"
  }
}

Backend Provider Errors

Forward the provider's JSON-RPC error response to the client as-is.

6. Scope Token Management API (Optional)

An admin API for the sponsorship service to manage tokens internally. WAIaaS does not call these endpoints — the format is entirely at the implementor's discretion.

Reference Design

POST   /admin/tokens          — Issue a token
GET    /admin/tokens           — List tokens
GET    /admin/tokens/{token}   — Token detail + usage stats
DELETE /admin/tokens/{token}   — Revoke a token

Token issuance request example:

{
  "name": "agent-wallet-1",
  "allowedChains": ["sepolia", "base-sepolia"],
  "maxSpendWei": "1000000000000000000",
  "expiresAt": 1741305600
}

7. Implementation Notes

Minimum Implementation Scope

1. Scope token validation — DB lookup or JWT decode
2. Chain / limit check — Compare against scope token metadata
3. Context injection — Inject policyId into paymaster methods (~5 lines)
4. JSON-RPC forward — fetch(providerUrl, { method: 'POST', body }) (~3 lines)

Core logic is under 100 lines. The rest is HTTP server boilerplate.

Backend Provider URL Assembly

Pimlico chainId mapping (partial):

Security Recommendations

• HTTPS required
• Scope tokens must have sufficient entropy (minimum 32 random bytes)
• Apply rate limiting (per IP + per token)
• Track sponsorship spend: accumulate actualGasCost from eth_getUserOperationReceipt for cap enforcement
• Method whitelist — allow only the 8 methods listed above, reject all others

Batch Requests (Optional)

viem may send JSON-RPC batch requests ([{...}, {...}]) in some cases. To support this, detect array input and apply per-request processing to each item.

Related

• Smart Account Lite / Full Mode Guide - Guide to using smart accounts with WAIaaS
• Architecture - System architecture including AA pipeline
• API Reference - REST API endpoints for UserOp operations