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 (secret or publishable):

IDRX uses 2 decimals. On-chain and payment-record amount strings are base units (Rp 5,000 → "500000"). Human prices in SDKs are whole IDR ("5000").

Authentication

Secret vs publishable: POST /facilitate from a browser (Origin present) must use ipk_pub_* and an Allowed Origin from the dashboard. Secret keys (ipk_sandbox_, ipk_live_) are for merchant backends (@transx402/server, WordPress PHP) with no browser Origin.

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.

Facilitator config

GET /config

Public chain, token, and x402 capability snapshot. No API key. Clients and @transx402/server load RPC, chainId, IDRX address, decimals, and Permit2 from here — do not hardcode them in app code.

Browsers in server settlement should call this via a same-origin merchant proxy (GET /api/transx402/config), not the facilitator origin (CORS).

Response (shape):

{
  "sandbox": {
    "rpcUrl": "https://testnet-rpc.onchainfolio.com/rpc",
    "chainId": 1337,
    "network": "sandbox",
    "tokens": { "IDRX": "0x..." },
    "tokenDecimals": { "IDRX": 2 },
    "permit2Address": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
    "x402": {
      "caip2Network": "eip155:1337",
      "sponsorshipMode": "erc20ApprovalRelay",
      "eip2612": false,
      "x402Permit2ProxyAddress": "0x..."
    },
    "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 }
  },
  "production": {
    "rpcUrl": "https://mainnet.base.org",
    "chainId": 8453,
    "network": "base",
    "tokens": { "IDRX": "0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22" },
    "tokenDecimals": { "IDRX": 2 },
    "permit2Address": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
    "x402": {
      "caip2Network": "eip155:8453",
      "sponsorshipMode": "erc20ApprovalRelay",
      "eip2612": false,
      "x402Permit2ProxyAddress": "0x..."
    },
    "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 }
  }
}

ipk_sandbox_ / ipk_pub_sandbox_ use the sandbox section; ipk_live_ / ipk_pub_live_ use production. Exact rpcUrl / chainId / addresses come from the live facilitator.

Payment Facilitation

POST /facilitate

Process a signed payment authorization. This is the core endpoint called by x402 clients (@transx402/server in canonical mode, or the browser client in settlement: "direct").

Auth: API Key (X-API-Key header). Browser callers must use a publishable key plus Allowed Origins.

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": "500000",
  "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": "2134500000000",
    "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". For IDRX, amount is whole IDRX (same as whole IDR), default cap 100000 per request. Use "ETH" with a decimal amount such as "0.01".

Auth: Secret sandbox API Key (ipk_sandbox_... only)

Request (IDRX):

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

Request (ETH):

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

Response:

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

POST /sandbox/reset

Re-fork the Anvil sandbox from the latest Base mainnet block. Returns 409 sandbox_operation_unsupported on hosted CAMP (treasury) sandbox.

Auth: Secret sandbox API Key

GET /sandbox/wallets

List Anvil deterministic test wallets. Returns 409 on hosted CAMP (treasury) sandbox.

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": "500000",
      "available": "100000"
    }
  }
}

Error Codes

Rate Limits