diff --git a/Readme.md b/Readme.md index da6bc1f..44d393c 100644 --- a/Readme.md +++ b/Readme.md @@ -505,6 +505,9 @@ gmgn-cli portfolio created-tokens --chain sol --wallet ### Track ```bash +# Followed token map for a wallet +gmgn-cli track follow-tokens --chain sol --wallet + # Follow-wallet trade records gmgn-cli track follow-wallet --chain sol gmgn-cli track follow-wallet --chain sol --limit 20 --min-amount-usd 1000 diff --git a/Readme.zh.md b/Readme.zh.md index dcadb7c..ef65031 100644 --- a/Readme.zh.md +++ b/Readme.zh.md @@ -529,6 +529,9 @@ gmgn-cli portfolio created-tokens --chain sol --wallet ### Track ```bash +# 查询钱包收藏的代币列表 +gmgn-cli track follow-tokens --chain sol --wallet + # 追踪关注钱包的交易动态 gmgn-cli track follow-wallet --chain sol gmgn-cli track follow-wallet --chain sol --limit 20 --min-amount-usd 1000 diff --git a/docs/cli-usage.md b/docs/cli-usage.md index 6749cb2..23fb239 100644 --- a/docs/cli-usage.md +++ b/docs/cli-usage.md @@ -349,6 +349,54 @@ gmgn-cli market signal --chain sol --groups '' [--raw] --- +## track follow-tokens + +Query the followed token list for a wallet. Returns a paginated list of tokens the wallet has bookmarked on GMGN, with full market data. API Key auth only. + +```bash +gmgn-cli track follow-tokens \ + --chain \ + --wallet \ + [--group-id ] \ + [--order-by ] \ + [--direction ] \ + [--limit ] \ + [--cursor ] \ + [--raw] +``` + +| Option | Required | Description | +|--------|----------|-------------| +| `--chain` | Yes | `sol` / `bsc` / `base` / `eth` | +| `--wallet` | Yes | Wallet address | +| `--group-id` | No | `all_group` (all tokens), `default`, or a user-defined group ID | +| `--interval` | No | Time interval for price change stats: `1m` / `5m` / `1h` / `6h` / `24h` | +| `--order-by` | No | `created_at` / `swaps` / `volume` / `market_cap` / `liquidity` / `price` / `open_timestamp` | +| `--direction` | No | Sort direction: `asc` / `desc` | +| `--limit` | No | Page size | +| `--cursor` | No | Pagination cursor from previous response | +| `--search` | No | Search by token name or address | + +--- + +## track follow-token-groups + +Query the follow token group names for a wallet. Returns the groups a wallet uses to organise its followed tokens on GMGN. API Key auth only. + +```bash +gmgn-cli track follow-token-groups \ + --chain \ + --wallet \ + [--raw] +``` + +| Option | Required | Description | +|--------|----------|-------------| +| `--chain` | Yes | `sol` / `bsc` / `base` / `eth` | +| `--wallet` | Yes | Wallet address | + +--- + ## portfolio follow-wallet Query follow-wallet trade records. Returns trades from wallets you personally follow on the GMGN platform. The follow list is resolved automatically from the GMGN user account bound to the API Key — `--wallet` is optional. Signed auth (API Key + private key signature). diff --git a/skills/gmgn-track/SKILL.md b/skills/gmgn-track/SKILL.md index f27184a..2c18c99 100644 --- a/skills/gmgn-track/SKILL.md +++ b/skills/gmgn-track/SKILL.md @@ -1,7 +1,7 @@ --- name: gmgn-track -description: Get real-time crypto buy/sell activity from Smart Money wallets, KOL influencer wallets, and personally followed wallets via GMGN API — alpha signals, whale tracking, meme token copy-trading ideas on Solana, BSC, Base, or Ethereum. Use when user asks what smart money or KOLs are buying, wants whale alerts, on-chain alpha, or copy-trade signals. (For a specific wallet address, use gmgn-portfolio.) -argument-hint: " --chain [--wallet ]" +description: Get real-time crypto buy/sell activity from Smart Money wallets, KOL influencer wallets, and personally followed wallets via GMGN API — alpha signals, whale tracking, meme token copy-trading ideas on Solana, BSC, Base, or Ethereum. Also query which tokens a wallet has followed (bookmarked) on GMGN. Use when user asks what smart money or KOLs are buying, wants whale alerts, on-chain alpha, copy-trade signals, or wants to check a wallet's followed tokens. (For a specific wallet address's portfolio, use gmgn-portfolio.) +argument-hint: " --chain [--wallet ]" metadata: cliHelp: "gmgn-cli track --help" --- @@ -49,6 +49,8 @@ Use the `gmgn-cli` tool to query on-chain tracking data based on the user's requ | Sub-command | Description | |-------------|-------------| +| `track follow-tokens` | Followed token list for a wallet — which tokens a wallet has bookmarked on GMGN, with full market data | +| `track follow-token-groups` | Follow token group names for a wallet — the group names and IDs the wallet uses to organise followed tokens | | `track follow-wallet` | Trade records from wallets the user personally follows on GMGN | | `track kol` | Real-time trades from KOL / influencer wallets tagged by GMGN | | `track smartmoney` | Real-time trades from smart money / whale wallets tagged by GMGN | @@ -61,7 +63,7 @@ Use the `gmgn-cli` tool to query on-chain tracking data based on the user's requ - `gmgn-cli` installed globally — if missing, run: `npm install -g gmgn-cli` - `GMGN_API_KEY` configured in `~/.config/gmgn/.env` — required for all sub-commands -- `GMGN_PRIVATE_KEY` — required for `track follow-wallet` only (signed auth); not needed for `kol` or `smartmoney` +- `GMGN_PRIVATE_KEY` — required for `track follow-wallet` only (signed auth); not needed for `follow-tokens`, `kol`, or `smartmoney` ## Rate Limit Handling @@ -69,6 +71,8 @@ All tracking routes used by this skill go through GMGN's leaky-bucket limiter wi | Command | Route | Weight | |---------|-------|--------| +| `track follow-tokens` | `GET /v1/user/follow_tokens` | 3 | +| `track follow-token-groups` | `GET /v1/user/follow_token_groups` | 1 | | `track follow-wallet` | `GET /v1/trade/follow_wallet` | 3 | | `track kol` | `GET /v1/user/kol` | 1 | | `track smartmoney` | `GET /v1/user/smartmoney` | 1 | @@ -101,6 +105,18 @@ When a request returns `429`: ## Usage Examples ```bash +# Followed token list for a wallet on SOL +gmgn-cli track follow-tokens --chain sol --wallet + +# Followed token list on BSC, raw JSON output +gmgn-cli track follow-tokens --chain bsc --wallet --raw + +# Follow token group names for a wallet on SOL +gmgn-cli track follow-token-groups --chain sol --wallet + +# Follow token group names, raw JSON output +gmgn-cli track follow-token-groups --chain sol --wallet --raw + # Follow-wallet trades (all wallets you follow) gmgn-cli track follow-wallet --chain sol @@ -126,6 +142,66 @@ gmgn-cli track smartmoney --limit 10 --raw gmgn-cli track smartmoney --chain sol --side sell --limit 10 --raw ``` +## `track follow-tokens` Options + +| Option | Description | +|--------|-------------| +| `--chain` | Required. `sol` / `bsc` / `base` / `eth` | +| `--wallet
` | Required. Wallet address to query | +| `--group-id ` | Filter by group: `all_group` (all tokens across groups), `default` (default group), or a user-defined group ID | +| `--interval ` | Time interval for price change stats (e.g. `1m`, `5m`, `1h`, `6h`, `24h`) | +| `--order-by ` | Sort field: `created_at` / `swaps` / `volume` / `market_cap` / `liquidity` / `price` / `open_timestamp` | +| `--direction ` | Required when `--order-by` is set. `asc` / `desc` | +| `--limit ` | Page size | +| `--cursor ` | Pagination cursor from previous response | +| `--search ` | Search by token name or address | + +## `track follow-tokens` Response Fields + +Top-level fields: + +| Field | Description | +|-------|-------------| +| `cursor` | Opaque cursor for fetching the next page | +| `all_following` | Total number of followed tokens | +| `is_recommend` | Whether results include recommended tokens | +| `followings` | Array of followed token objects | + +Each item in `followings` contains: + +| Field | Description | +|-------|-------------| +| `address` | Token contract address | +| `symbol` | Token ticker symbol | +| `name` | Token name | +| `chain` | Chain the token is on | +| `price` | Current token price | +| `price_change_percent` | Price change percentage | +| `volume` | Trading volume | +| `liquidity` | Pool liquidity | +| `market_cap` | Market cap | +| `swaps` | Total swaps | +| `group_ids` | Follow groups this token belongs to | +| `open_timestamp` | Unix timestamp when trading opened | + +## `track follow-token-groups` Options + +| Option | Description | +|--------|-------------| +| `--chain` | Required. `sol` / `bsc` / `base` / `eth` | +| `--wallet
` | Required. Wallet address to query | + +## `track follow-token-groups` Response Fields + +`data` is an array. Each item contains: + +| Field | Description | +|-------|-------------| +| `chain` | Chain the group is on | +| `group_id` | Group identifier (e.g. `default`, or a user-defined ID) | +| `group_name` | Human-readable group name | +| `rank` | Display order / sort rank | + ## `track follow-wallet` Options | Option | Description | @@ -311,6 +387,7 @@ To research any token surfaced by smart money activity, follow [`docs/workflow-t ## Notes +- `track follow-tokens` uses exist auth (API Key only); `--wallet` is required - `track follow-wallet` uses signed auth (API Key + private key signature); `track kol` and `track smartmoney` use exist auth (API Key only) - `track follow-wallet` returns trades from wallets followed on the GMGN platform; the follow list is resolved automatically from the GMGN user account bound to the API Key — `--wallet` is optional - Use `--raw` to get single-line JSON for further processing diff --git a/src/client/OpenApiClient.ts b/src/client/OpenApiClient.ts index 1f4c749..7075372 100644 --- a/src/client/OpenApiClient.ts +++ b/src/client/OpenApiClient.ts @@ -435,6 +435,14 @@ export class OpenApiClient { return this.authSignedRequest("GET", "/v1/trade/follow_wallet", { chain, ...extra }, null); } + async getFollowTokens(chain: string, walletAddress: string, extra: Record = {}): Promise { + return this.authExistRequest("GET", "/v1/user/follow_tokens", { chain, wallet_address: walletAddress, ...extra }); + } + + async getFollowGroupNames(chain: string, walletAddress: string): Promise { + return this.authExistRequest("GET", "/v1/user/follow_token_groups", { chain, wallet_address: walletAddress }); + } + async getKol(chain?: string, limit?: number): Promise { const query: Record = {}; if (chain) query["chain"] = chain; diff --git a/src/commands/track.ts b/src/commands/track.ts index 6663a25..9506729 100644 --- a/src/commands/track.ts +++ b/src/commands/track.ts @@ -7,6 +7,47 @@ import { validateChain } from "../validate.js"; export function registerTrackCommands(program: Command): void { const track = program.command("track").description("On-chain tracking commands: follow-wallet trades, KOL trades, Smart Money trades"); + track + .command("follow-tokens") + .description("Get the followed token list for a wallet on a given chain") + .requiredOption("--chain ", "Chain: sol / bsc / base / eth") + .requiredOption("--wallet
", "Wallet address") + .option("--group-id ", "Filter by group: all_group (all), default, or a user-defined group ID") + .option("--interval ", "Time interval for price change stats (e.g. 1m, 5m, 1h, 6h, 24h)") + .option("--order-by ", "Sort field: created_at / swaps / volume / market_cap / liquidity / price / open_timestamp") + .option("--direction ", "Sort direction: asc / desc") + .option("--limit ", "Page size", parseInt) + .option("--cursor ", "Pagination cursor") + .option("--search ", "Search by token name or address") + .option("--raw", "Output raw JSON") + .action(async (opts) => { + validateChain(opts.chain); + const extra: Record = {}; + if (opts.groupId) extra["group_id"] = opts.groupId; + if (opts.interval) extra["interval"] = opts.interval; + if (opts.orderBy) extra["order_by"] = opts.orderBy; + if (opts.direction) extra["direction"] = opts.direction; + if (opts.limit != null) extra["limit"] = opts.limit; + if (opts.cursor) extra["cursor"] = opts.cursor; + if (opts.search) extra["search_text"] = opts.search; + const client = new OpenApiClient(getConfig()); + const data = await client.getFollowTokens(opts.chain, opts.wallet, extra).catch(exitOnError); + printResult(data, opts.raw); + }); + + track + .command("follow-token-groups") + .description("Get the follow token group names for a wallet on a given chain") + .requiredOption("--chain ", "Chain: sol / bsc / base / eth") + .requiredOption("--wallet
", "Wallet address") + .option("--raw", "Output raw JSON") + .action(async (opts) => { + validateChain(opts.chain); + const client = new OpenApiClient(getConfig()); + const data = await client.getFollowGroupNames(opts.chain, opts.wallet).catch(exitOnError); + printResult(data, opts.raw); + }); + track .command("follow-wallet") .description("Get follow-wallet trade records")