Chain Stock Tokens

Overview

Query the list of stock tokens issued on a specific blockchain network. Supports filtering by exchange, ticker symbol, and token contract address.

Endpoint: GET /api/v1/chains/{chain_id}/tokens

Authentication: No authentication required (public endpoint)

Path Parameters

Parameter	Type	Required	Description
chain_id	int	Yes	Blockchain network ID (e.g. 56 = BSC Mainnet)

Query Parameters

Parameter	Type	Required	Description
exchange_id	int	No	Exchange ID (0=US stocks, 1=HK stocks)
ticker	string	No	Stock ticker symbol (exact match, e.g. AAPLs)
token_address	string	No	Token contract address (exact match)
stock_code	string	No	Stock code (exact match, e.g. AAPL)
token_type	string	No	Token type filter (stock or share)
page	int	No	Page number for pagination (1-based, requires page_size)
page_size	int	No	Page size for pagination (default: 100, max: 500, requires page)

Response Parameters

Field	Type	Description
chain_id	int	Chain ID
tokens	array	List of tokens
tokens[].ticker	string	Stock ticker symbol
tokens[].name	string	Stock name
tokens[].exchange	string	Exchange name
tokens[].token_address	string	Token contract address
tokens[].token_type	string	Token type (stock or share)
tokens[].underlying_token	string	Optional Underlying StockToken address (for ShareToken)
tokens[].decimals	int	Token decimals (0 for StockToken, 18 for ShareToken)
tokens[].lot_size	decimal	Board lots (default 1 for US stocks)
tokens[].spread_table_code	string	Price Ticker (Default 1 for US stocks)
total	int	Total number of records matching the filter
page	int	Optional Current page number (only when pagination is used)
page_size	int	Optional Page size (only when pagination is used)
total_pages	int	Optional Total pages (only when pagination is used)

Request Examples

All Tokens

curl -X GET "/api/v1/chains/56/tokens"

Filter by Exchange

curl -X GET "/api/v1/chains/56/tokens?exchange_id=0"

Filter by Ticker

curl -X GET "/api/v1/chains/56/tokens?ticker=AAPLs"

Combined Filter

curl -X GET "/api/v1/chains/56/tokens?exchange_id=0&ticker=AAPLs"

Filter by Token Address

curl -X GET "/api/v1/chains/56/tokens?token_address=0x1234...abcd"

Filter by Token Type

curl -X GET "/api/v1/chains/56/tokens?token_type=stock"

Pagination

curl -X GET "/api/v1/chains/56/tokens?page=1&page_size=100"

Pagination with Filter

curl -X GET "/api/v1/chains/56/tokens?exchange_id=0&page=1&page_size=100"

Response Example

Non-Paginated Response

{
  "chain_id": 56,
  "tokens": [
    {
      "ticker": "AAPL",
      "stock_code": "AAPL",
      "name": "Apple Inc.",
      "exchange": "USEX",
      "token_address": "0x1234567890abcdef1234567890abcdef12345678",
      "token_type": "stock",
      "underlying_token": null,
      "decimals": 0,
      "lot_size": "1",
      "spread_table_code": "1"
    },
    {
      "ticker": "AAPLs",
      "stock_code": "AAPL",
      "name": "Apple Inc. Share Token",
      "exchange": "USEX",
      "token_address": "0xabcdef1234567890abcdef1234567890abcdef12",
      "token_type": "share",
      "underlying_token": "0x1234567890abcdef1234567890abcdef12345678",
      "decimals": 18,
      "lot_size": "1",
      "spread_table_code": "1"
    }
  ],
  "total": 2
}

Paginated Response

{
  "chain_id": 56,
  "tokens": [
    {
      "ticker": "AAPL",
      "stock_code": "AAPL",
      "name": "Apple Inc.",
      "exchange": "USEX",
      "token_address": "0x1234567890abcdef1234567890abcdef12345678",
      "token_type": "stock",
      "underlying_token": null,
      "decimals": 0,
      "lot_size": "1",
      "spread_table_code": "1"
    }
  ],
  "total": 5000,
  "page": 1,
  "page_size": 100,
  "total_pages": 50
}

Exchange ID Reference

See Exchange enum in Public API Overview.

Notes

• Only returns tokens where is_active = true and token_address is set
• ticker is an exact, case-sensitive match
• Multiple filter parameters are combined with AND logic
• Results are sorted alphabetically by ticker
• Pagination: When both page and page_size are provided, returns paginated results with metadata (page, page_size, total_pages). The total field is always returned to indicate the total number of records matching the filter. When pagination parameters are omitted, returns all records (backward compatible).
• Performance: For large datasets (1000+ records), use pagination to avoid timeouts. Maximum page size is 500.
• Token Types:
  • stock: StockToken (0 decimals) - represents direct stock ownership
  • share: ShareToken (18 decimals) - represents fractional ownership of underlying StockToken