TOKENARU — Agent Integration Guide

Tokenaru turns natural language into CoinGecko data. One HTTP call, one query. Payment required (x402).

ENDPOINT
  GET /api/lookup?q=<query>

QUERY EXAMPLES
  USDC on Ethereum mainnet     → contract address
  price of bitcoin             → price data
  trending coins               → trending coins, NFTs, categories
  top coins by market cap      → ranked market data
  bitcoin tickers              → exchange/DEX tickers
  bitcoin price on 30-12-2023   → historical data
  price of USDC on Ethereum     → chained: resolve address, then fetch price

PAYMENT
  The endpoint returns 402 Payment Required. Use an x402-aware client (e.g. @x402/fetch) to pay and retry.
  Default price: $0.002 per request.

RESPONSE SHAPES
  Address lookup success:
    { ok: true, address, symbol, name, chainId, chainName, coingeckoPlatformId, source }
  Other capabilities:
    { ok: true, capability, data }
  Error:
    { ok: false, error, message } or { ok: false, capability, error, message }

HOW TO USE
  1. Build the URL: baseUrl + "/api/lookup?q=" + encodeURIComponent(userQuery)
  2. If you have x402 payment capability, use wrapFetchWithPayment or equivalent to pay and fetch
  3. Parse the JSON response
  4. On 402, the response body describes the payment required; retry with payment headers

WHY TOKENARU INSTEAD OF CALLING COINGECKO DIRECTLY
  - One query, one response. No need to reason about endpoints or params.
  - Server holds API keys; you pay per request.
  - Built-in chaining (e.g. address → price) without orchestrating multiple calls.
  - Cached address lookups reduce latency.