TOKENS API

Gain insight into individual tokens, live pricing, top holders, and searchable catalogs. All token endpoints are priced at 0.0004 USD per settled request and require an X402 payment replay.

GET /token/{address}/{networkId}

Attribute	Value
Method	GET
Description	Returns comprehensive token metadata, market stats, social links, exchange listings, and launchpad details.
Settlements	/, /solana, /base
Price	0.0004 USD

Path parameters

Name	Type	Required	Notes
address	string	yes	Checksummed contract address.
networkId	integer	yes	Numeric chain identifier supported by Neura. Example: 1 (Ethereum), 137 (Polygon).

Example request

curl -X GET "$NEURA_BASE_URL/token/0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/1" \
  -H "Accept: application/json" \
  -H "X-402-Invoice: $INVOICE" \
  -H "X-402-Payment-Proof: $PROOF"

Response snapshot

{
  "success": true,
  "data": {
    "token": {
      "address": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "networkId": 1,
      "networkName": "Ethereum",
      "marketCap": 11000000000,
      "volume24h": 3500000000,
      "priceChange24h": -0.0025,
      "lastUpdated": "2025-01-15T12:34:56.000Z",
      "exchanges": [
        {
          "name": "Uniswap v3",
          "networkId": 1,
          "tradeUrl": "https://app.uniswap.org/#/swap?inputCurrency=0xA0b8..."
        }
      ],
      "launchpad": null,
      "socialLinks": {
        "website": "https://www.circle.com/usdc",
        "twitter": "https://twitter.com/circle"
      }
    }
  },
  "timestamp": "2025-01-15T12:34:56.000Z"
}

GET /token/{address}/{networkId}/price

Attribute	Value
Method	GET
Description	Returns the current price, both native and USD, for a specific token.
Settlements	/, /solana, /base
Price	0.0004 USD

Path parameters

Same as GET /token/{address}/{networkId}.

Response snapshot

{
  "success": true,
  "data": {
    "prices": [
      {
        "address": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "networkId": 1,
        "price": 0.9997,
        "priceUsd": 0.9997,
        "lastUpdated": "2025-01-15T12:36:02.000Z"
      }
    ]
  },
  "timestamp": "2025-01-15T12:36:02.123Z"
}

GET /token/{tokenId}/top10holders

Attribute	Value
Method	GET
Description	Lists the top ten token holders with balances and percentage ownership.
Settlements	/, /solana, /base
Price	0.0004 USD

Path parameters

Name	Type	Required	Notes
tokenId	string	yes	Use the {network}:{address} identifier returned by the token endpoints (for example ethereum:0xA0b8...).

Response snapshot

{
  "success": true,
  "data": {
    "tokenId": "ethereum:0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "holders": [
      {
        "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
        "balance": "6212345678900000",
        "percentage": 6.12,
        "rank": 1
      },
      {
        "address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE",
        "balance": "512345678900000",
        "percentage": 5.02,
        "rank": 2
      }
    ],
    "totalHolders": 256000,
    "lastUpdated": "2025-01-15T12:40:01.000Z"
  },
  "timestamp": "2025-01-15T12:40:01.500Z"
}

GET /tokens/search

Attribute	Value
Method	GET
Description	Searches tokens by name, symbol, or address and optionally limits the number of matches.
Settlements	/, /solana, /base
Price	0.0004 USD

Query parameters

Name	Type	Required	Notes
q	string	yes	Search phrase (case insensitive).
limit	integer	no	Default 20. Minimum 1, maximum 100. Values outside this range are rejected.

Example request

curl -G "$NEURA_BASE_URL/tokens/search" \
  --data-urlencode "q=bitcoin" \
  --data-urlencode "limit=5" \
  -H "Accept: application/json" \
  -H "X-402-Invoice: $INVOICE" \
  -H "X-402-Payment-Proof: $PROOF"

Response snapshot

{
  "success": true,
  "data": {
    "tokens": [
      {
        "id": "ethereum:0x1234...",
        "address": "0x1234...",
        "symbol": "WBTC",
        "name": "Wrapped Bitcoin",
        "decimals": 8,
        "networkId": 1,
        "marketCap": 6500000000,
        "volume24h": 250000000,
        "priceChange24h": -0.015,
        "lastUpdated": "2025-01-15T12:45:00.000Z"
      }
    ],
    "total": 42,
    "query": "bitcoin",
    "lastUpdated": "2025-01-15T12:45:00.000Z"
  },
  "timestamp": "2025-01-15T12:45:00.500Z"
}

Validation rules and errors

• Missing or malformed path parameters result in 400 with a descriptive error message ("tokenId is required", "Network ID must be numeric", etc.).

• Rate limit breaches produce 429 with retryAfter seconds.

• If a token cannot be found, the API returns success: false with an error message, still within a 200 response.

Refer to the Error Responses page for the full envelope format. Continue with the Wallets API for balance lookups.