Get Stock Token Address

Endpoint Information

Endpoint: GET /api/v1/instruments/token-address

Description: Get the token contract address for a stock based on ticker and exchange ID

Authentication: API Key + Signature. See Authorization

Request Parameters

Parameter	Type	Required	Description
ticker	string	Yes	Stock ticker symbol (e.g., AAPLs)
exchange	number	Yes	Exchange ID, see Exchange enum
chain_id	number	No	Blockchain network ID, uses system default chain ID if not provided

Response Parameters

Field	Type	Description
ticker	string	Stock ticker symbol
stock_code	string	Optional Stock code
name	string	Stock name
exchange_id	number	Exchange ID
chain_id	number	Blockchain network ID
token_address	string	Token contract address
token_type	string	Optional Token type (stock or share)
underlying_token	string	Optional Underlying StockToken address (for ShareToken)
decimals	int	Token decimals (0 for StockToken, 18 for ShareToken)
is_active	boolean	Whether the token is active
lot_size	decimal	Board lots (default 1 for US stocks)
spread_table_code	string	Price Ticker (Default 1 for US stocks)

Request Example

Query Using Default Chain ID

curl -X GET "{API_BASE_URL}/api/v1/instruments/token-address?ticker=AAPLs&exchange=0" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Maker-Addr: YOUR_MAKER_ADDRESS" \
     -H "X-API-Timestamp: 1715100000000" \
     -H "X-API-Signature: GENERATED_SIGNATURE" \
     -H "Content-Type: application/json"

Query Specifying Chain ID (BSC)

curl -X GET "{API_BASE_URL}/api/v1/instruments/token-address?ticker=AAPLs&exchange=0&chain_id=56" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Maker-Addr: YOUR_MAKER_ADDRESS" \
     -H "X-API-Timestamp: 1715100000000" \
     -H "X-API-Signature: GENERATED_SIGNATURE" \
     -H "Content-Type: application/json"

Response Examples

Success Response (StockToken)

{
  "code": 0,
  "data": {
    "ticker": "AAPL",
    "stock_code": "AAPL",
    "name": "Apple Inc.",
    "exchange_id": 0,
    "chain_id": 56,
    "token_address": "0x1234567890abcdef1234567890abcdef12345678",
    "token_type": "stock",
    "underlying_token": null,
    "decimals": 0,
    "is_active": true,
    "lot_size": "1",
    "spread_table_code": "1"
  }
}

Success Response (ShareToken)

{
  "code": 0,
  "data": {
    "ticker": "AAPLs",
    "stock_code": "AAPL",
    "name": "Apple Inc. Share Token",
    "exchange_id": 0,
    "chain_id": 56,
    "token_address": "0xabcdef1234567890abcdef1234567890abcdef12",
    "token_type": "share",
    "underlying_token": "0x1234567890abcdef1234567890abcdef12345678",
    "decimals": 18,
    "is_active": true,
    "lot_size": "1",
    "spread_table_code": "1"
  }
}

Error Responses

Missing ticker parameter:

{
  "error": "Not found: not found or not available: ticker=, exchange=0, chain_id=56"
}

Missing exchange parameter:

{
  "error": "Failed to deserialize query string: cannot parse integer from empty string"
}

Ticker does not exit or the parameters do not match.:

{
  "error": "Not found: not found or not available: ticker=INVALID, exchange=0, chain_id=56"
}

Use Cases

• Query token address before creating an order
• Verify if a stock is available on the platform
• Get basic information about a stock
• Query token address on a specific chain in cross-chain scenarios

Implementation Notes

• Supports querying token addresses on specific blockchain networks via the chain_id parameter
• If chain_id is not provided, the system uses the default chain ID from the configuration file
• Query results are cached for 4 hours (14400 seconds) to improve performance
• Cache key format: token_addr:{ticker}:{exchange_id}:{chain_id}