API Reference

Complete documentation of all TransX402 REST API endpoints — authentication, merchant management, payment facilitation, sandbox, and more.

Base URL

The environment is determined automatically from the API key prefix:

Key Prefix	Environment	URL
`ipk_sandbox_`	Sandbox (Anvil fork)	`https://sandbox.transx402.com`
`ipk_live_`	Production (Base mainnet)	`https://api.transx402.com`

Authentication

Endpoint Group	Auth	Method
`/facilitate`	API Key	`X-API-Key` header
`/payments/*`	API Key	`X-API-Key` header
`/tokens/*`	None (public)	—
`/health`	None (public)	—
`/verify/:txHash`	None (public)	—
`/auth/*`	Wallet signature	SIWE
`/merchant/*`	Session cookie	Set after `/auth/login`
`/sandbox/*`	Sandbox API Key	`X-API-Key` header

Authentication and Registration

`POST /auth/register`

Request:

{
  "email": "merchant@example.com",
  "walletAddress": "0xMerchant...",
  "name": "My Blog",
  "website": "https://myblog.com",
  "signature": "0x...",
  "message": "Sign in to TransX402\nNonce: abc123\nTimestamp: 2026-04-01T10:00:00Z"
}

Response:

{
  "merchantId": "m_abc123",
  "email": "merchant@example.com",
  "walletAddress": "0xMerchant...",
  "sandboxApiKey": "ipk_sandbox_...",
  "createdAt": "2026-04-01T10:00:00Z"
}

On registration, a sandbox API key is automatically created. Production keys are created separately from the dashboard.

`POST /auth/login`

`POST /auth/logout`

Clear session.

Payment Facilitation

`POST /facilitate`

Process a signed payment authorization. This is the core endpoint called by x402 clients.

Auth: API Key (X-API-Key header)

Processing pipeline:

Parse and validate request schema
Authenticate API key, resolve merchant and environment
Route to correct chain (sandbox Anvil or production Base)
Verify token is in the registry
Verify Permit2 signature
Check deadline has not passed
Check nonce has not been used
Check payer's IDRX balance
Check payer's Permit2 allowance
Simulate transaction
Submit transaction on-chain
Wait for confirmation
Record payment in database
Fire webhook (async)
Return transaction hash

Payment Status

`GET /payments/:txHash`

Get the status of a payment by transaction hash.

Auth: API Key

Response:

{
  "txHash": "0x...",
  "status": "confirmed",
  "from": "0xPayer",
  "to": "0xMerchant",
  "token": "IDRX",
  "amount": "150000000000000000000000",
  "amountFormatted": "150000",
  "currency": "IDR",
  "network": "base",
  "blockNumber": 12345678,
  "timestamp": "2026-04-01T10:30:00Z",
  "resource": "https://example.com/article/123"
}

Status values: pending, confirmed, failed

`GET /payments`

List payments for the authenticated merchant.

Auth: API Key

Query parameters:

Param	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status
`from`	string	Filter by payer address
`since`	ISO date	Filter payments after this date
`until`	ISO date	Filter payments before this date

Response:

{
  "payments": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

Merchant Profile

`GET /merchant/me`

Get the current merchant profile.

Auth: Session cookie

`PATCH /merchant/me`

Update merchant profile.

Auth: Session cookie

Request:

{
  "name": "My Updated Blog",
  "webhookUrl": "https://myblog.com/webhook/transx402",
  "webhookSecret": "auto",
  "defaultToken": "IDRX",
  "defaultNetwork": "base"
}

`GET /merchant/stats`

Get payment statistics.

Auth: Session cookie

Response:

{
  "totalPayments": 1423,
  "totalVolume": {
    "IDRX": "21345000000000000000000000000",
    "formatted": {
      "IDRX": "21,345,000,000 IDR"
    }
  },
  "last30Days": {
    "payments": 342,
    "volume": { "IDRX": "..." },
    "uniquePayers": 89
  }
}

API Key Management

`POST /merchant/api-keys`

Create a new API key.

Auth: Session cookie

Request:

{
  "environment": "sandbox",
  "label": "WordPress Site"
}

Response:

{
  "id": "key_abc123",
  "key": "ipk_sandbox_abc123def456...",
  "prefix": "ipk_sandbox_abc1",
  "environment": "sandbox",
  "label": "WordPress Site",
  "createdAt": "2026-04-01T10:00:00Z"
}

Important: The full key field is only returned once at creation. Store it securely.

`GET /merchant/api-keys`

List all API keys (shows prefix, label, environment, last used — never the full key).

Auth: Session cookie

`DELETE /merchant/api-keys/:id`

Revoke an API key.

Auth: Session cookie

Sandbox Utilities

These endpoints are only accessible with sandbox API keys.

`POST /sandbox/fund`

Fund a test wallet with IDRX on the sandbox chain.

Auth: Sandbox API Key

Request:

{
  "address": "0xTestWallet...",
  "amount": "1000000"
}

Response:

{
  "txHash": "0x...",
  "address": "0xTestWallet...",
  "amount": "1000000",
  "token": "IDRX",
  "balance": "1000000"
}

`POST /sandbox/reset`

Reset sandbox chain state (re-fork from latest Base mainnet block).

Auth: Sandbox API Key

`GET /sandbox/wallets`

List pre-funded test wallets with IDRX and ETH balances.

Auth: Sandbox API Key

Response:

{
  "wallets": [
    {
      "address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
      "ethBalance": "10000.0",
      "idrxBalance": "10000000000",
      "privateKey": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
    }
  ]
}

These are Anvil's deterministic accounts — safe to expose in sandbox only.

Token Information

`GET /tokens`

List all supported tokens.

Auth: None

`GET /tokens/:symbol/price`

Get current price information for a token.

Auth: None

Response:

{
  "symbol": "IDRX",
  "currency": "IDR",
  "rate": 1.0,
  "lastUpdated": "2026-04-01T10:30:00Z"
}

Payment Verification

`GET /verify/:txHash`

Public endpoint to verify a payment was processed by TransX402. Useful for server-side verification without an API key.

Auth: None

Response:

{
  "verified": true,
  "txHash": "0x...",
  "token": "IDRX",
  "amount": "150000000000000000000000",
  "from": "0xPayer",
  "to": "0xMerchant",
  "network": "base"
}

Health Check

`GET /health`

Auth: None

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "networks": {
    "base": { "status": "ok", "blockNumber": 12345678 }
  }
}

Error Format

All errors follow a consistent format:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Payer IDRX balance is below required amount",
    "details": {
      "required": "150000000000000000000000",
      "available": "50000000000000000000000"
    }
  }
}

Error Codes

Code	HTTP Status	Description
`invalid_signature`	400	Permit2 signature verification failed
`insufficient_balance`	400	Payer doesn't have enough tokens
`no_permit2_approval`	400	Payer hasn't approved Permit2 contract
`expired_deadline`	400	Payment authorization has expired
`unsupported_token`	400	Token not in registry
`unsupported_network`	400	Network not supported for this token
`simulation_failed`	400	Transaction simulation reverted
`tx_failed`	500	On-chain transaction reverted
`rate_limited`	429	Too many requests
`unauthorized`	401	Invalid or missing API key

Rate Limits

Endpoint	Limit
`POST /facilitate`	60/min per IP
`GET /payments/*`	120/min per API key
`POST /merchants/*`	10/min per IP
All others	120/min per IP

API Reference

On this page