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
• 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

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

Configuration: Set all four SKALE_* env vars to enable. The official SKALE Base Sepolia testnet RPC is:

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>

Admin endpoints (when BITE is enabled):

Method	Path	Description
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