Skip to main content
POST
/
api
/
token-info
POST /api/token-info
curl --request POST \
  --url https://api.example.com/api/token-info \
  --header 'Content-Type: application/json' \
  --data '
{
  "addresses": [
    "<string>"
  ]
}
'
{
  "data": {
    "id": 123,
    "name": "<string>",
    "symbol": "<string>",
    "slug": "<string>",
    "logo": "<string>",
    "description": "<string>",
    "date_added": "<string>",
    "date_launched": {},
    "tags": [
      "<string>"
    ],
    "platform": {
      "name": "<string>",
      "token_address": "<string>"
    },
    "category": "<string>",
    "urls": {
      "website": [
        "<string>"
      ],
      "technical_doc": [
        "<string>"
      ],
      "twitter": [
        "<string>"
      ],
      "explorer": [
        "<string>"
      ],
      "source_code": [
        "<string>"
      ]
    }
  },
  "status": {
    "timestamp": "<string>",
    "error_code": 123,
    "error_message": {},
    "elapsed": 123,
    "credit_count": 123,
    "notice": {}
  },
  "error": "<string>"
}

​
Overview

Retrieves comprehensive token metadata from CoinMarketCap for one or more token contract addresses. This endpoint acts as a secure server-side proxy to the CoinMarketCap API, ensuring API keys remain protected.

​
Request

​
Body Parameters

​
addresses
string[]
required
Array of token contract addresses to fetch information for. Addresses should be provided as hexadecimal strings (e.g., 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48).

​
Response

The API returns the standard CoinMarketCap v2 cryptocurrency info response format.

​
Success Response

​
data
object
Object containing token information keyed by contract address (lowercase).
​
status
object
CoinMarketCap API status information

​
Error Responses

​
error
string
Error message describing what went wrong

​
Error Codes

  • 400 Bad Request: addresses parameter is missing or not an array
  • 500 Internal Server Error: API key not configured or CoinMarketCap API request failed

​
Examples

​
Request Example

curl -X POST https://bridge-wrapped.vercel.app/api/token-info \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "0xdac17f958d2ee523a2206206994597c13d831ec7"
    ]
  }'

​
Success Response Example

{
  "data": {
    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": {
      "id": 3408,
      "name": "USD Coin",
      "symbol": "USDC",
      "slug": "usd-coin",
      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/3408.png",
      "description": "USD Coin (USDC) is a stablecoin that is pegged to the U.S. dollar on a 1:1 basis...",
      "date_added": "2018-10-08T00:00:00.000Z",
      "date_launched": "2018-09-26T00:00:00.000Z",
      "tags": ["stablecoin", "asset-backed-stablecoin", "defi"],
      "platform": {
        "name": "Ethereum",
        "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      },
      "category": "stablecoin",
      "urls": {
        "website": ["https://www.circle.com/usdc"],
        "technical_doc": ["https://www.centre.io/pdfs/attestation/Grant-Thornton_circle_usdc_reserves_07312021.pdf"],
        "twitter": ["https://twitter.com/circle"],
        "explorer": [
          "https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        ],
        "source_code": ["https://github.com/centrehq"]
      }
    },
    "0xdac17f958d2ee523a2206206994597c13d831ec7": {
      "id": 825,
      "name": "Tether",
      "symbol": "USDT",
      "slug": "tether",
      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/825.png",
      "description": "Tether (USDT) is a stablecoin cryptocurrency that is pegged 1:1 to the US dollar...",
      "date_added": "2015-02-25T00:00:00.000Z",
      "date_launched": null,
      "tags": ["stablecoin", "asset-backed-stablecoin", "payments"],
      "platform": {
        "name": "Ethereum",
        "token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
      },
      "category": "stablecoin",
      "urls": {
        "website": ["https://tether.to/"],
        "technical_doc": ["https://tether.to/wp-content/uploads/2016/06/TetherWhitePaper.pdf"],
        "twitter": ["https://twitter.com/Tether_to"],
        "explorer": [
          "https://etherscan.io/token/0xdac17f958d2ee523a2206206994597c13d831ec7"
        ],
        "source_code": []
      }
    }
  },
  "status": {
    "timestamp": "2026-03-03T10:30:45.123Z",
    "error_code": 0,
    "error_message": null,
    "elapsed": 234,
    "credit_count": 1,
    "notice": null
  }
}

​
Error Response Examples

​
Invalid Request (400)

{
  "error": "Invalid request: addresses must be an array"
}

​
API Key Not Configured (500)

{
  "error": "API key not configured"
}

​
CoinMarketCap API Error (500)

{
  "error": "CoinMarketCap API request failed"
}

​
Implementation Notes

​
Server-Side Only

This endpoint is designed to be called from the server-side or through the CoinMarketCapService client wrapper. The API key is stored as an environment variable (COINMARKETCAP_API_KEY) and should never be exposed to clients.

​
Caching Strategy

The CoinMarketCapService implements a 1-hour cache for token information to reduce API calls and improve performance. Consider implementing additional caching layers if needed.

​
Fallback Information

The service provides built-in fallback information for common tokens (ETH, WETH, USDC, USDT, DAI) across multiple chains. This ensures the UI can display basic information even when the CoinMarketCap API is unavailable.

​
Rate Limits

Be aware of CoinMarketCap API rate limits based on your subscription tier. Implement appropriate throttling and caching strategies to stay within limits.

Build docs developers (and LLMs) love

Get started for freeTalk to us