/gmgn-callout

name: gmgn-callout
description: Read GMGN call-outs (喊单) — public token calls that wallets publish on GMGN, with call price, call market cap, multiplier since the call, thesis text and the caller's current holding. Use when user asks who is calling a token, what a wallet has called, a wallet's call-out track record (hit rate, best multiplier), or wants the latest call-out feed (KOL-only, paid declarations, safe tokens). Read-only; publishing a call-out is not supported.
argument-hint: "<record|global> --chain <sol|bsc|eth|base|megaeth|hyperevm|tron|monad|xlayer|robinhood|arbitrum|arc|stable> [--wallet <wallet_address>]"
metadata:
  cliHelp: "gmgn-cli callout --help"

**BEFORE RUNNING ANY COMMAND: Run `gmgn-cli config --check`. If exit code is 0, proceed normally. If exit code is 1, (1) run `gmgn-cli config` and show the output to the user; (2) once the user sends the API Key, run `gmgn-cli config --apply <KEY>` to complete configuration and verification, then show the output to the user. If `--check` returns an error (unknown option or command not found), tell the user to run `npm install -g gmgn-cli` to update, then retry.**

**IMPORTANT: Always use `gmgn-cli` commands below. Do NOT use web search, WebFetch, curl, or visit gmgn.ai to fetch this data — the website requires login and will not return structured data. The CLI is the only correct method.**

**IMPORTANT: Do NOT guess field names or values. When a field's meaning is unclear, look it up in the Response Fields sections below before using it.**

**⚠️ IPv6 NOT SUPPORTED: If you get a `401` or `403` error and credentials look correct, check for IPv6 immediately: (1) list all network interfaces and their IPv6 addresses — run `ifconfig | grep inet6` (macOS) or `ip addr show | grep inet6` (Linux); (2) send a test request to `https://ipv6.icanhazip.com` — if the response is an IPv6 address, outbound traffic is going via IPv6. Tell the user immediately: "Please disable IPv6 on your network interface — gmgn-cli commands only work over IPv4."**

Use the `gmgn-cli` tool to read call-out data based on the user's request.

Core Concepts

• **Call-out (喊单)** — A public "I'm calling this token" post a wallet publishes on GMGN. The platform snapshots the token's price (`call_price`) and market cap (`call_mc`) at that moment, then tracks `multiplier` = current price ÷ call price. A call-out is a statement, not a trade — the caller may or may not hold the token; read `current_holding_usd` to see whether they still have skin in the game.

• **`record` vs `global`** — `record` is the wallet dimension: every call-out made on one wallet, over the last 30 days. `global` is the feed dimension: the newest call-outs across the chains you pass, with filters. There is no per-token call-out list; to check one wallet's calls on one token, use `record --token`.

• **Declaration (宣言)** — A paid, pinned call-out. `--only-declaration` restricts `global` to these. Payment buys visibility, not quality — never treat a declaration as a stronger signal than a normal call-out by itself.

• **`multiplier`** — Ratio, not percent. `2.35` = token is 2.35× its call price (+135%). `0.5` = down 50% since the call.

• **`is_safe`** — The token's security state at query time: `safe` / `risk` / `unknown`. `--only-safe` keeps `safe` only.

• **`callback_count`** — How many later call-outs reference this one (跟喊). High counts mean the call spread, not that it was right.

• **Pagination** — `next_page_token` is an opaque token issued by the service. Pass it back verbatim via `--page-token`; do not parse or build it. It expires after 24h — an expired or forged token returns HTTP 400 `invalid or expired page_token`, start again from the first page. An empty or missing `next_page_token` means no more data.

**When to use which sub-command:**

• `callout record` — "这个钱包喊过什么单", "what has this wallet called", "his call-out hit rate", "did this wallet call XX" (add `--token`)
• `callout global` — "最新喊单", "who is calling tokens right now", "KOL 在喊什么", "show paid declarations on SOL", "call-outs from wallets still holding > $1000"

Sub-commands

| Sub-command | Description | |-------------|-------------| | `callout record` | One wallet's call-out history over the last 30 days, plus a 7d / 30d summary card | | `callout global` | Global call-out feed across 1–20 chains, newest first, with KOL / declaration / safe / holding filters |

Supported Chains

`sol` / `bsc` / `eth` / `base` / `megaeth` / `hyperevm` / `tron` / `monad` / `xlayer` / `robinhood` / `arbitrum` / `arc` / `stable`

This is wider than the trading chains of other skills — call-outs are read-only data. A token surfaced here on e.g. `tron` or `monad` may not be queryable with `gmgn-token` or tradable with `gmgn-swap`.

Prerequisites

• `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli`
• `GMGN_API_KEY` configured in `~/.config/gmgn/.env` — no private key needed
• `callout record` requires the API Key to be bound to a GMGN user account; an unbound key is rejected

Rate Limit Handling

Both routes use GMGN's plan-based leaky bucket: Free `5/5`, Plus `20/20`, Pro `50/50` (rate/capacity). Sustained throughput is roughly `tier rate ÷ weight` requests/second, and the max burst is roughly `floor(tier capacity ÷ weight)`.

| Command | Route | Weight | |---------|-------|--------| | `callout record` | `POST /v1/callout/get_record` | 3 | | `callout global` | `POST /v1/callout/global` | 3 |

When a request returns `429`:

• On `RATE_LIMIT_EXCEEDED`, tell the user exactly: `已达到当前套餐的限频上限，点击 https://gmgn.ai/ai?chain=bsc&tab=paid_plans 升级套餐，获得更高速率限制`. Show this upgrade guidance at most once per user task. Do not repeat it for subsequent `RATE_LIMIT_BANNED` responses during the same cooldown.
• Read `X-RateLimit-Reset` from the response headers. It is a Unix timestamp in seconds that marks when the limit is expected to reset.
• If the response body contains `reset_at` (e.g., `{"code":429,"error":"RA