query-token-info

# query-token-info — CLI Reference

Complete reference for every command in `scripts/cli.mjs`.

**Invocation pattern:** `node <skill-dir>/scripts/cli.mjs <command> '<json_params>'`
**Exit codes:** `0` success · `1` usage/upstream error · `3` network failure

---

## `search` — Search tokens by keyword

```bash
node <skill-dir>/scripts/cli.mjs search '{"keyword":"<keyword>","chainIds":"56"}'
```

### Parameters

| Param | Type | Required | Description |
|---|---|---|---|
| `keyword` | string | **yes** | Name / symbol / contract address |
| `chainIds` | string | no | Comma-separated chainIds (e.g. `"56"`, `"1,56,8453,CT_501"`); default: all |
| `orderBy` | string | no | Sort key, e.g. `volume24h` |

### Return fields (under `.data[]`)

| Field | Type | Description |
|---|---|---|
| `chainId` | string | Chain identifier (e.g. `"56"` = BSC) |
| `contractAddress` | string | Token contract address |
| `tokenId` | string | Binance-internal token ID (stable across address changes) |
| `name`, `symbol` | string | Token display names |
| `icon` | string | Logo path — prefix with `https://bin.bnbstatic.com` |
| `price`, `percentChange24h` | string | Latest USD price and 24h change (%) |
| `volume24h`, `marketCap`, `liquidity` | string | All USD; string-encoded decimals |
| `tagsInfo` | object | Risk / recognition tags, categorized (e.g. `"Sensitive Events": [...]`, `"Community Recognition Level": [...]`) |

---

## `meta` — Static token metadata

```bash
node <skill-dir>/scripts/cli.mjs meta '{"chainId":"56","contractAddress":"0x..."}'
```

### Parameters

| Param | Type | Required | Description |
|---|---|---|---|
| `chainId` | string | **yes** | Chain identifier |
| `contractAddress` | string | **yes** | Token contract address (case-insensitive) |

### Return fields (under `.data`)

| Field | Type | Description |
|---|---|---|
| `tokenId` | string | Binance-internal stable ID |
| `name`, `symbol`, `decimals` | — | Display name, ticker, precision |
| `chainName`, `chainIconUrl` | string | Chain display info |
| `links` | array of `{label, link}` | Website / whitepaper / social links |
| `aiNarrativeFlag` | number | `1` = AI has narrative summary available |
| `nativeAddressFlag` | boolean | `true` = native chain coin (not an ERC-20) |

`links[]` entries are `{label, link}` — labels include `"website"`, `"whitepaper"`, social platforms.

---

## `dynamic` — Real-time market data

```bash
node <skill-dir>/scripts/cli.mjs dynamic '{"chainId":"56","contractAddress":"0x..."}'
```

### Parameters

| Param | Type | Required | Description |
|---|---|---|---|
| `chainId` | string | **yes** | Chain identifier |
| `contractAddress` | string | **yes** | Token contract address |

### Return fields (under `.data`)

Price + volume/buy/sell breakdowns across multiple windows (5m, 1h, 4h, 24h), separated by on-chain vs Binance-routed:

| Field pattern | Meaning |
|---|---|
| `price`, `nativeTokenPrice` | Current USD price and chain-native price |
| `volume{5m,1h,4h,24h}` | Total trading volume in window (USD) |
| `volume{window}{Buy,Sell}` | Direction breakdown |
| `volume{window}Binance` | Binance-routed subset |
| `volume{window}Net{Buy,Binance}` | Net flow = Buy − Sell |
| `holders` | Holder count (if available) |
| `liquidity` | Current liquidity in USD |

---

## `kline` — Candlestick OHLCV

```bash
node <skill-dir>/scripts/cli.mjs kline '{"chainId":"56","contractAddress":"0x...","interval":"1h","limit":24}'
```

### Parameters

| Param | Type | Required | Description |
|---|---|---|---|
| `chainId` | string | **yes** | Chain identifier — `1` (Ethereum) / `56` (BSC) / `8453` (Base) / `CT_501` (Solana) |
| `contractAddress` | string | **yes** | Token contract address |
| `interval` | string | **yes** | Candle size: `1s` / `1min` / `3min` / `5min` / `15min` / `30min` / `1h` / `2h` / `4h` / `6h` / `8h` / `12h` / `1d` / `3d` / `1w` / `1m` |
| `limit` | number | no | Optional. Max 500 per request. Has higher priority than `from` when both provided. |
| `from` | number | no | Optional. Start timestamp in **milliseconds**. |
| `to` | number | no | Optional. End timestamp in **milliseconds**. |
| `pm` | string | no | Optional. Price mode — `p` (price, default) or `m` (marketcap). |

### Return shape (under `.data[]`)

Each row is a 2D array (7 numbers):

| Index | Field |
|---|---|
| `[0]` | open price (USD) |
| `[1]` | high price |
| `[2]` | low price |
| `[3]` | close price |
| `[4]` | volume |
| `[5]` | timestamp (ms since epoch, start of candle) |
| `[6]` | trade count |

Envelope is `{ data, status: {error_code, error_message} }` — no `code` field (unlike other commands).

---

## Errors

Exit codes: `0` ok · `1` upstream/usage (stderr: reason; stdout: body with business `code`) · `3` network.
Business `code`: `000000` ok · `100004` rate-limited · `100002` bad param · `000400` token not found / unsupported chain.

#!/usr/bin/env node
// query-token-info CLI — self-contained, zero-dep, Node >= 22
// Usage: node cli.mjs <command> '<json_params>'
//
// Commands:
//   search   token search by keyword
//   meta     static token metadata
//   dynamic  real-time market data (price, volume, holders)
//   kline    candlestick data
//
// All 4 commands use the SAME parameter shape: { chainId, contractAddress, ... }.
// Internally, kline hits a different host and uses different upstream field names
// (platform/address) — this CLI handles the translation so the LLM caller sees
// one consistent interface.

// ---- inline HTTP helper (self-contained, zero dependency) ----
const TIMEOUT_MS = 10_000;
const UA = { 'Accept-Encoding': 'identity', 'User-Agent': 'binance-web3/2.0 (Skill)' };

// ---- chainId → upstream kline platform name ----
// Single source of truth for chain identity. Used only by kline (other commands
// pass chainId through as-is to the Binance Web3 API which accepts chainId directly).
const CHAIN_ID_TO_PLATFORM = {
  '1':      'ethereum',
  '56':     'bsc',
  '8453':   'base',
  'CT_501': 'solana',
};

const qs = (p) => Object.entries(p)
  .filter(([, v]) => v != null)
  .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
  .join('&');

async function call({ url, method = 'GET', body, headers = {} }) {
  const ctrl = new AbortController();
  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
  const opts = { method, headers: { ...UA, ...headers }, signal: ctrl.signal };
  if (method === 'POST') { opts.headers['content-type'] = 'application/json'; opts.body = JSON.stringify(body || {}); }
  let res;
  try { res = await fetch(url, opts); }
  catch { clearTimeout(timer); throw Object.assign(new Error('Network request failed'), { exitCode: 3 }); }
  clearTimeout(timer);
  const data = await res.json();
  if (res.status >= 400) throw Object.assign(new Error(`HTTP ${res.status}`), { exitCode: 1, body: data });
  return data;
}

// ---- commands: (params) => { url, method?, body?, headers? } ----
const COMMANDS = {
  search: (p) => ({
    url: `https://web3.binance.com/bapi/defi/v5/public/wallet-direct/buw/wallet/market/token/search/ai?${qs(p)}`,
  }),
  meta: (p) => ({
    url: `https://web3.binance.com/bapi/defi/v1/public/wallet-direct/buw/wallet/dex/market/token/meta/info/ai?${qs(p)}`,
  }),
  dynamic: (p) => ({
    url: `https://web3.binance.com/bapi/defi/v4/public/wallet-direct/buw/wallet/market/token/dynamic/info/ai?${qs(p)}`,
  }),
  kline: (p) => {
    // Translate unified interface → upstream kline field names.
    // { chainId, contractAddress, interval, ... } → { platform, address, interval, ... }
    const { chainId, contractAddress, ...rest } = p;
    const platform = chainId == null ? undefined : CHAIN_ID_TO_PLATFORM[chainId];
    if (chainId != null && platform === undefined) {
      const supported = Object.keys(CHAIN_ID_TO_PLATFORM).map((k) => `"${k}"`).join(', ');
      throw Object.assign(
        new Error(`kline: unsupported chainId "${chainId}". Supported: ${supported}`),
        { exitCode: 1 },
      );
    }
    const upstream = { ...rest };
    if (platform !== undefined) upstream.platform = platform;
    if (contractAddress !== undefined) upstream.address = contractAddress;
    return {
      url: `https://dquery.sintral.io/u-kline/v1/k-line/candles?${qs(upstream)}`,
    };
  },
};

// ---- exports (for unit testing; direct execution still works — see dispatch below) ----
export { COMMANDS, call, qs, UA, TIMEOUT_MS, CHAIN_ID_TO_PLATFORM };

// ---- CLI dispatch (only runs when executed directly, not when imported) ----
if (import.meta.url === `file://${process.argv[1]}`) {
  const [cmd, paramsStr] = process.argv.slice(2);

  if (!cmd || cmd === '--help' || cmd === '-h') {
    console.log("Usage: node cli.mjs <command> '<json_params>'\n\nCommands:");
    for (const name of Object.keys(COMMANDS)) console.log(`  ${name}`);
    process.exit(0);
  }

  const builder = COMMANDS[cmd];
  if (!builder) { console.error(`Unknown command: ${cmd}\nRun with --help to see available commands.`); process.exit(1); }

  let params = {};
  if (paramsStr) {
    try { params = JSON.parse(paramsStr); }
    catch { console.error('Invalid JSON params'); process.exit(1); }
  }

  try {
    const result = await call(builder(params));
    console.log(JSON.stringify(result, null, 2));
  } catch (err) {
    console.error(err.message);
    if (err.body) console.log(JSON.stringify(err.body, null, 2));
    process.exit(err.exitCode || 1);
  }
}

---
name: query-token-info
description: |
  Per-token details for a specific token identified by keyword, symbol, or contract address:
  (1) search — find tokens by keyword/symbol/contract;
  (2) meta — static info: name, symbol, logo, social links, creator, official website;
  (3) dynamic — real-time market data: price, 24h change, volume, holder count, liquidity;
  (4) kline — OHLCV candlestick data for technical analysis.
  Use for: "price of $X", "search for token Y", "kline chart for $Z", "who created $W",
  "social links for $V", "holder count of $U", "candlestick data", "find the contract address of <token>".
metadata:
  author: binance-web3-team
  version: "2.0"
---

# Query Token Info Skill

## Overview

Four read-only token endpoints fronted by one CLI. The agent picks a subcommand and passes
a JSON blob; with this skill user can:

Search Tokens: Find tokens by name, symbol, or contract address across chains.
Token Research: Get token metadata, social links, and creator info.
Market Analysis: Real-time price, volume, holder distribution, and liquidity data.
Chart Analysis: K-Line candlestick data for technical analysis.

## When to Use This Skill

| User intent | Command |
|-------------|---------|
| Search a token by keyword, symbol, or contract address | `search` |
| Get static metadata (name, symbol, logo, social links, creator) | `meta` |
| Get real-time market data (price, volume, holders, liquidity) | `dynamic` |
| Get candlestick chart / OHLCV data | `kline` |

## Supported Chains

| Chain | `chainId` |
|-------|-----------|
| Ethereum | `1` |
| BSC | `56` |
| Base | `8453` |
| Solana | `CT_501` |

All four commands (`search`, `meta`, `dynamic`, `kline`) use the same `chainId` values.

## How to Call APIs

```bash
node <skill-dir>/scripts/cli.mjs <command> '<json_params>'
```

Example:

```bash
node <skill-dir>/scripts/cli.mjs search '{"keyword":"<keyword>","chainIds":"56"}'
```

## Commands

| Command | Purpose | Required args | Example |
|---------|---------|---------------|---------|
| `search` | Search tokens by keyword | `keyword` (optional: `chainIds`, `orderBy`) | `node <skill-dir>/scripts/cli.mjs search '{"keyword":"<keyword>","chainIds":"1,56,8453,CT_501"}'` |
| `meta` | Static token metadata | `chainId`, `contractAddress` | `node <skill-dir>/scripts/cli.mjs meta '{"chainId":"56","contractAddress":"0x..."}'` |
| `dynamic` | Real-time market data | `chainId`, `contractAddress` | `node <skill-dir>/scripts/cli.mjs dynamic '{"chainId":"56","contractAddress":"0x..."}'` |
| `kline` | Candlestick data | `chainId`, `contractAddress`, `interval` (optional: `limit`, `from`, `to`, `pm`) | `node <skill-dir>/scripts/cli.mjs kline '{"chainId":"56","contractAddress":"0x...","interval":"1min","limit":500}'` |

## Rules

- **Icon URL**: `icon` fields are relative paths. Prepend `https://bin.bnbstatic.com` for a usable URL.
- **Numbers as strings**: All numeric market fields (`price`, `volume24h`, `marketCap`, etc.) are
  returned as strings. Convert before arithmetic.
- **Kline is a 2D array**, not JSON objects. Each candle: `[open, high, low, close, volume, timestamp_ms, count]`.
- **Kline time window**: `limit` takes priority over `from` when both are provided. Use `to`
  with `limit` to fetch the N most recent candles ending at `to`. `pm` selects price (`p`,
  default) or market-cap (`m`) series.
- **Intervals** supported by `kline`: `1s`, `1min`, `3min`, `5min`, `15min`, `30min`, `1h`, `2h`,
  `4h`, `6h`, `8h`, `12h`, `1d`, `3d`, `1w`, `1m`.

## Full CLI Reference

See [`references/cli.md`](references/cli.md) for per-subcommand invocations, parameter tables, return-field tables, and real response samples.