Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nhestrompia/shielded-x402/llms.txt

Use this file to discover all available pages before exploring further.

The Payment Relayer is a chain-bound service that executes authorized payments on behalf of agents. Each relayer instance is tied to a specific blockchain and validates authorizations from the credit sequencer before executing transactions.

​
Overview

The relayer runtime supports:
  1. Authorization Validation - Verify signed authorizations from the sequencer
  2. Chain Enforcement - Each relayer instance bound to a specific chainRef (CAIP-2)
  3. Payment Execution - Execute payments on the target chain
  4. Execution Reporting - Send signed execution reports back to the sequencer
Legacy /v1/relay/credit/* routes have been removed. Use /v1/relay/pay with sequencer authorizations.

​
Installation

From the monorepo root: 
pnpm relayer:dev

​
Required Configuration

​
RELAYER_CHAIN_REF
string
required
CAIP-2 chain reference that this relayer instance will operate on.Examples:
  • eip155:84532 (Base Sepolia)
  • eip155:8453 (Base Mainnet)
  • solana:devnet (Solana Devnet)
​
RELAYER_SEQUENCER_URL
string
required
Base URL of the credit sequencer service.Example: https://sequencer.example.com
​
RELAYER_SEQUENCER_KEYS_JSON
string
required
JSON map of sequencer public keys for verifying authorization signatures.Example:
{
  "seq-key-1": "0x<ed25519-pubkey-32-bytes>"
}
​
RELAYER_REPORTING_PRIVATE_KEY
string
required
Ed25519 private key for signing execution reports. Accepts either 32-byte seed or 64-byte key as hex.Example: 0x1234567890abcdef...
​
RELAYER_KEY_ID
string
required
Logical identifier for this relayer’s key, sent to sequencer in execution reports.Example: rel-base-prod-1

​
Optional Configuration

​
RELAYER_PORT
number
default:"3100"
HTTP port for the relayer service.
​
RELAYER_PAYOUT_MODE
string
default:"forward"
Payout execution mode. Options:
  • forward - Forward request to merchant endpoint
  • noop - No-op mode for testing (no actual payment)
  • solana - Direct Solana on-chain execution
  • evm - Direct EVM on-chain execution
​
RELAYER_PAYOUT_HEADERS_JSON
string
JSON object of static HTTP headers to include in outbound merchant requests (forward mode).Example: {"X-API-Key": "secret"}
​
RELAYER_ALLOWED_HOSTS
string
Comma-separated allowlist of hosts for forward mode security.Example: merchant1.com,merchant2.com
​
RELAYER_MERCHANT_TIMEOUT_MS
number
default:"5000"
Timeout for merchant HTTP requests in milliseconds.
​
RELAYER_MAX_RESPONSE_BYTES
number
default:"1048576"
Maximum response body size from merchant (1 MB default).
​
RELAYER_RATE_LIMIT_PER_MINUTE
number
default:"180"
Rate limit for /v1/relay/pay endpoint (requests per minute).
​
RELAYER_CALLER_AUTH_TOKEN
string
Optional authentication token. When set, /v1/relay/pay requires x-relayer-auth-token header.
​
RELAYER_EVM_PRIVATE_KEY
string
Optional fallback private key for EVM payout mode. Can be overridden per-request.

​
Payout Modes

​
Forward Mode

Forwards the payment request to a merchant-specified endpoint: 
RELAYER_PAYOUT_MODE=forward
RELAYER_ALLOWED_HOSTS=merchant.example.com
RELAYER_PAYOUT_HEADERS_JSON='{"Authorization": "Bearer token"}'

​
No-op Mode (Testing)

For local smoke tests without actual chain execution: 
RELAYER_CHAIN_REF=eip155:8453
RELAYER_PAYOUT_MODE=noop

​
Solana Mode

Direct Solana on-chain payment execution. The merchantRequest.bodyBase64 must contain:
​
rpcUrl
string
required
Solana RPC endpoint URL.
​
wsUrl
string
required
Solana WebSocket endpoint URL.
​
gatewayProgramId
string
required
Solana gateway program ID.
​
verifierProgramId
string
required
Solana verifier program ID.
​
stateAccount
string
required
Gateway state PDA (Program Derived Address).
​
recipient
string
required
Recipient Solana public key.
​
amountLamports
number
required
Payment amount in lamports.
​
authIdHex
string
required
Authorization ID as hex string.
​
authExpiryUnix
number
required
Authorization expiry timestamp (Unix).
​
proofBase64
string
required
Zero-knowledge proof encoded as base64.
​
publicWitnessBase64
string
required
Public witness data encoded as base64.
​
payerKeypairPath
string
required
Path to payer keypair file.
Example configuration: 
RELAYER_CHAIN_REF=solana:devnet
RELAYER_PAYOUT_MODE=solana

​
EVM Mode

Direct EVM on-chain payment execution. The merchantRequest.bodyBase64 must contain:
​
rpcUrl
string
required
EVM RPC endpoint URL.
​
recipient
string
required
Recipient EVM address (0x…).
​
amountWei
string
required
Payment amount in wei.
​
chainId
number
Optional EVM chain ID.
​
privateKey
string
Optional private key (overrides RELAYER_EVM_PRIVATE_KEY).
Example configuration: 
RELAYER_CHAIN_REF=eip155:84532
RELAYER_PAYOUT_MODE=evm
RELAYER_EVM_PRIVATE_KEY=0x...

​
API Endpoints

​
Health & Monitoring

  • GET /health - Basic health check
  • GET /health/ready - Readiness probe
  • GET /metrics - Prometheus-compatible metrics

​
Payment Execution

  • POST /v1/relay/pay - Execute an authorized payment

​
Configuration Examples

​
Base Sepolia Relayer

.env
# Chain binding
RELAYER_CHAIN_REF=eip155:84532
RELAYER_PORT=3100

# Sequencer connection
RELAYER_SEQUENCER_URL=https://sequencer.shielded.example.com
RELAYER_SEQUENCER_KEYS_JSON='{"seq-key-1":"0xabcd..."}'

# Relayer identity
RELAYER_REPORTING_PRIVATE_KEY=0x1234...
RELAYER_KEY_ID=rel-base-sepolia-1

# Payout configuration
RELAYER_PAYOUT_MODE=evm
RELAYER_EVM_PRIVATE_KEY=0x5678...

# Rate limiting
RELAYER_RATE_LIMIT_PER_MINUTE=180

​
Solana Devnet Relayer

.env
# Chain binding
RELAYER_CHAIN_REF=solana:devnet
RELAYER_PORT=3101

# Sequencer connection
RELAYER_SEQUENCER_URL=https://sequencer.shielded.example.com
RELAYER_SEQUENCER_KEYS_JSON='{"seq-key-1":"0xabcd..."}'

# Relayer identity
RELAYER_REPORTING_PRIVATE_KEY=0x9abc...
RELAYER_KEY_ID=rel-solana-devnet-1

# Payout configuration
RELAYER_PAYOUT_MODE=solana

# Rate limiting
RELAYER_RATE_LIMIT_PER_MINUTE=180

​
Multi-Relayer Setup

Run multiple relayers for different chains: 
# Terminal 1: Base relayer
RELAYER_PORT=3100 RELAYER_CHAIN_REF=eip155:84532 pnpm relayer:dev

# Terminal 2: Solana relayer
RELAYER_PORT=3101 RELAYER_CHAIN_REF=solana:devnet pnpm relayer:dev

​
Security Considerations

  1. Private Key Management - Store RELAYER_REPORTING_PRIVATE_KEY and RELAYER_EVM_PRIVATE_KEY securely
  2. Host Allowlist - Use RELAYER_ALLOWED_HOSTS in forward mode to prevent SSRF attacks
  3. Authentication - Set RELAYER_CALLER_AUTH_TOKEN for production deployments
  4. Rate Limiting - Adjust RELAYER_RATE_LIMIT_PER_MINUTE based on capacity

​
Next Steps

Credit Sequencer

Configure the authorization sequencer

Deployment Guide

Deploy to production

Build docs developers (and LLMs) love

Get started for freeTalk to us