API Reference

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

Base URL

All hosted requests go to https://api.transx402.com. Local development uses http://localhost:3402.

The chain is determined from your API key prefix:

Authentication

Authentication and Registration

POST /auth/register

Register a new merchant account. Requires a SIWE signature to prove wallet ownership.

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

Login with wallet signature. Sets a session cookie for dashboard access.

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:

1. Parse and validate request schema
2. Authenticate API key, resolve merchant and environment
3. Route to correct chain (sandbox CAMP Testnet or production Base)
4. Verify token is in the registry
5. Verify Permit2 signature
6. Check deadline has not passed
7. Check nonce has not been used
8. Check payer's IDRX balance
9. Check payer's Permit2 allowance
10. Simulate transaction
11. Submit transaction on-chain
12. Wait for confirmation
13. Record payment in database
14. Fire webhook (async)
15. Return transaction hash

Payment Status

GET /payments/:txHash

Post-settlement lookup: check whether TransX402 recorded a payment for this transaction hash. Scoped to the API key's merchant. Use for deferred unlock (e.g. WordPress pay-per-article) or reconciliation after you already have a txHash.

This is not the x402 protocol pre-settlement verify step. Settlement uses combined POST /facilitate (internal verify + settle).

Auth: API Key

Response:

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

Status values: pending, confirmed, failed

verified is true when status === "confirmed". resource is the content URL from the original payment (use it to match pay-per-article unlocks). resource and description may be null if not provided at settlement.

Deprecated alias: GET /verify/:txHash returns the same response with a Deprecation: true header. Prefer /payments/:txHash.

GET /payments

List payments for the authenticated merchant.

Auth: API Key

Query parameters:

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 or ETH on the sandbox chain. Optional token defaults to "IDRX". Use "ETH" with a decimal amount such as "0.01".

Auth: Sandbox API Key

Request (IDRX):

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

Request (ETH):

{
  "address": "0xTestWallet...",
  "amount": "0.01",
  "token": "ETH"
}

Response:

{
  "txHash": "0x...",
  "address": "0xTestWallet...",
  "amount": "0.01",
  "token": "ETH",
  "balance": "10000000000000000"
}

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"
}

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

Rate Limits