# Partner API {% hint style="info" %} The API is **not public**. To request access, please contact **Market Stalker** directly with your intended use case. Each approved partner receives an API key and limited quota for selected endpoints. {% endhint %}
Get Telegram User Profile **Purpose:** Returns detailed user data including historic display/usernames, recent activity, and group roles. Request: ``` GET /admin-roles?query= Header: x-api-key: YOUR_PARTNER_KEY ``` Example: ``` curl -H "x-api-key: YOUR_PARTNER_KEY" ".../user-report?query=DataWizz" ``` Response: ``` { "user_id": 6137747116, "display_name": "DataWizz πŸ§™ (Market Stalker)", "username": "DataWizz", "first_seen": "2025-09-13T22:40:31+00:00", "last_seen": "2025-11-04T06:41:29+00:00", "history": { "previous_display_names_count": 2, "previous_display_names": [ "DataWizz πŸ§™", "DataWizz (Channel in bio)" ], "previous_usernames_count": 0, "previous_usernames": [] }, "groups_summary": { "total_groups": 5, "active_in_last_7_days": 5, "admin_in_group_count": 1 }, "groups": [ { "group_id": -1002282510595, "name": "The Market Stalker Community", "first_seen_in_group": "2025-09-13T22:40:31+00:00", "last_seen_in_group": "2025-11-04T06:41:29+00:00", "members_count": 2285, "token": { "address": "0x522Ec96bCed6dc26325120EdF3931d34E417a620", "chain": "ethereum", "symbol": "STLKR" }, "telegram": { "link": "https://t.me/themarketstalker", "link_type": "portal" }, "admin": { "is_admin": true, "is_owner": true, "role": "owner", "admin_tag": "Owner", "rights": { "change_info": true, "ban_users": true, "delete_messages": true, "pin_messages": true, "add_admins": true } } }, { "group_id": -1003178265398, "name": "White Monkey", "first_seen_in_group": "2025-10-30T23:20:55+00:00", "last_seen_in_group": "2025-10-30T23:20:55+00:00", "members_count": 1977, "token": null, "telegram": { "link": "https://t.me/whitemonkeyportal", "link_type": "portal" }, "admin": { "is_admin": false, "is_owner": false, "role": null, "admin_tag": null, "rights": null } }, { "group_id": -1002812191154, "name": "Marie Rose - SPX Mascot πŸ’ΉπŸ§²πŸŒΉ", "first_seen_in_group": "2025-10-29T22:52:13+00:00", "last_seen_in_group": "2025-10-29T22:52:13+00:00", "members_count": 1591, "token": { "address": "0xcaa1E525ACb44aeC4e0D17a0e2467AA3Ea7EE3A6", "chain": "ethereum", "symbol": "MARIE" }, "telegram": { "link": "https://t.me/marieroseethereum", "link_type": "portal" }, "admin": { "is_admin": false, "is_owner": false, "role": null, "admin_tag": null, "rights": null } }, { "group_id": -1003072270133, "name": "FRENLY COMMUNITY", "first_seen_in_group": "2025-10-28T08:45:06+00:00", "last_seen_in_group": "2025-10-28T08:45:06+00:00", "members_count": 1335, "token": { "address": "0x26EcB65d997CBFf18FCa447cB85f6aF1175a22B0", "chain": "base", "symbol": "FRENLY" }, "telegram": { "link": "https://t.me/frenly_portal", "link_type": "portal" }, "admin": { "is_admin": false, "is_owner": false, "role": null, "admin_tag": null, "rights": null } }, { "group_id": -1002947732445, "name": "Rhino - Official Ethereum Macot", "first_seen_in_group": "2025-10-24T22:36:59+00:00", "last_seen_in_group": "2025-10-24T22:36:59+00:00", "members_count": 678, "token": null, "telegram": { "link": "https://t.me/rhinoeth", "link_type": "portal" }, "admin": { "is_admin": false, "is_owner": false, "role": null, "admin_tag": null, "rights": null } } ], "admin_groups": [ { "group_id": -1002282510595, "name": "The Market Stalker Community", "last_seen_in_group": "2025-11-04T06:41:29+00:00", "members_count": 2285, "telegram": { "link": "https://t.me/themarketstalker", "link_type": "portal" }, "role": "owner", "admin_tag": "Owner", "rights": { "change_info": true, "ban_users": true, "delete_messages": true, "pin_messages": true, "add_admins": true } } ] } ```
Get Groups & Roles (Queried User Has Admin Rights) **Purpose:** Returns only the groups where the user has admin privileges, with a normalized `role` (`owner`, `super_admin`, `mod`), optional `admin_tag`, and a best join link. Request: ``` GET /admin-roles?query= Header: x-api-key: YOUR_PARTNER_KEY ``` Example: ``` curl -H "x-api-key: YOUR_PARTNER_KEY" ".../admin-roles?query=Cryptodevbsctg" ``` Response: ``` { "status": "ok", "meta": { "query": "Cryptodevbsctg" }, "user": { "id": 6171169457, "username": "Cryptodevbsctg", "display_name": "⚑Synergy⚑ OG", "username_history": [], "display_name_history": [ "⚑ Synergy⚑ OG", "⚑Synergy⚑ OG", "Synergy βš‘πŸ’ΉπŸ§²πŸŸ¦βš‘ OG", "Synergy πŸ’ΉπŸ§²πŸŸ¦ OG" ] }, "admin_summary": { "owner": 6, "super_admin": 3, "mod": 4 }, "groups_with_admin": [ { "id": -1003195316992, "name": "$CORGI CULT", "role": "owner", "admin_tag": "OG", "link_type": "public", "join_url": "https://t.me/corgiog" }, { "id": -1002914932974, "name": "Holder Guard", "role": "owner", "admin_tag": "β€”", "link_type": "public", "join_url": "https://t.me/holderguardtg" }, { "id": -1003001951506, "name": "Mandela effect", "role": "owner", "admin_tag": "Admin", "link_type": "public", "join_url": "https://t.me/mandelaeffecttg" }, { "id": -1002993540678, "name": "PumpBase Lounge", "role": "owner", "admin_tag": "Dev PumpBase", "link_type": "public", "join_url": "https://t.me/pumpbaseshillgroup" }, { "id": -1003255276513, "name": "Pumpit", "role": "owner", "admin_tag": "Pumpit", "link_type": "private", "join_url": "https://t.me/+PL4QgMPDIcE3NjI5" }, { "id": -1003000895346, "name": "⚑PumpBase⚑", "role": "owner", "admin_tag": "Base maxi", "link_type": "public", "join_url": "https://t.me/pumpbasepad" }, { "id": -1003112342557, "name": "Group -1003112342557", "role": "super_admin", "admin_tag": "β€”", "link_type": "β€”", "join_url": "β€”" }, { "id": -1001733141232, "name": "Playbunny", "role": "super_admin", "admin_tag": "β€”", "link_type": "public", "join_url": "https://t.me/playbunnycoin" }, { "id": -1002994396194, "name": "Shield | Base", "role": "super_admin", "admin_tag": "Support", "link_type": "public", "join_url": "https://t.me/shieldcoinbase" }, { "id": -1002737779964, "name": "$Kandy On Base", "role": "mod", "admin_tag": "β€”", "link_type": "portal", "join_url": "https://t.me/kandyonchain" }, { "id": -1003185428621, "name": "$PUMPBULL", "role": "mod", "admin_tag": "Chad", "link_type": "portal", "join_url": "https://t.me/pumpbulll" }, { "id": -1002444269034, "name": "Ape Alliance | Alpha Lounge", "role": "mod", "admin_tag": "OG SYNERGY", "link_type": "private", "join_url": "https://t.me/+Rm_PtVxosmdiYmNh" }, { "id": -1002489355941, "name": "Yellow Pill CTO πŸŸ¨πŸ’Š", "role": "mod", "admin_tag": "Support", "link_type": "portal", "join_url": "https://t.me/yellowpill_cto" } ] } ``` **Role Logic** * `owner` β†’ user is group owner. * `super_admin` β†’ admin with `admin_rights.add_admins = true`. * `mod` β†’ admin (or has rights) but **without** `add_admins`. **Link Preference** * `portal` β†’ `public` β†’ `invite`. If none, returns `β€”` with `join_url: "β€”"`.
Get Group Members, Including Recent Activity + Admin List **Purpose:** Return a group’s member list, recent activity windows (today / last 7 days), and a concise admin list. Search by **token address** or by a **group username** (we match against both `portal_username` and `group_public_username`). If multiple groups match, we pick the one with the **most recent `last_logged_at`**. Request: ``` GET /group-members?token_address= | /group-members?group_username= Header: x-api-key: YOUR_PARTNER_KEY ``` Example: ``` # by group username (matches portal_username or group_public_username) curl -H "x-api-key: YOUR_PARTNER_KEY" \ ".../group-members?group_username=themarketstalker" # by token address curl -H "x-api-key: YOUR_PARTNER_KEY" \ ".../group-members?token_address=0x522Ec96bCed6dc26325120EdF3931d34E417a620" ``` Response: ``` { "status": "ok", "meta": { "match_by": "token_address", "value": "0x522Ec96bCed6dc26325120EdF3931d34E417a620" }, "group": { "group_id": -1002282510595, "group_name": "The Market Stalker Community", "portal_username": "themarketstalker", "group_public_username": null, "members_count": 2285 }, "overview": { "total_members_seen": 2285 }, "today": { "active": 23, "joined": 2 }, "last_7_days": { "active": 95, "joined": 35 }, "members": [ { "user_id": 7202168682, "display_name": "BlindSilentNinja", "first_seen": "2025-09-13T22:46:51+00:00", "last_seen": "2025-11-04T10:19:00+00:00", "admin": true, "admin_tag": "Owner" }, { "user_id": 6137747116, "display_name": "DataWizz πŸ§™ (Market Stalker)", "first_seen": "2025-09-13T22:40:31+00:00", "last_seen": "2025-11-04T06:41:29+00:00", "admin": true, "admin_tag": "Owner" }, { "user_id": 2103605856, "display_name": "Syncieman.eth🐺", "first_seen": "2025-09-13T22:49:22+00:00", "last_seen": "2025-11-04T11:01:20+00:00", "admin": true, "admin_tag": "Mod" }, { "user_id": 6068830149, "display_name": "Bill Kenn", "first_seen": "2025-09-13T23:36:50+00:00", "last_seen": "2025-11-03T20:37:31+00:00", "admin": true, "admin_tag": "Bill" }, { "user_id": 567713533, "display_name": "π˜Ώπ™π—–π—₯π—¬π—£π—§π—’πŸ…³πŸ…°οΈπŸ††πŸ…Ά $xα΄€ΚŸα΄˜Κœα΄€ | ᴄᴏᴛ α΄‡ΚŸΙͺᴛᴇ 🏠", "first_seen": "2025-09-14T07:32:22+00:00", "last_seen": "2025-11-02T13:17:20+00:00", "admin": true, "admin_tag": "DrCrypto" }, { "user_id": 1361785012, "display_name": "Risk", "first_seen": "2025-09-14T07:35:43+00:00", "last_seen": "2025-10-31T17:26:48+00:00", "admin": true, "admin_tag": "Risk" }, { "user_id": 6016060428, "display_name": "CubeETH", "first_seen": "2025-09-14T09:07:27+00:00", "last_seen": "2025-10-31T17:26:48+00:00", "admin": true, "admin_tag": "Cube" }, { "user_id": 563515153, "display_name": "V - American Pepe $APE", "first_seen": "2025-09-15T04:39:19+00:00", "last_seen": "2025-10-31T17:26:48+00:00", "admin": true, "admin_tag": "V-Guy" }, { "user_id": 6387792471, "display_name": "🎩 𝐌𝐫.πŸ††πŸ…·πŸ…°οΈπŸ…»πŸ…΄ 🐳", "first_seen": "2025-09-15T04:39:19+00:00", "last_seen": "2025-10-31T17:26:48+00:00", "admin": true, "admin_tag": "Whale" }, { "user_id": 7031045125, "display_name": "GOAT", "first_seen": "2025-09-15T11:43:55+00:00", "last_seen": "2025-11-04T11:23:31+00:00", "admin": false, "admin_tag": null }, { "user_id": 6724355432, "display_name": "ΞTM", "first_seen": "2025-09-14T04:41:45+00:00", "last_seen": "2025-11-04T10:55:47+00:00", "admin": false, "admin_tag": null }, { "user_id": 1540594318, "display_name": "The Fox | SES | XDC | MMKK | (Ronin Arc)", "first_seen": "2025-09-15T11:43:55+00:00", "last_seen": "2025-11-04T10:53:50+00:00", "admin": false, "admin_tag": null } ] } ``` **Behavior & Notes** * **Query params:** provide **exactly one** of `token_address` or `group_username`. * `group_username` checks **both** `portal_username` and `group_public_username`. * **Multi-match resolution:** if multiple group docs match, we return the one with the **latest `last_logged_at`** (most up-to-date snapshot). * **Activity windows:** * **Today** = last 24 hours (UTC). * **Last 7 days** = rolling 7 days (UTC). * **Sorting:** `members` are sorted by **most recent `last_seen`** (fallback to `first_seen`). * **Admin fields:** When a member is an admin, we include `admin: true` and `admin_tag` (if available).
Get Most Recent Groups Queried User Has Been Active In **Purpose:** Return the most recent groups a user has been seen in (sorted by `last_seen_in_group` desc) and includes token details when available. Request: ``` GET /recent-groups?query=&limit= Header: x-api-key: YOUR_PARTNER_KEY ``` **Query Params** * `query` (required): Telegram `user_id` or `@username`. * `limit` (optional, default 5, max 25): Number of groups to return. Examples: **cURL (by @username)** ``` curl -H "x-api-key: YOUR_PARTNER_KEY" \ ".../recent-groups?query=@DataWizz&limit=5" ``` **cURL (by user\_id)** ``` curl -H "x-api-key: YOUR_PARTNER_KEY" \ ".../recent-groups?query=6137747116&limit=5" ``` Response: ``` { "status": "ok", "meta": { "query": "DataWizz", "limit": 5 }, "user": { "id": 6137747116, "username": "DataWizz", "display_name": "DataWizz πŸ§™ (Market Stalker)" }, "results": [ { "group_id": -1002282510595, "group_name": "The Market Stalker Community", "last_seen_in_group": "2025-11-04T06:41:29+00:00", "telegram": { "link": "https://t.me/themarketstalker", "link_type": "portal" }, "token": { "address": "0x522Ec96bCed6dc26325120EdF3931d34E417a620", "chain": "ethereum", "symbol": "STLKR" } }, { "group_id": -1003178265398, "group_name": "White Monkey", "last_seen_in_group": "2025-10-30T23:20:55+00:00", "telegram": { "link": "https://t.me/whitemonkeyportal", "link_type": "portal" }, "token": null }, { "group_id": -1002812191154, "group_name": "Marie Rose - SPX Mascot πŸ’ΉπŸ§²πŸŒΉ", "last_seen_in_group": "2025-10-29T22:52:13+00:00", "telegram": { "link": "https://t.me/marieroseethereum", "link_type": "portal" }, "token": { "address": "0xcaa1E525ACb44aeC4e0D17a0e2467AA3Ea7EE3A6", "chain": "ethereum", "symbol": "MARIE" } }, { "group_id": -1003072270133, "group_name": "FRENLY COMMUNITY", "last_seen_in_group": "2025-10-28T08:45:06+00:00", "telegram": { "link": "https://t.me/frenly_portal", "link_type": "portal" }, "token": { "address": "0x26EcB65d997CBFf18FCa447cB85f6aF1175a22B0", "chain": "base", "symbol": "FRENLY" } }, { "group_id": -1002947732445, "group_name": "Rhino - Official Ethereum Macot", "last_seen_in_group": "2025-10-24T22:36:59+00:00", "telegram": { "link": "https://t.me/rhinoeth", "link_type": "portal" }, "token": null } ] } ``` * Sorted by `last_seen_in_group` (desc). If missing, falls back to `first_seen_in_group`. * `token` block is only returned if data stored includes token metadata (`token_address`, `token_chain`, `token_symbol`).
Get Telegram Group by CA **Purpose:** Resolve a token **contract address** to its Telegram group(s). Useful for new launches that haven’t updated listing sites yet. If multiple groups match the same CA, results are sorted by the most recently updated group document (`last_logged_at` desc). Request: ``` GET /group-by-ca?token_address=&limit= Header: x-api-key: YOUR_PARTNER_KEY ``` Example: ``` curl -H "x-api-key: YOUR_PARTNER_KEY" \ ".../group-by-ca?token_address=GFcSfsnVE1jnS6NmSMoYqXWJ1ZgPug9379byxYpump&limit=3" ``` Response: ``` { "status": "ok", "meta": { "token_address": "GFcSfsnVE1jnS6NmSMoYqXWJ1ZgPug9379byxYpump", "limit": 3 }, "results": [ { "group_id": -1003275229931, "group_name": "THE 3 CULT CTO", "members_count": 113, "last_logged_at": "2025-11-04T11:56:21+00:00", "telegram": { "link": "https://t.me/the_3_cult_takeover", "link_type": "public" }, "token": { "address": "GFcSfsnVE1jnS6NmSMoYqXWJ1ZgPug9379byxYpump", "chain": "solana", "symbol": "3", "name": "Three" } }, { "group_id": -1003145003968, "group_name": "THE 3 CULT", "members_count": 1436, "last_logged_at": "2025-10-30T11:23:00+00:00", "telegram": { "link": "https://t.me/entryportal_3", "link_type": "portal" }, "token": { "address": "GFcSfsnVE1jnS6NmSMoYqXWJ1ZgPug9379byxYpump", "chain": "solana", "symbol": "3", "name": "Three" } } ] } ``` * **Multi-match resolution:**\ Results are sorted by `last_logged_at` (most recent first).\ This ensures the most active or recently updated group appears first. * **Link resolution order:**\ `portal_username` β†’ `group_public_username` β†’ `invite_link`.\ If none are found, `link_type` will be `"β€”"`. * **Token block:**\ Includes `address`, `chain`, `symbol`, and `name` to simplify integration with on-chain data tools.
KOLS by CA **Purpose:** Return all **Telegram** and **X (Twitter)** KOLs (Key Opinion Leaders) who mentioned or called a specific token contract. Each platform includes the **timestamp**, **market cap**, **price at post**, and **source link**.\ This endpoint is designed for influencer analysis, narrative tracking, and first-call detection. Request: ``` GET /kols-by-ca?token_address= Header: x-api-key: YOUR_PARTNER_KEY ``` Example: ``` curl -H "x-api-key: YOUR_PARTNER_KEY" \ ".../kols-by-ca?token_address=8fdBKZq7wo9fJbsZEZhq6omCgvKzLt97HY9XaGgqpump" ``` Response: ``` { "status": "ok", "meta": { "token_address": "8fdBKZq7wo9fJbsZEZhq6omCgvKzLt97HY9XaGgqpump", "chain": "sol" }, "token": { "name": "Neo 1x Companion", "symbol": "NEO" }, "telegram_kols": [ { "account": "ranma_calls_solana", "post_url": "https://t.me/Ranma_Calls_Solana/47879", "post_timestamp": "2025-10-28T12:08:13Z", "post_mc": 72937, "post_price": 0.0000729 }, { "account": "shitcoingemsalert", "post_url": "https://t.me/shitcoingemsalert/110433", "post_timestamp": "2025-10-28T12:08:34Z", "post_mc": 77467, "post_price": 0.0000774 }, { "account": "sultanplays", "post_url": "https://t.me/SultanPlays/49102", "post_timestamp": "2025-10-28T12:49:06Z", "post_mc": 481889, "post_price": 0.0004819 }, { "account": "mreduplays", "post_url": "https://t.me/MrEduPlays/4268", "post_timestamp": "2025-10-28T13:09:58Z", "post_mc": 604311, "post_price": 0.0006043 }, { "account": "wizzytrades", "post_url": "https://t.me/WizzyTrades/18662", "post_timestamp": "2025-10-28T13:28:08Z", "post_mc": 1112042, "post_price": 0.001112 }, { "account": "maybachcalls", "post_url": "https://t.me/MaybachCalls/11355", "post_timestamp": "2025-10-28T15:59:22Z", "post_mc": 3114912, "post_price": 0.003115 } ], "x_kols": [ { "account": "owarieth", "post_type": "tweet", "method": "cashtag", "post_url": "https://x.com/OwariETH/status/1983340550209319048", "post_mc": 1363448, "post_price": 0.001363, "post_timestamp": "2025-10-28T12:10:10Z" }, { "account": "pastelalpha", "post_type": "tweet", "method": "cashtag", "post_url": "https://x.com/PastelAlpha/status/1983394635914637489", "post_mc": 3990620, "post_price": 0.00399, "post_timestamp": "2025-10-28T13:58:25Z" }, { "account": "mariuscrypt0", "post_type": "quote", "method": "cashtag", "post_url": "https://x.com/MariusCrypt0/status/1983457468198846914", "post_mc": 2913715, "post_price": 0.002913, "post_timestamp": "2025-10-28T15:41:25Z" }, { "account": "evee0x", "post_type": "quote", "method": "cashtag", "post_url": "https://x.com/evee0x/status/1983502049573536250", "post_mc": 4182195, "post_price": 0.004182, "post_timestamp": "2025-10-28T16:11:54Z" }, { "account": "traderpaw", "post_type": "tweet", "method": "cashtag", "post_url": "https://x.com/traderpaw/status/1984386148450648446", "post_mc": 4223974, "post_price": 0.004224, "post_timestamp": "2025-10-29T08:45:00Z" } ] } ``` #### **Field Reference & Notes** **Shared Fields (Telegram & X)** | Field | Type | Description | | ---------------- | ------ | --------------------------------------------------------------- | | `account` | string | The username or channel handle (Telegram or X). | | `post_url` | string | Direct link to the post or Telegram message. | | `post_timestamp` | string | When the KOL mentioned or posted about the token (ISO8601 UTC). | | `post_mc` | number | Market cap at the time of the post (USD). | | `post_price` | number | Token price at that same time (USD). | **X-Specific Fields** | Field | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------ | | `post_type` | string | Indicates if the post was an original `tweet`, `retweet`, `quote`, or `reply`. | | `method` | string | How the token was referenced β€” e.g., `cashtag` (`$NEO`), `ticker`, or direct `CA` mention. | **Ordering** * Entries are sorted chronologically (earliest β†’ latest) so you can visualize narrative momentum. * For first-mention analysis, look at the earliest `post_timestamp` across both platforms. **Use Cases** * Identify **who called the token first** on either platform. * Track **cross-platform hype correlation** (e.g., Telegram calls preceding X posts). * Detect **organic narrative spreads** vs. coordinated call activity.
Custom endpoints are available upon request and data avaliablity. Pricing varies by requirements. Contact @DataWizz on Telegram to enquire further. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.themarketstalker.com/our-tools/partner-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.