RequestTap x402 Router

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

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

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

Copy the API key credentials into your .env:

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

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_passhttp://localhost:4402;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;}# Gateway public endpointslocation /health {proxy_passhttp://localhost:4402;}location /docs {proxy_passhttp://localhost:4402;}# Everything else → upstream app (landing page, static assets)location / {proxy_passhttp://localhost:8000;}

Example Docker Compose:

services:
gateway:
build: .command: node --env-file=.env packages/gateway/dist/index.jsports:
- "4402:4402"env_file: .envapi:
image: your-upstream-api# No public port — only reachable by the gatewayexpose:
- "8000"nginx:
image: nginx:alpineports:
- "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:

Gateway encrypts calldata via @skalenetwork/bite (BITE.encryptTransaction())
Encrypted intent is stored on-chain (storeIntent)
After x402 payment confirms, markPaid triggers the threshold decryption reveal
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:

Buy CREDITS at base.skalenodes.com/credits using the wallet from SKALE_PRIVATE_KEY
Deploy the contract: cd contracts && npm run deploy:base-mainnet
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

Navigation Menu

Uh oh!

Repository files navigation

RequestTap x402 Router

Table of Contents

Key Features

Architecture

Monorepo Structure

Prerequisites

Getting CDP Credentials

Quick Start

Run Tests

Production Deployment

Recommended: Reverse Proxy

Common Mistake

Verify Your Deployment

Configuration

BITE Encryption (SKALE)

API Endpoints

Public

Admin (requires `Authorization: Bearer <RT_ADMIN_KEY>`)

Agent Guide

Claude Code Commands

Contributing

Security

Changelog

Contributors

Website

Contact

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.claude/commands		.claude/commands
contracts		contracts
dashboard		dashboard
examples/agent-demo		examples/agent-demo
media		media
packages		packages
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

RequestTap x402 Router

Table of Contents

Key Features

Architecture

Monorepo Structure

Prerequisites

Getting CDP Credentials

Quick Start

Run Tests

Production Deployment

Recommended: Reverse Proxy

Common Mistake

Verify Your Deployment

Configuration

BITE Encryption (SKALE)

API Endpoints

Public

Admin (requires Authorization: Bearer <RT_ADMIN_KEY>)

Agent Guide

Claude Code Commands

Contributing

Security

Changelog

Contributors

Website

Contact

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Admin (requires `Authorization: Bearer <RT_ADMIN_KEY>`)