> For the complete documentation index, see [llms.txt](https://docs.gmgn.ai/index/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gmgn.ai/index/gmgn-callout-openapi.md).

# GMGN Callout OpenAPI

## GMGN Callout OpenAPI — Integration and Migration Guide

**Who this is for**

* **New integrators** — read call-out data through GMGN OpenAPI (`openapi.gmgn.ai`).
* **Existing integrators** — currently calling `https://papi.gmgn.ai/callout/openapi/v1/*` with AK/SK authentication, and needing to migrate to GMGN OpenAPI (see section 5).

**Scope**: the call-out read endpoints `/global`, `/get_record` and `/token`. This is a **read-only** API.

### Contents

1. Overview
2. Getting access
3. Authentication
4. Endpoints
5. Migrating from the old endpoint (existing integrators)
6. Rate limits
7. Error codes
8. FAQ
9. Support and quota requests

***

### 1. Overview

| Item                    | Detail                                                                                                                                                                                                                |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Production Base URL** | `https://openapi.gmgn.ai`                                                                                                                                                                                             |
| **Test Base URL**       | `https://openapi.wenmoon.cc`                                                                                                                                                                                          |
| **Auth**                | API Key (`X-APIKEY` header) + query `timestamp` (seconds) + `client_id` (UUID). **Read endpoints require no signature**                                                                                               |
| **Protocol**            | All endpoints are `POST` with a JSON body; responses are JSON                                                                                                                                                         |
| **Endpoints**           | <p><code>POST /v1/callout/global</code> — global call-out feed<br><code>POST /v1/callout/get\_record</code> — call-out history by wallet<br><code>POST /v1/callout/token</code> — cross-wallet call-outs by token</p> |
| **Supported chains**    | `sol`, `bsc`, `eth`, `base`, `megaeth`, `hyperevm`, `tron`, `monad`, `xlayer`, `robinhood`, `arbitrum`, `arc`, `stable`, `avalanche`, `elysium`                                                                       |
| **Rate limit**          | Per account plan. Call-out partners are enabled on the Pro tier: about 16 QPS (see section 6)                                                                                                                         |

> ℹ️ **AK/SK credentials are no longer issued** for new integrations — everyone uses a GMGN OpenAPI Key.

***

### 2. Getting access

Create an API Key at [**gmgn.ai/ai**](https://gmgn.ai/ai).

Once you have the key you can call the API directly — there are no signing credentials to request from us. For a higher quota, an egress IP allowlist entry, or help with a problem, see section 9.

***

### 3. Authentication

Every request must carry all three:

```http
POST /v1/callout/global?timestamp=1730784000&client_id=3f6c1f4e-8a1b-4c43-9d2e-5b7f0c9e1a22
Host: openapi.gmgn.ai
X-APIKEY: <your_api_key>
Content-Type: application/json

{"limit": 50}
```

| Parameter   | In     | Description                                                                                                                           |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `X-APIKEY`  | Header | Your API Key                                                                                                                          |
| `timestamp` | Query  | Current Unix time in **seconds**. Must be within **15 seconds** of server time — keep NTP enabled                                     |
| `client_id` | Query  | **A newly generated UUID per request.** A repeat within 20 seconds is rejected as a replay, so **generate a new one for retries too** |

> ℹ️ Read endpoints do not need `X-Signature`.

#### Python

```python
import time, uuid, requests

BASE = "https://openapi.gmgn.ai"        # test: https://openapi.wenmoon.cc
API_KEY = "<your_api_key>"

def call(path, payload):
    params = {"timestamp": int(time.time()), "client_id": str(uuid.uuid4())}
    headers = {"X-APIKEY": API_KEY, "Content-Type": "application/json"}
    resp = requests.post(BASE + path, params=params, json=payload, headers=headers, timeout=15)
    return resp.json()

print(call("/v1/callout/global", {"limit": 50}))
```

#### Go

```go
func call(ctx context.Context, path string, payload any) (*http.Response, error) {
	body, err := json.Marshal(payload)
	if err != nil {
		return nil, fmt.Errorf("marshal body: %w", err)
	}
	q := url.Values{}
	q.Set("timestamp", strconv.FormatInt(time.Now().Unix(), 10))
	q.Set("client_id", uuid.NewString())
	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
		baseURL+path+"?"+q.Encode(), bytes.NewReader(body))
	if err != nil {
		return nil, fmt.Errorf("new request: %w", err)
	}
	req.Header.Set("X-APIKEY", apiKey)
	req.Header.Set("Content-Type", "application/json")
	return httpClient.Do(req) // set httpClient.Timeout to >= 15s
}
```

***

### 4. Endpoints

All responses share one envelope:

```json
{ "code": 0, "message": "ok", "data": { } }
```

#### 4.1 POST /v1/callout/global — Global call-out feed

Call-outs from all chains interleaved, paged newest first.

**Request**

| Field                                 | Required | Type         | Description                                                                                                                                                                                                                                     |
| ------------------------------------- | :------: | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chains`                              |          | string\[]    | Only these chains, **at most 20**. Omit = all chains                                                                                                                                                                                            |
| `limit`                               |          | int          | Page size, 0–50. `0` = default                                                                                                                                                                                                                  |
| `page_token`                          |          | string       | `next_page_token` from the previous page                                                                                                                                                                                                        |
| `since`                               |          | string / int | Incremental lower bound: a ULID (returns `ulid > since`) or a **millisecond** timestamp (returns `create_time >= since`). A seconds timestamp returns 400. Ignored when `page_token` is present. **Cannot be combined with `only_declaration`** |
| `only_kol`                            |          | bool         | Only call-outs from KOL wallets                                                                                                                                                                                                                 |
| `only_safe`                           |          | bool         | Only safe tokens                                                                                                                                                                                                                                |
| `only_declaration`                    |          | bool         | Only paid declarations                                                                                                                                                                                                                          |
| `min_holding_usd` / `max_holding_usd` |          | decimal      | Caller's current holding, USD range                                                                                                                                                                                                             |

**Response**: `data.list[]` (call-out records) and `data.next_page_token` (empty = no more pages).

> ⚠️ With filters applied, a page **may hold more than `limit`** records. Decide whether to keep paging by checking whether `next_page_token` is empty — **not by the record count**.

**Incremental polling (recommended)**

A call-out's `create_time` / `ulid` are set at creation, but the record lands in the database a few seconds later. **Do not use the previous round's highest `ulid` as `since`** — you will miss records that landed late.

```python
seen, cursor_ms = set(), int(time.time() * 1000) - 60_000
while True:
    payload, max_ct = {"since": cursor_ms - 30_000, "limit": 50}, cursor_ms
    while True:
        data = call("/v1/callout/global", payload)["data"]
        for r in data["list"]:
            if r["ulid"] not in seen:
                seen.add(r["ulid"])
                handle(r)
                max_ct = max(max_ct, r["create_time"])
        if not data.get("next_page_token"):
            break
        payload = {"page_token": data["next_page_token"]}
    cursor_ms = max_ct
    time.sleep(60)
```

> ℹ️ `seen` only needs to hold the last few minutes of ULIDs — otherwise it grows without bound.

#### 4.2 POST /v1/callout/get\_record — Call-out history by wallet

**Request**

| Field         | Required | Type   | Description                                                  |
| ------------- | :------: | ------ | ------------------------------------------------------------ |
| `chain`       |     ✅    | string | Chain                                                        |
| `call_wallet` |     ✅    | string | Wallet address. Returns every call-out made from this wallet |
| `call_token`  |          | string | Only this token. **Exact, case-sensitive match**             |
| `limit`       |          | int    | 0–50. `0` = default 20                                       |
| `page_token`  |          | string | `next_page_token` from the previous page                     |

**Response**

* `data.call_out_records[]` — call-outs from the **last 30 days**.
* `data.next_page_token` — empty = no more pages.
* `data.summary` — the wallet's 7d / 30d rollup (`total_calls`, `avg_multiplier`, `best_multiplier`, `hit_2x_count`, `top_tokens`). **Omitted when there is no data.**

> ℹ️ The holding fields (`current_holding_usd`, `current_pnl_usd`, `balance`, `accu_cost`, etc.) are **the calling wallet's own** current holding of that token — they **do not merge the caller's other wallets**. An empty string means the value is temporarily unavailable (for example, no price), **not 0**.

#### 4.3 POST /v1/callout/token — Cross-wallet call-outs by token

**Request**

| Field                                           | Required | Type   | Description                                                                                                                                              |
| ----------------------------------------------- | :------: | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chain`                                         |     ✅    | string | Chain                                                                                                                                                    |
| `call_token`                                    |     ✅    | string | Token address                                                                                                                                            |
| `cursor`                                        |          | string | `next_cursor` from the previous page                                                                                                                     |
| `limit`                                         |          | int    | 0–50. `0` = 50; **above 50 returns 400**                                                                                                                 |
| `only_kol`                                      |          | bool   | Only KOL call-outs                                                                                                                                       |
| `start_time` / `end_time`                       |          | int    | `create_time` range (**milliseconds**, inclusive). `0` = no bound                                                                                        |
| `min_call_holding_usd` / `max_call_holding_usd` |          | number | Holding USD range **at call time**. `0` = no bound                                                                                                       |
| `app_lang`                                      |          | string | Translation language: `zh-CN` Simplified, `zh-TW` Traditional, any other non-empty value English. Returned in `display_content`. Omit = source text only |

**Response**: `messages[]`, `has_more`, `next_cursor`, `top_message` (highest multiplier in the last 30 days), `vip_message` (the active paid pinned declaration), `history_vip_messages`, `declaration_level`.

> ⚠️ Use `has_more` to decide whether to keep paging.

#### 4.4 Pagination cursors

* `next_page_token` / `next_cursor` are **opaque strings**. Pass them back verbatim — **do not parse or concatenate them**.
* They are valid for **24 hours**. An expired or invalid cursor returns `HTTP 400`; restart from the first page.

#### 4.5 Privacy

Responses **contain no GMGN internal user IDs**: `user_id`, `encrypted_user_id` and `id` are not returned. User-uploaded avatar and media URLs that embed an internal ID are blanked (an empty string in records, `null` in token messages). Twitter avatars are returned normally.

***

### 5. Migrating from the old endpoint (existing integrators)

#### 5.1 What you need to change

| Change                 | Old `papi.gmgn.ai/callout/openapi/v1`                                          | New `openapi.gmgn.ai/v1/callout`            | Mandatory                                                                 |
| ---------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------- |
| Base URL               | `https://papi.gmgn.ai/callout/openapi/v1/{name}`                               | `https://openapi.gmgn.ai/v1/callout/{name}` | ✅                                                                         |
| Credentials            | AK + SK                                                                        | API Key                                     | ✅                                                                         |
| Signature              | Header `X-Signature` = `hex(HMAC-SHA256(sk, ak+ts+METHOD+path+rawQuery+body))` | No signature on read endpoints              | ✅ Delete the signing code                                                 |
| Identity header        | `X-Ak`                                                                         | `X-APIKEY`                                  | ✅                                                                         |
| Timestamp              | Header `X-Timestamp`, milliseconds, ±30s                                       | Query `timestamp`, **seconds**, ±15s        | ✅                                                                         |
| Replay protection      | None                                                                           | Query `client_id`, a new UUID per request   | ✅                                                                         |
| `/global` response     | `data.records`                                                                 | `data.list`                                 | ✅                                                                         |
| `/get_record` response | `data.records`                                                                 | `data.call_out_records`                     | ✅                                                                         |
| Cursors                | Old cursors                                                                    | Opaque token; **old cursors are not valid** | Start from page 1 when you switch                                         |
| `/global` page size    | Fixed 100                                                                      | `limit ≤ 50`                                | If applicable: twice as many requests for the same data                   |
| `/global` time range   | Last 7 days only                                                               | **Not truncated**                           | If applicable: truncate by `create_time` yourself if you only want 7 days |
| `/token` `limit > 50`  | Capped at 50                                                                   | **Returns 400**                             | If applicable                                                             |
| 429 response headers   | `Retry-After`, `X-RateLimit-*`                                                 | Same                                        | —                                                                         |

**Unchanged**: request fields (`chains`, `since`, `only_kol`, `call_wallet`, `call_token`, `cursor`, time ranges, holding ranges, etc.), record fields, how holdings are computed, data range (`get_record` 30 days), `since` semantics and the incremental-polling recommendation. **Both endpoints read the same data.**

**New capabilities on the new endpoint (optional)**: `/global` gains `limit`, `only_safe`, `only_declaration` and holding-range filters, and can fetch data older than 7 days; `/get_record` gains `summary`; `/token` gains `app_lang` translations.

#### 5.2 Code migration example

**Old**

```python
def call_old(path, payload):
    ts = str(int(time.time() * 1000))                    # milliseconds
    body = json.dumps(payload, separators=(",", ":"))
    full_path = "/callout/openapi/v1" + path
    msg = AK + ts + "POST" + full_path + "" + body
    sig = hmac.new(SK.encode(), msg.encode(), hashlib.sha256).hexdigest()
    headers = {"X-Ak": AK, "X-Timestamp": ts, "X-Signature": sig,
               "Content-Type": "application/json"}
    return requests.post("https://papi.gmgn.ai" + full_path, data=body, headers=headers).json()

records = call_old("/global", {})["data"]["records"]
```

**New**

```python
def call_new(path, payload):
    params = {"timestamp": int(time.time()), "client_id": str(uuid.uuid4())}  # seconds + fresh UUID
    headers = {"X-APIKEY": API_KEY, "Content-Type": "application/json"}
    return requests.post("https://openapi.gmgn.ai/v1/callout" + path,
                         params=params, json=payload, headers=headers, timeout=15).json()

records = call_new("/global", {"limit": 50})["data"]["list"]   # records → list
```

> ℹ️ Put both call paths behind one interface and switch with a config flag — it makes staged rollout and rollback straightforward.

#### 5.3 Migration steps

| Step                     | When                               | What you do                                                                                                                 | What GMGN does                                       | Done when                                        |
| ------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------ |
| ① Provision              | —                                  | Create a key at [gmgn.ai/ai](https://gmgn.ai/ai). For a higher QPS or an egress IP allowlist, submit the form in section 9  | Enable the Pro quota                                 | You have a working key                           |
| ② Rework                 | after ①                            | Change the code per 5.1 / 5.2, with a config switch between old and new                                                     | Answer questions                                     | Code ready                                       |
| ③ Test integration       | after ②                            | Exercise every endpoint you use against `openapi.wenmoon.cc` and run the 5.4 checklist                                      | Help investigate                                     | Checklist fully passed                           |
| ④ Staged production      | after ③                            | Switch production to the new endpoint (optionally a share of traffic or a subset of endpoints first) and watch for 24 hours | Watch call volume and error rate on the new endpoint | No sustained 4xx / 429                           |
| ⑤ Full cutover           | after ④                            | Stop calling the old endpoint and tell your contact "cutover complete"                                                      | Confirm old-endpoint traffic is zero                 | Old endpoint at 0 traffic for 7 consecutive days |
| ⑥ Old credentials closed | after ⑤, or **\[TBD sunset date]** | —                                                                                                                           | Disable your old AK/SK (announced in advance)        | Old endpoint returns 401                         |

> ℹ️ **Rollback**: the old endpoint stays available until ⑥, so if the new one misbehaves, flip the switch back — no data impact.
>
> ⚠️ **Sunset date**: the old read endpoints stop serving on **\[TBD sunset date]**. If you have not migrated by then, your old AK/SK will be disabled; switching to the new endpoint restores service.

#### 5.4 Cutover checklist

* [ ] Timestamp is in **seconds**, and NTP is enabled on the server
* [ ] Every request — **including retries** — generates a fresh `client_id`
* [ ] The HMAC signing code and the `X-Ak` / `X-Timestamp` headers are deleted
* [ ] `/global` reads `data.list`; paging ends when `next_page_token` is empty; truncate to 7 days yourself if you need that
* [ ] `/get_record` reads `data.call_out_records`
* [ ] `/token` sends `limit` no greater than 50
* [ ] Old cursors are discarded at cutover and paging starts from page 1
* [ ] Incremental polling still uses `since` = (previous round's highest `create_time`) − 30000, de-duplicating by `ulid`
* [ ] 429 is handled: back off per `Retry-After`, and do not keep retrying while banned
* [ ] Client timeout is ≥ 15 seconds
* [ ] Old and new endpoints were compared for the same wallet / token, with matching record counts and key fields (compare the last 7 days for `/global`)

***

### 6. Rate limits

* Counted on **two dimensions at once** — API Key and source IP. Calls the same key makes to **other** OpenAPI endpoints also consume this quota.
* Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; a 429 additionally carries `Retry-After` (seconds).
* For a higher quota, submit the form in section 9 with your peak QPS and use case.

***

### 7. Error codes

On failure the HTTP status matches `code`, and `error` is a string error code:

```json
{ "code": 401, "error": "AUTH_TIMESTAMP_EXPIRED", "message": "..." }
```

| HTTP | `error`                                          | Cause / handling                                                                                                                        |
| ---- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `BAD_REQUEST`                                    | Bad parameter (unsupported chain, `limit` out of range, `since` given as a seconds timestamp, etc.) or an expired cursor. Fix and retry |
| 401  | `AUTH_KEY_INVALID`                               | API Key is not valid                                                                                                                    |
| 401  | `AUTH_TIMESTAMP_EXPIRED` / `AUTH_TIMESTAMP_SKEW` | Timestamp is outside ±15 seconds. Check you are not sending milliseconds, and that the server clock is synced                           |
| 401  | `AUTH_CLIENT_ID_REPLAYED`                        | Duplicate `client_id` — generate a new one for every request, including retries                                                         |
| 403  | `AUTH_KEY_BLOCKED` / `AUTH_IP_BLOCKED`           | Key is blocked, or the source IP is not allowlisted. See section 9                                                                      |
| 429  | `RATE_LIMIT_EXCEEDED` / `RATE_LIMIT_BANNED`      | Over quota. Back off per `Retry-After` — **continuing to call while banned extends the ban**                                            |
| 502  | `CALLOUT_API_UNAVAILABLE`                        | Upstream temporarily unavailable or timed out. Retry with backoff                                                                       |
| 503  | `CALLOUT_CURSOR_UNAVAILABLE`                     | Retry shortly                                                                                                                           |

***

### 8. FAQ

**Q: Will the data change after migrating?** A: No. Both endpoints read the same data, with identical record fields and holding semantics.

**Q: Can I call both endpoints during the dual-run period?** A: Yes. Both work until step ⑥. Use a switch rather than calling both long-term.

**Q: Can I call these endpoints over MCP or a CLI?** A: No — REST only.

**Q: Can new integrators still request AK/SK?** A: No. Everyone uses a GMGN OpenAPI Key, created at [gmgn.ai/ai](https://gmgn.ai/ai).

***

### 9. Support and quota requests

Hit a problem, or need a **higher QPS / quota**, an **egress IP allowlist** entry, or a blocked key released?

**→** [**Submit a request**](https://docs.google.com/forms/d/e/1FAIpQLScRnqI0PSQBEewJnF3JnfRSm50PylZRcIAfE7bl96Yp7RCQCg/viewform?usp=dialog)

For a quota request, include your **peak QPS and use case**. For a problem report, include the endpoint, an example request and response, and the timestamp of the failing call so we can trace it. Never put the API Key itself in the form.
