GMGN Callout OpenAPI

The GMGN Callout OpenAPI lets approved partners programmatically publish and read on-chain "callouts" — a signal from a wallet that it is calling a specific token, optionally with a thesis and a linked Twitter/X identity.

Use it to:

• Create callouts — a wallet calls a token, attributed to a verified Twitter/X account.

• Read a wallet's history — paginate the callouts made by a single wallet.

• Read a token's callouts — the cross-wallet callout feed for one token, including the highest-multiplier callout.

All endpoints are POST, accept and return application/json (UTF-8), and are authenticated with an AK/SK HMAC signature on every request. Your ak / sk credentials are issued by GMGN.

Base URL	https://papi.gmgn.ai/callout/openapi/v1
Content-Type	application/json (UTF-8)
Auth	AK/SK HMAC-SHA256 signature (headers on every request)

---

Response envelope

Every response is wrapped in a {code, message, data} envelope. Business data always lives under data — unwrap data; never read top-level fields directly.

{ "code": 0, "message": "", "data": { } }

Situation	Shape
HTTP 200 + code = 0	Success. Business payload is in data. For write endpoints, whether the operation was accepted is data.success.
HTTP 4xx / 5xx	code (int) + message (string) describe the error. No data.

Two layers of outcome for writes

For POST /create, a transport-level HTTP 200 does not mean the callout was accepted. There are two distinct layers:

1. Transport / auth / limits — HTTP status code (400, 401, 429, 500).

2. Business rule — inside data, the boolean data.success. When false, inspect data.reject.reason.

Data types

• Prices, market caps, multipliers, percentages, and token amounts are strings (e.g. "0.5", "2.3") to preserve precision. Parse with a decimal-safe library, not native floats.

• Timestamps are Unix milliseconds (int64) unless a field is explicitly an ISO-8601 string (e.g. created_at on the /token feed).

• ulid is the unique identifier of a callout.

---

Authentication

Every request must be signed with your AK/SK credentials using HMAC-SHA256. Keep the sk server-side — never ship it in a client app or browser.

Required headers

Header	Description
X-Ak	Your issued access key.
X-Timestamp	Current time as a Unix millisecond timestamp.
X-Signature	Lowercase hex HMAC-SHA256 of the payload below.

Signature payload

Concatenate these fields in order, with no separators:

payload = ak + timestamp + method + path + rawQuery + body

Field	Description
ak	Same value as X-Ak.
timestamp	Same value as X-Timestamp (millisecond string).
method	Uppercase HTTP method, e.g. POST.
path	Request path including the API prefix, excluding host and query, e.g. /callout/openapi/v1/create.
rawQuery	URL query string (empty string for these POST endpoints).
body	Raw request body — must match the bytes actually sent exactly. Empty string if there is no body.

signature = HEX( HMAC_SHA256(sk, payload) )   // lowercase hex

⚠️ Timestamp window: ±30 seconds. If X-Timestamp differs from server time by more than 30s the request is rejected. Keep your client clock synced (NTP).

ℹ️ Because the signature covers the raw body bytes, sign the exact serialized JSON string you send. Do not re-serialize, pretty-print, or reorder keys between signing and sending.

Signing examples

Go

ts := strconv.FormatInt(time.Now().UnixMilli(), 10)
method := "POST"
path := "/callout/openapi/v1/create"
rawQuery := ""
body := `{"chain":"sol","call_wallet":"...","call_token":"...","twitter_id":"1926272637581336576"}`

payload := ak + ts + method + path + rawQuery + body
mac := hmac.New(sha256.New, []byte(sk))
mac.Write([]byte(payload))
sig := hex.EncodeToString(mac.Sum(nil))
// Headers: X-Ak: ak, X-Timestamp: ts, X-Signature: sig

Python

import hashlib, hmac, time, json, requests

AK, SK = "your_ak", "your_sk"
BASE = "https://papi.gmgn.ai"
path = "/callout/openapi/v1/create"
method = "POST"
raw_query = ""
body = json.dumps({
    "chain": "sol",
    "call_wallet": "...",
    "call_token": "...",
    "twitter_id": "1926272637581336576",
}, separators=(",", ":"))  # sign the exact bytes you send

ts = str(int(time.time() * 1000))
payload = AK + ts + method + path + raw_query + body
sig = hmac.new(SK.encode(), payload.encode(), hashlib.sha256).hexdigest()

resp = requests.post(
    BASE + path,
    data=body,  # send the same bytes that were signed
    headers={
        "Content-Type": "application/json",
        "X-Ak": AK,
        "X-Timestamp": ts,
        "X-Signature": sig,
    },
)
print(resp.json())

Node.js

import crypto from "node:crypto";

const AK = "your_ak", SK = "your_sk";
const BASE = "https://papi.gmgn.ai";
const path = "/callout/openapi/v1/create";
const method = "POST";
const rawQuery = "";
const body = JSON.stringify({
  chain: "sol",
  call_wallet: "...",
  call_token: "...",
  twitter_id: "1926272637581336576",
}); // sign the exact string you send

const ts = Date.now().toString();
const payload = AK + ts + method + path + rawQuery + body;
const sig = crypto.createHmac("sha256", SK).update(payload).digest("hex");

const resp = await fetch(BASE + path, {
  method,
  headers: {
    "Content-Type": "application/json",
    "X-Ak": AK,
    "X-Timestamp": ts,
    "X-Signature": sig,
  },
  body,
});
console.log(await resp.json());

Authentication failures (HTTP 401)

{ "code": 401, "message": "invalid signature" }

message	Meaning
missing auth header	One of X-Ak / X-Timestamp / X-Signature is absent.
invalid timestamp	X-Timestamp is malformed or outside the ±30s window.
invalid ak	The access key is not recognized.
invalid signature	The computed signature does not match.
api not allowed	This ak is not permitted to call this endpoint.
ip not allowed	The request originated from a non-allowlisted IP.

---

Rate limits

Limits are enforced per ak.

Limit	Quota	Over-limit response	Applies to
Request rate (QPS)	Per your allocation (default ≈ 10 QPS)	HTTP 429 rate limit exceeded	All endpoints
Callout 24h quota	Per your allocation	HTTP 429 ak daily quota exceeded	/create only

• Read endpoints (/get_record, /token) do not consume the callout 24h quota. They are still subject to the QPS limit.

• The 24h callout quota is distinct from the per-twitter_id and per-wallet business limits, which surface as business rejects (data.success = false) rather than HTTP 429 — see reject reasons.

---

Endpoints

POST /create — Create a callout

Publish a callout: one on-chain wallet calling one token. The source platform is derived automatically from your ak — you do not pass it.

POST https://papi.gmgn.ai/callout/openapi/v1/create

Request body

Field	Type	Required	Description
chain	string	✅	Chain, e.g. sol / eth / bsc.
call_wallet	string	✅	On-chain wallet address making the callout.
call_token	string	✅	Token address being called.
twitter_id	string	✅	Caller's Twitter/X rest_id. Numeric-only string (^[0-9]+$).
twitter_handle	string		@handle, used as a display fallback.
twitter_username	string		Display name, used as a display fallback.
call_thesis	string		Callout rationale text. Subject to content moderation.
callback_to_chain	string		Follow-callout: chain of the original post being followed.
callback_to_wallet	string		Follow-callout: wallet of the original post being followed.
callback_to_ulid	string		Follow-callout: ULID of the original post being followed.

ℹ️ The three callback_to_* fields describe a follow-callout (calling in response to another callout). Supply all three together, or none.

Success response (HTTP 200, data.success = true)

{
  "code": 0,
  "data": {
    "success": true,
    "record": {
      "chain": "sol",
      "call_wallet": "...",
      "call_token": "...",
      "call_price": "0.5",
      "call_mc": "500",
      "ulid": "01HF7...",
      "create_time": 1700000000000,
      "token_symbol": "TKN",
      "multiplier": "1"
    }
  }
}

ulid is the unique identifier of the callout.

Business reject (HTTP 200, data.success = false)

The request was well-formed and authenticated, but a business rule blocked it:

{
  "code": 0,
  "data": {
    "success": false,
    "reject": {
      "code": 40002404,
      "reason": "cooldown",
      "next_available_at": 1700000600000,
      "interval_minutes": 10
    }
  }
}

⚠️ Branch on reason (stable semantic string), never on code (troubleshooting aid only).

Reject reasons

reason	code	Meaning
twitter_not_bound	40002401	The calling wallet has no bound Twitter/X account.
twitter_not_verified	40002406	The bound Twitter/X account has not passed verification.
content_violation	40002407	call_thesis hit the content-moderation filter.
content_audit_unavailable	40002408	Moderation service unavailable — fail-closed reject. Retry later.
holding_too_low	40002403	The wallet's holding of this token is below the threshold.
cooldown	40002404	Same wallet + same token is in a cooldown window. next_available_at (ms) and interval_minutes describe it.
twitter_daily_limit	40002409	This twitter_id exceeded its 24h callout count. next_available_at is the window reset time.
daily_limit	40002405	24h callout count exceeded. next_available_at is the window reset time.

reject fields

Field	Type	Description
reason	string	Semantic reject reason (use this).
code	int	Numeric business code (troubleshooting only).
next_available_at	int64	For time-based rejects (cooldown, daily_limit, twitter_daily_limit): next allowed time, Unix ms.
interval_minutes	int64	For cooldown: length of the cooldown window in minutes.

ℹ️ Token safety checks (honeypot, etc.) are currently disabled. They were previously a hard block, but new pools lacking safety data caused false rejections, so the hard block was removed in favor of a disclaimer approach. No safety-related reason is returned today — you do not need a handler branch for it. This may be reinstated later with separate notice.

Invalid parameters (HTTP 400)

{ "code": 400, "message": "invalid twitter_id: must be a numeric rest_id" }

Missing or non-numeric twitter_id returns the above; other missing required fields return a corresponding 400.

---

POST /get_record — Callouts by wallet

Return the callout history of a single wallet, newest first, with a cursor that pages toward older records. Read endpoint — does not consume the 24h quota.

POST https://papi.gmgn.ai/callout/openapi/v1/get_record

Request body

Field	Type	Required	Description
chain	string	✅	Chain.
call_wallet	string	✅	Wallet address to query.
limit	int		Page size. Max 50.
page_token	string		Pagination cursor (next_page_token from the previous page). Empty for the first page.

Success response

{
  "code": 0,
  "data": {
    "records": [
      {
        "chain": "sol",
        "call_wallet": "...",
        "call_token": "...",
        "call_price": "0.5",
        "call_mc": "500",
        "ulid": "01HF7...",
        "multiplier": "2.3",
        "token_symbol": "TKN",
        "token_logo": "...",
        "twitter_username": "...",
        "holding_percentage": "0.12"
      }
    ],
    "next_page_token": "01HF6..."
  }
}

records[] fields

Field	Type	Description
chain	string	Chain.
call_wallet	string	Wallet that made the callout.
call_token	string	Token address called.
call_price	string	Token price at callout time.
call_mc	string	Market cap at callout time.
ulid	string	Callout unique identifier.
multiplier	string	Current multiplier vs. callout price (e.g. "2.3").
token_symbol	string	Token symbol.
token_logo	string	Token logo URL.
twitter_username	string	Caller display name.
holding_percentage	string	Caller's holding percentage of the token.

Pagination — pass page_token = the previous response's next_page_token to fetch the next (older) page. An empty next_page_token means there are no older records.

ℹ️ Unlike /token, /get_record reflects the real callout source per call_wallet. If you need to distinguish which platform a callout came from, use this endpoint.

---

POST /token — Callouts by token

Return the cross-wallet callout feed for one token: all callouts on that token, the highest-multiplier callout (top_message), and a pagination cursor. Read endpoint — does not consume the 24h quota.

POST https://papi.gmgn.ai/callout/openapi/v1/token

Request body

Field	Type	Required	Description
chain	string	✅	Chain.
call_token	string	✅	Token address.
cursor	string		Pagination cursor (base64). Empty for the first page.
limit	int		Page size.

Success response

{
  "code": 0,
  "data": {
    "chain": "sol",
    "community": { "token_address": "..." },
    "messages": [
      {
        "id": "gmgn_01HF7...",
        "content": "...",
        "username": "...",
        "display_name": "...",
        "profile_image_url": "...",
        "wallet_address": "...",
        "user_twitter_url": "...",
        "follower_count": 0,
        "created_at": "2026-07-14T00:00:00Z",
        "source": "gmgn",
        "multiplier": "2.3",
        "ulid": "01HF7..."
      }
    ],
    "has_more": true,
    "top_message": { },
    "next_cursor": "..."
  }
}

messages[] fields

Field	Type	Description
id	string	Message identifier.
content	string	Callout thesis / text.
media_url	string / null	Attached media, if any.
username	string	Caller handle.
display_name	string	Caller display name.
profile_image_url	string / null	Caller avatar URL.
wallet_address	string	Caller wallet address.
user_twitter_url	string	Caller Twitter/X profile URL.
follower_count	int64	Caller follower count.
created_at	string	ISO-8601 timestamp of the callout.
source	string / null	Callout source — see note below.
multiplier	string	Multiplier vs. callout price.
ulid	string	Callout unique identifier.

top_message — the highest-multiplier callout for this token in the last 30 days. Returned only on the first page (empty cursor). If there is none, the field is omitted.

Pagination

• has_more (bool) is the authoritative signal for whether to keep paging.

• next_cursor is returned only when has_more is true. When there are no more pages the field is omitted entirely (not an empty string or null).

⚠️ Page on has_more, not on the presence of next_cursor.

ℹ️ On /token, source is always gmgn — this aggregated token-page view does not pass through third-party source identifiers. To distinguish callouts by originating platform, use /get_record, which reflects the real source per call_wallet.

---

HTTP status codes

Status	Meaning
200	Request handled. For writes, inspect data.success.
400	Invalid parameters (missing/malformed required field).
401	Signature authentication failed. See Authentication failures.
429	Rate limit or 24h quota exceeded. See Rate limits.
500	Internal error. Safe to retry with backoff.

---

OpenAPI 3.0 specification

The complete OAS 3.0 definition below can be imported directly into Swagger UI, Redoc, or Postman.

ℹ️ The X-Signature value must be computed per request — it cannot be a static value in Swagger/Postman. Use a pre-request script to build the signature over ak + timestamp + method + path + rawQuery + body.

openapi: 3.0.3
info:
  title: GMGN Callout OpenAPI
  version: 1.0.0
servers:
  - url: https://papi.gmgn.ai/callout/openapi/v1

components:
  schemas:
    Reject:
      type: object
      properties:
        code: { type: integer, description: "Business code (troubleshooting aid; branch on reason)" }
        reason: { type: string, description: "Reject reason (use this to branch)", example: cooldown }
        next_available_at: { type: integer, format: int64, description: "Next allowed time (Unix ms)" }
        interval_minutes: { type: integer, format: int64 }
    CallOutRecord:
      type: object
      properties:
        chain: { type: string }
        call_wallet: { type: string }
        call_token: { type: string }
        call_price: { type: string }
        call_mc: { type: string }
        ulid: { type: string }
        create_time: { type: integer, format: int64 }
        token_symbol: { type: string }
        token_logo: { type: string }
        holding_percentage: { type: string }
        multiplier: { type: string }
        twitter_username: { type: string }
    TokenCallOutMessage:
      type: object
      properties:
        id: { type: string }
        content: { type: string }
        media_url: { type: string, nullable: true }
        username: { type: string }
        display_name: { type: string }
        profile_image_url: { type: string, nullable: true }
        wallet_address: { type: string }
        user_twitter_url: { type: string }
        follower_count: { type: integer, format: int64 }
        created_at: { type: string }
        source: { type: string, nullable: true, description: "Always gmgn on /token; use /get_record to distinguish source" }
        multiplier: { type: string }
        ulid: { type: string }
  parameters:
    XAk:        { name: X-Ak,        in: header, required: true, schema: { type: string } }
    XTimestamp: { name: X-Timestamp, in: header, required: true, schema: { type: string }, description: "Unix millisecond timestamp (±30s window)" }
    XSignature: { name: X-Signature, in: header, required: true, schema: { type: string }, description: "hex(HMAC_SHA256(sk, ak+ts+method+path+rawQuery+body))" }

paths:
  /create:
    post:
      summary: Create a callout
      parameters:
        - $ref: '#/components/parameters/XAk'
        - $ref: '#/components/parameters/XTimestamp'
        - $ref: '#/components/parameters/XSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [chain, call_wallet, call_token, twitter_id]
              properties:
                chain: { type: string, example: sol }
                call_wallet: { type: string }
                call_token: { type: string }
                twitter_id: { type: string, pattern: '^[0-9]+$' }
                twitter_handle: { type: string }
                twitter_username: { type: string }
                call_thesis: { type: string }
                callback_to_chain: { type: string }
                callback_to_wallet: { type: string }
                callback_to_ulid: { type: string }
      responses:
        '200':
          description: Business outcome is in data.success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: integer }
                  data:
                    type: object
                    properties:
                      success: { type: boolean }
                      record: { $ref: '#/components/schemas/CallOutRecord' }
                      reject: { $ref: '#/components/schemas/Reject' }
        '400': { description: Invalid parameters }
        '401': { description: Signature authentication failed }
        '429': { description: Rate limit or 24h quota exceeded }
        '500': { description: Internal error }
  /get_record:
    post:
      summary: Callout history by wallet
      parameters:
        - $ref: '#/components/parameters/XAk'
        - $ref: '#/components/parameters/XTimestamp'
        - $ref: '#/components/parameters/XSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [chain, call_wallet]
              properties:
                chain: { type: string }
                call_wallet: { type: string }
                limit: { type: integer, maximum: 50 }
                page_token: { type: string }
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: integer }
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items: { $ref: '#/components/schemas/CallOutRecord' }
                      next_page_token: { type: string }
        '401': { description: Signature authentication failed }
        '429': { description: Rate limit }
        '500': { description: Internal error }
  /token:
    post:
      summary: Cross-wallet callout list by token
      parameters:
        - $ref: '#/components/parameters/XAk'
        - $ref: '#/components/parameters/XTimestamp'
        - $ref: '#/components/parameters/XSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [chain, call_token]
              properties:
                chain: { type: string }
                call_token: { type: string }
                cursor: { type: string }
                limit: { type: integer }
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: integer }
                  data:
                    type: object
                    properties:
                      chain: { type: string }
                      community:
                        type: object
                        properties:
                          token_address: { type: string }
                      messages:
                        type: array
                        items: { $ref: '#/components/schemas/TokenCallOutMessage' }
                      has_more: { type: boolean }
                      top_message: { $ref: '#/components/schemas/TokenCallOutMessage' }
                      next_cursor: { type: string }
        '401': { description: Signature authentication failed }
        '429': { description: Rate limit }
        '500': { description: Internal error }