API Reference

AstralBeam's read-only REST API exposes bridge records, token mappings, chain configuration and statistics. It does not submit transfers or return wallet balances.

Base URL

Environment	API origin
Public testnet	`https://api.testnet.astralbeam.io`
Local development (default API_PORT)	`http://localhost:3000`

Paths below include /api/v1; append them to the origin once. Public-testnet examples accompany testnet.astralbeam.io. Other deployments have independent databases, contract addresses and histories. Do not reuse their numeric IDs or token mappings here.

Responses and errors

Most endpoints return success and data. Lists may add pagination, chain or count. Health is an explicit exception: it returns top-level status and checks, without a data envelope. See Statistics.

{"success": true, "data": [], "pagination": {"page": 1, "limit": 50, "total": 0, "totalPages": 0}}

Errors usually return {"success": false, "error": "..."}; query validation may add details. Check HTTP status as well as the body. Invalid input returns 400, missing resources 404, ambiguous source-hash lookups 409, unexpected server failures 500, and degraded/unhealthy dependency checks 503. Do not treat an initial transaction lookup 404 as proof of a failed on-chain transfer.

The public API does not require authentication. Respect any upstream rate limits and handle 429 responses with backoff. API liquidity is a cached observation, not a reservation or guarantee.

API Categories

Tokens

Token registry, multi-chain address management, and real-time liquidity data.

Endpoint	Description
`GET /api/v1/tokens`	List all supported tokens
`GET /api/v1/tokens/{id}`	Get token by ID
`GET /api/v1/tokens/address/{address}`	Get token by EVM address
`GET /api/v1/tokens/ethereum/{address}`	Get token by Ethereum address (legacy)
`GET /api/v1/tokens/casper/{hash}`	Get token by Casper hash
`GET /api/v1/tokens/chain/{chainName}`	Get tokens for a specific chain
`GET /api/v1/tokens/chains`	List supported chains (token-scoped view)

Transactions

Bridge transaction history and status tracking.

Endpoint	Description
`GET /api/v1/transactions`	List transactions (paginated)
`GET /api/v1/transactions/{id}`	Get transaction by ID
`GET /api/v1/transactions/hash/{txHash}`	Get transaction by source tx hash
`GET /api/v1/transactions/address/{address}`	Get all transactions for an address
`GET /api/v1/transactions/status/pending`	Get pending transactions

Statistics

Bridge statistics and health monitoring.

Endpoint	Description
`GET /api/v1/stats`	Get overall bridge statistics
`GET /api/v1/stats/chains`	Get per-chain statistics
`GET /api/v1/stats/token-flow`	Authoritative transfer counts and exact volumes per deployment and token
`GET /api/v1/stats/health`	Health check endpoint
`GET /api/v1/stats/relayers`	Get relayer statistics

Chains

Supported EVM chain information.

Endpoint	Description
`GET /api/v1/chains`	List all supported chains
`GET /api/v1/chains/{chainId}`	Get chain by ID
`GET /api/v1/chains/explorers/all`	Get explorer URLs for all chains

Utility endpoints

Endpoint	Description
`GET /livez`	Process liveness, not dependency health
`GET /api/v1/stats/casper-node`	Cached Casper node reachability
`GET /api/v1/stats/bridge-fee`	Configured Casper bridge fee
`GET /api/v1/rates/{fiatId}/latest`	Latest CSPR fiat rate; `/rates/{fiatId}/latest` is an alias

See Statistics for utility response shapes.

Pagination

Transaction list/address endpoints accept page (default 1, maximum 100000) and limit (default 50, maximum 100). Responses include page, limit, total and totalPages. A page length is not the total history count. Fetch every page before computing whole-history aggregates; data can change between requests.

Quick examples

curl -fsS 'https://api.testnet.astralbeam.io/api/v1/tokens'
curl -fsS 'https://api.testnet.astralbeam.io/api/v1/transactions?limit=5&status=completed'
curl -sS 'https://api.testnet.astralbeam.io/api/v1/stats/health'

For a bounded, cancellable source-hash tracker, see the Developer Guide. Polling is supported; no webhook subscription endpoint is exposed.

API Overview