Chains & Tokens

Configuration structure

Chains and tokens are defined in the server config file under chains. Each chain key is a human-readable identifier (e.g. eth-sepolia, polygon-mainnet) that is also used as the chain parameter in API calls.

{
  "chains": {
    "eth-sepolia": {
      "chainId": 11155111,
      "rpcUrl": "https://rpc.sepolia.org",
      "blockTimeMs": 12000,
      "tokens": {
        "USDC": {
          "symbol": "USDC",
          "address": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
          "decimals": 6
        },
        "ETH": {
          "symbol": "ETH",
          "decimals": 18,
          "coingeckoId": "ethereum"
        }
      }
    }
  },
  "payment": {
    "defaultToken": "USDC"
  }
}

Token fields

Field	Required	Description
`symbol`	Yes	Display symbol (e.g. `ETH`)
`decimals`	Yes	Number of decimal places
`address`	ERC-20 only	Contract address. Omit for native coins.
`coingeckoId`	Non-stablecoins	CoinGecko coin ID used for price lookup. Omit for stablecoins — they are always valued at $1.00.

Stablecoins vs. volatile tokens

Tokens without a coingeckoId are treated as stablecoins and assigned a fixed exchange rate of 1 USD. Tokens with a coingeckoId have their USD price fetched from CoinGecko and cached for payment.rateRefreshMinutes (default: 5).

Adding a new chain

Add the chain entry to the config file with the correct chainId, rpcUrl, and blockTimeMs.
Add at least one token under tokens.
Restart the API and Worker.

The API will automatically include the new chain in GET /v1/charges/chains and create a PaymentWallet on the new chain for every subsequent charge.

The Worker spawns a separate blockchain scanner per token per chain. Adding many chains or tokens increases RPC call volume proportionally.

Native coin detection

Native coins (no address field) are detected using balance polling rather than event logs. The Worker checks the wallet balance before and after each block to calculate received native coin amounts.

ERC-20 detection

ERC-20 tokens are detected by scanning Transfer event logs filtered to the wallet address. The raw amount is converted to a human amount using decimals, then to USD using the stored exchange rate.