RequestTap x402 Router

Open Source x402 API Router. Instantly turn any API into a USDC pay-per-request service for AI agents.

---

Table of Contents

• Key Features
• Architecture
• Quick Start
• Production Deployment
• Configuration
• BITE Encryption
• API Endpoints
• Agent Guide
• Claude Code Commands
• Contributing
• Security
• Changelog
• License

---

Key Features

• x402 Payments - Native HTTP 402 payment flow on Base (USDC)
• AP2 Mandates - Spend caps, tool allowlists, expiry, signature verification (Mandate + IntentMandate)
• Replay Protection - Idempotency key + request hash deduplication
• SSRF Protection - Blocks private/reserved IP ranges at route compile time
• x402 Upstream Detection - Rejects routes that already speak x402 to prevent markup/middleman abuse
• Agent Access Control - Block specific agent addresses and check ERC-8004 on-chain reputation scores
• API Key Auth - Optional API key requirement for gateway routes
• Rate Limiting - 100 requests/min per IP via express-rate-limit
• Security Headers - helmet + CORS middleware on all responses
• BITE Encryption - Optional SKALE BITE for encrypted premium intents
• Receipts - Structured JSON receipts for every request (SUCCESS, DENIED, ERROR)

Architecture

AI Agent  ──>  Agent SDK  ──>  Gateway  ──>  Upstream API
                  │              │
                  │         ┌────┴─────────┐
                  │         │   Pipeline   │
                  │         ├──────────────┤
                  │         │ Rate Limit   │ ← 100 req/min
                  │         │ API Key Auth │
                  │         │ Access Ctrl  │ ← Blacklist + ERC-8004
                  │         │ Route Match  │ ← OpenAPI 3.0
                  │         │ Idempotency  │
                  │         │ AP2 Mandate  │ ← EIP-191 Signatures
                  │         │ x402 Payment │ ← Base L2 / USDC
                  │         │ BITE Encrypt │ ← SKALE Network
                  │         │ Proxy        │
                  │         │ Receipt      │
                  │         └──────────────┘
                  │
                  └── Receipts (SUCCESS / DENIED / ERROR)

Payments: x402 Protocol → Coinbase CDP → Base L2 (USDC)
Encryption: SKALE BITE → SKALE V4 Consensus → Threshold Encryption
Signing: viem → EIP-191 Personal Sign → EIP-155 Chain IDs
Contracts: Solidity → Hardhat → SKALE Deployment

Monorepo Structure

Package	Description
packages/shared	Types, schemas, constants
packages/gateway	Express HTTP gateway with middleware pipeline
packages/sdk	Agent client SDK (RequestTapClient)
dashboard	Admin dashboard & debug tools
examples/agent-demo	Demo script
contracts/	SKALE BITE Solidity contract

Prerequisites

• Node.js v20+
• Coinbase Developer Platform (CDP) API key — required by the Agent SDK to create wallets and make USDC payments

Getting CDP Credentials

1. Go to portal.cdp.coinbase.com and create a project
2. Navigate to API Keys → Create API Key
3. Configure the key:
   • API-specific restrictions: enable Server Wallet → Accounts only
   • Signature algorithm: Ed25519 (recommended)
   • Skip Coinbase App & Advanced Trade permissions (not needed)
4. Copy the API key credentials into your .env:

   CDP_API_KEY_ID=<your key id>
   CDP_API_KEY_SECRET=<your key secret>
   

5. Generate a Wallet Secret (required for signing transactions):
   • Go to Server Wallet dashboard
   • Select your project from the dropdown
   • In the Wallet Secret section, click Generate
   • Save it immediately — it is shown only once
   • Add it to your .env:

     CDP_WALLET_SECRET=<base64-encoded PKCS8 EC P-256 key>
     

Note: The Wallet Secret is generated by CDP's Trusted Execution Environment (TEE) and cannot be created locally. It is a base64-encoded PKCS8 DER EC P-256 private key used to sign wallet-auth JWTs.

Quick Start

# 1. Copy config files and add your secrets
cp .env.example .env          # add CDP keys + RT_PAY_TO_ADDRESS
cp packages/gateway/routes.example.json routes.json

# 2. Install and build
npm install
npm run build

# Start gateway (port 4402)
node --env-file=.env packages/gateway/dist/index.js

# Start dashboard (port 3000) — in a separate terminal
node dashboard/server.js

Then open:

• Dashboard: http://localhost:3000/dashboard
• API Docs: http://localhost:3000/docs
• Gateway Health: http://localhost:4402/admin/health (requires Authorization: Bearer <RT_ADMIN_KEY>)

Run Tests

npm test                                    # all workspaces
npm test --workspace=packages/gateway       # gateway only

Production Deployment

In production, the RT gateway must be the public-facing entry point for all API routes. The gateway handles x402 payment challenges, verifies payments, proxies to your upstream API, and injects any required auth headers automatically. If agents reach your upstream directly (bypassing the gateway), they'll get auth errors instead of the expected 402 Payment Required.

Recommended: Reverse Proxy

Put a reverse proxy (nginx, Caddy, Cloudflare, Traefik) in front that routes API traffic through the gateway:

                 ┌─────────────────────────────────────────┐
                 │          Reverse Proxy (nginx)          │
Internet ──────>│                                         │
                 │  /api/v1/*  ──>  RT Gateway (:4402)    │
                 │  /health    ──>  RT Gateway (:4402)    │
                 │  /docs      ──>  RT Gateway (:4402)    │
                 │  /*         ──>  Upstream App (:8000)   │ ← landing page, etc.
                 └─────────────────────────────────────────┘
                                      │
                           RT Gateway handles:
                           • x402 payment (402 → pay → 200)
                           • Auth injection to upstream
                           • Receipts, mandates, replay protection

Example nginx config:

# API routes → RT Gateway (x402 payment + proxy)
location /api/v1/ {
    proxy_pass http://localhost:4402;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

# Gateway public endpoints
location /health {
    proxy_pass http://localhost:4402;
}
location /docs {
    proxy_pass http://localhost:4402;
}

# Everything else → upstream app (landing page, static assets)
location / {
    proxy_pass http://localhost:8000;
}

Example Docker Compose:

services:
  gateway:
    build: .
    command: node --env-file=.env packages/gateway/dist/index.js
    ports:
      - "4402:4402"
    env_file: .env

  api:
    image: your-upstream-api
    # No public port — only reachable by the gateway
    expose:
      - "8000"

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf

Common Mistake

If your upstream API has its own auth (API keys, tokens), agents should not need that key. The gateway injects upstream auth automatically via the route's provider.auth config:

{
  "path": "/api/v1/companies",
  "price_usdc": "0.01",
  "provider": {
    "backend_url": "http://api:8000",
    "auth": {
      "header": "X-Api-Key",
      "value": "your-internal-api-key"
    }
  }
}

Agents pay USDC — that is their authentication. If agents get a 401 instead of 402, it means requests are bypassing the gateway and hitting the upstream directly.

Verify Your Deployment

After deploying, confirm the gateway is in the request path:

# Should return 402 Payment Required (not 401 or 200)
curl -s -o /dev/null -w "%{http_code}" https://your-domain.com/api/v1/your-paid-endpoint

# Should return {"status":"ok"}
curl -s https://your-domain.com/health

You can also use the provider test script:

npx tsx scripts/test-x402-provider.ts https://your-domain.com --dry-run

Configuration

Set environment variables or create a .env file (see .env.example):

Variable	Required	Default	Description
RT_PAY_TO_ADDRESS	yes	—	USDC payment destination (Ethereum address)
RT_PORT	no	4402	Gateway listen port
RT_ADMIN_KEY	no	—	Bearer token for admin API
RT_FACILITATOR_URL	no	Coinbase facilitator	x402 facilitator URL
RT_BASE_NETWORK	no	base-sepolia	Base network name
RT_ROUTES_FILE	no	—	Path to routes JSON file
RT_GATEWAY_DOMAIN	no	—	Gateway domain for IntentMandate merchant matching (falls back to Host header)
RT_REPLAY_TTL_MS	no	300000	Replay protection window in milliseconds (5 min)
RT_SKIP_X402_PROBE	no	false	Skip x402 upstream detection on route registration
ERC8004_RPC_URL	no	—	RPC URL for ERC-8004 reputation registry
ERC8004_CONTRACT	no	—	ERC-8004 Reputation Registry contract address
ERC8004_MIN_SCORE	no	20	Minimum reputation score to allow requests
SKALE_RPC_URL	no	—	SKALE RPC endpoint (enables BITE encryption)
SKALE_CHAIN_ID	no	—	SKALE chain ID
SKALE_BITE_CONTRACT	no	—	BITE contract address
SKALE_PRIVATE_KEY	no	—	SKALE signing key

BITE Encryption (SKALE)

Optional threshold encryption for payment intents using SKALE BITE (Blockchain Integrated Threshold Encryption). When enabled, premium request data is encrypted before consensus and only revealed after payment confirmation.

How it works:

1. Gateway encrypts calldata via @skalenetwork/bite (BITE.encryptTransaction())
2. Encrypted intent is stored on-chain (storeIntent)
3. After x402 payment confirms, markPaid triggers the threshold decryption reveal
4. Decrypted data is read back via getIntent

Networks:

Network	Chain ID	RPC	Gas Token	Notes
SKALE Base Sepolia (testnet)	324705682	https://base-sepolia-testnet.skalenodes.com/v1/jubilant-horrible-ancha	sFUEL (free)	Best for development
SKALE Base (mainnet)	1187947933	https://skale-base.skalenodes.com/v1/base	CREDIT	Permissionless, no subscription needed

Testnet configuration:

SKALE_RPC_URL=https://base-sepolia-testnet.skalenodes.com/v1/jubilant-horrible-ancha
SKALE_CHAIN_ID=324705682
SKALE_BITE_CONTRACT=<your deployed BiteIntentStore address>
SKALE_PRIVATE_KEY=<private key with sFUEL for gas>

Mainnet configuration:

SKALE_RPC_URL=https://skale-base.skalenodes.com/v1/base
SKALE_CHAIN_ID=1187947933
SKALE_BITE_CONTRACT=<your deployed BiteIntentStore address>
SKALE_PRIVATE_KEY=<private key with CREDITS for gas>

SKALE Base Mainnet setup:

1. Buy CREDITS at base.skalenodes.com/credits using the wallet from SKALE_PRIVATE_KEY
2. Deploy the contract: cd contracts && npm run deploy:base-mainnet
3. Set SKALE_BITE_CONTRACT to the deployed address

SKALE Base mainnet is permissionless — no chain subscription required. Developers purchase CREDITS (with USDC or SKL) to pay for gas. The dashboard sidebar shows your current CREDIT balance when connected to mainnet.

Contract deployment scripts:

npm run deploy:calypso       # Calypso testnet
npm run deploy:base-sepolia  # SKALE Base Sepolia testnet
npm run deploy:base-mainnet  # SKALE Base mainnet

Admin endpoints (when BITE is enabled):

Method	Path	Description
GET	/admin/skale/status	Wallet address and CREDIT balance
POST	/admin/skale/test-anchor	Test SKALE connectivity
GET	/admin/skale/intent/:id	Read intent state
POST	/admin/skale/reveal/:id	Manually trigger reveal

API Endpoints

Public

Method	Path	Description
GET	/health	Returns {"status":"ok"}
GET	/docs	OpenAPI spec for registered routes

Admin (requires Authorization: Bearer <RT_ADMIN_KEY>)

Method	Path	Description
GET	/admin/health	Gateway health, uptime, route & receipt counts
GET	/admin/config	Current gateway configuration (secrets masked)
GET	/admin/routes	List all routes
POST	/admin/routes	Add a single route
PUT	/admin/routes/:toolId	Update route (price, description, backend URL, etc.)
DELETE	/admin/routes/:toolId	Delete a route
POST	/admin/routes/import	Batch import routes from an OpenAPI spec
GET	/admin/receipts	Query receipts with filtering & pagination
GET	/admin/receipts/stats	Aggregate stats (total, success rate, USDC, latency)
GET	/admin/spend/:mandateId	Check daily spend for a mandate
GET	/admin/intent-spend/:mandateKey	Check lifetime spend for an IntentMandate
GET	/admin/dashboard-config	Get dashboard configuration
PUT	/admin/dashboard-config	Update dashboard configuration
GET	/admin/docs/openapi	Generate OpenAPI spec
GET	/admin/blacklist	List blacklisted agent addresses
POST	/admin/blacklist	Add agent address to blacklist
DELETE	/admin/blacklist/:address	Remove agent from blacklist
GET	/admin/reputation/:agentId	Query ERC-8004 on-chain reputation for an agent

Agent Guide

Building an AI agent that pays for API calls? See AGENTS.md for the full guide covering SDK setup, payment flow, AP2 mandates, receipts, and code examples.

Claude Code Commands

This repo includes Claude Code slash commands in .claude/commands/ for common dev workflows. Open the project in Claude Code and type / to see them:

Command	Description
/start	Build, generate demo .env & routes.json if missing, start gateway + dashboard, print URLs
/stop	Kill running gateway and dashboard processes
/restart	Stop, rebuild, and restart everything
/status	Show which services are running with uptime and route stats
/build	Build all TypeScript workspaces (or a specific one: /build gateway)
/run-tests	Run the test suite (or a specific workspace: /run-tests sdk)
/run-debug	Start gateway with Node --inspect + verbose logging for debugger attachment
/health	Hit admin API endpoints and display a health summary
/add-route	Add a new API route (via admin API if running, or edits routes.json)
/logs	Show recent gateway and dashboard log output

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests.

Security

To report a vulnerability, please email support@requesttap.ai — do not open public issues for security bugs. See SECURITY.md for full details.

Changelog

See CHANGELOG.md for a detailed list of changes in each release.

Contributors

Website

RequestTap.ai

Contact

support@requesttap.ai

License

MIT