Tokens API
Resolve token identities in the selected API environment, not by symbol alone. The API supplies metadata and cached bridge liquidity, not user-wallet balances. See Supported Tokens for the public-testnet catalog.
Endpoints
| Endpoint | Result |
|---|---|
GET /api/v1/tokens |
Token data array with chain-address mappings |
GET /api/v1/tokens/{id} |
Token data object by numeric ID |
GET /api/v1/tokens/address/{address} |
Token by EVM address across registered chains |
GET /api/v1/tokens/ethereum/{address} |
Legacy alias for EVM address lookup |
GET /api/v1/tokens/casper/{hash} |
Token by Casper package hash |
GET /api/v1/tokens/chain/{chainName} |
Token data array and chain slug |
GET /api/v1/tokens/chains |
Enabled chain registry rows by default |
Token endpoints accept includeLiquidity=false to omit liquidity work/fields; the default includes liquidity. /tokens/chains?enabled=false returns all registry rows. Unlike /chains, these raw registry rows do not resolve locker addresses from environment configuration: use /chains for lockers. A registry entry alone is not proof of an active token corridor.
EVM address lookup requires 0x plus 40 hex characters. Casper hash lookup accepts 64 hex characters with an optional 0x, not the hash- prefix. Malformed address/hash identifiers return 400, unknown tokens 404. The numeric ID route uses decimal parseInt: 2junk is interpreted as 2, while an ID with no parseable numeric prefix returns 400. Clients should send and validate digits-only IDs. Use an exact chain slug such as sepolia, base-sepolia, polygon-amoy or robinhood-testnet.
Token fields
| Field | Type | Meaning |
|---|---|---|
id |
number | Environment-specific database ID |
symbol, name |
string | Display metadata, not unique identity |
casperHash |
string | Casper token package identifier, 64 hex characters |
decimalsEth, decimalsCasper |
number | Token decimal precision |
originChain |
string | evm or casper |
wrappedAddress |
string or null | Legacy wrapped-address field; use per-chain addresses |
isActive |
boolean | Catalog activity flag |
addresses |
object | Chain slug to EVM token address; casing may vary |
evmLiquidity |
object or null | Chain slug to decimal unlockable amount for EVM-origin tokens |
casperLiquidity |
string or null | Decimal unlockable amount for Casper-origin tokens |
createdAt, updatedAt |
string | ISO timestamps |
Liquidity fields can be omitted when not requested. For EVM-origin tokens casperLiquidity is null; for Casper-origin tokens evmLiquidity is null. These indicate which side holds backing, not unlimited bridge capacity. Available liquidity can change before execution; contracts enforce the actual limits.
Liquidity by route
| Direction | Token origin | Backing requirement |
|---|---|---|
| EVM to Casper | EVM | Source ERC-20 is locked; destination wrapper minted |
| Casper to EVM | EVM | Selected destination locker must have enough ERC-20 |
| Casper to EVM | Casper | Source CEP-18 is locked; destination wrapper minted |
| EVM to Casper | Casper | Casper factory must have enough locked native token |
Minting routes still require valid tokens, balances, approvals, fees and contract permission checks. They do not always succeed.
curl -fsS 'https://api.testnet.astralbeam.io/api/v1/tokens' |
jq '.data[] | {id, symbol, casperHash, addresses, evmLiquidity, casperLiquidity}'
curl -fsS 'https://api.testnet.astralbeam.io/api/v1/tokens/chain/robinhood-testnet'
curl -fsS 'https://api.testnet.astralbeam.io/api/v1/tokens/address/0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238'
For a Casper lookup, take casperHash from the selected environment's registry and append it to /api/v1/tokens/casper/. Do not copy a wrapper hash from another environment. Use decimal/bigint libraries rather than floating-point arithmetic for exact token amounts.