Merkl Developer Portal logo
get

/v4/tokens/{id}

Get a token by its canonical id, or by the {chainId}-{address} shorthand. The shorthand reads an unknown token from chain and stores it; a canonical id the database does not hold is a 404.

Path parameters

idstring
required

Token ID (path-only). Two accepted forms: (1) canonical numeric hash Bun.hash(${chainId}${checksumAddress(address)}).toString() (e.g. 3460729690457214808), or (2) the {chainId}-{address} shorthand (e.g. 1-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) which the server resolves to the canonical id. The shorthand is path-only — the ?id= query filter only accepts the canonical numeric form (comma-separated list supported). NOT a campaign or opportunity ID. See ID types.

Query parameters

returnUnderlyingboolean

Resolve the token's underlying and return it under underlying, null when the token is not a wrapper.

Responses

200
Response for status 200
Schema
object
idstring
required
Unique identifier for the token
namestring | null
required
Full name of the token
chainIdinteger
required
Chain Id
addressstring
required
decimalsnumber
required
Number of decimals for the token
symbolstring
required
Symbol of the token
iconstring
required
URL to the token icon image
verifiedboolean
required
Whether the token is verified
isNativeboolean
required
Whether this is a native blockchain token
isTestboolean
required
Whether this is a test token
typeenum
required
Type of the token (TOKEN, PRETGE, POINT)TOKENPRETGEPOINT
pricenumber | nullCurrent price of the token in USD
updatedAtnumber | nullUnix timestamp of last price update
priceSourcestring | nullSource of the price information
displaySymbolstringCustom display symbol override
underlyingTokenIdstringIf this token is a wrapper, the ID of the underlying token
priceAlertDismissedAtnumber
priceAlertCountnumber
underlyingobject | null
idstringUnique identifier for the token
namestring | nullFull name of the token
chainIdintegerChain Id
addressstring
decimalsnumberNumber of decimals for the token
symbolstringSymbol of the token
iconstringURL to the token icon image
verifiedbooleanWhether the token is verified
isNativebooleanWhether this is a native blockchain token
isTestbooleanWhether this is a test token
typeenumType of the token (TOKEN, PRETGE, POINT)TOKENPRETGEPOINT
pricenumber | nullCurrent price of the token in USD
updatedAtnumber | nullUnix timestamp of last price update
priceSourcestring | nullSource of the price information
displaySymbolstringCustom display symbol override
underlyingTokenIdstringIf this token is a wrapper, the ID of the underlying token
priceAlertDismissedAtnumber
priceAlertCountnumber
Example
{
  "id": "string",
  "name": "string",
  "chainId": 0,
  "address": "string",
  "decimals": 0,
  "symbol": "string",
  "icon": "string",
  "verified": false,
  "isNative": false,
  "isTest": false,
  "type": "TOKEN",
  "price": 0,
  "updatedAt": 0,
  "priceSource": "string",
  "displaySymbol": "string",
  "underlyingTokenId": "string",
  "priceAlertDismissedAt": 0,
  "priceAlertCount": 0,
  "underlying": {
    "id": "string",
    "name": "string",
    "chainId": 0,
    "address": "string",
    "decimals": 0,
    "symbol": "string",
    "icon": "string",
    "verified": false,
    "isNative": false,
    "isTest": false,
    "type": "TOKEN",
    "price": 0,
    "updatedAt": 0,
    "priceSource": "string",
    "displaySymbol": "string",
    "underlyingTokenId": "string",
    "priceAlertDismissedAt": 0,
    "priceAlertCount": 0
  }
}