> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex Skills

> Install the Codex skills so your AI coding agent knows the Codex GraphQL API: operations, auth patterns, query templates, and best practices.

The Codex skill gives your AI coding agent structured knowledge of the Codex GraphQL API, including operations, auth patterns, query templates, and best practices, so it can interface with the Codex GraphQL API directly.

Run this command in Terminal to install the skill:

```bash theme={null}
npx skills add Codex-Data/skills -g --yes
```

The skill will be available wherever you use an agent.

> [!NOTE]
>
> If the install fails with "PromptScript does not support global skill installation", name your agent, for example `npx skills add Codex-Data/skills -g -a claude-code`.

### Updating

The install is a local copy and does not update itself. To pick up new versions of the skill, run:

```bash theme={null}
npx skills update -g
```

Re-running the install command also works. Start a new agent session afterwards so it loads the updated skill.

## Teach your agent about Codex

Paste this into your agent so it knows when to reach for Codex:

```text theme={null}
Codex (https://graph.codex.io/graphql) is a GraphQL API for real-time on-chain
data: token prices, OHLCV charts, token screening, trades, wallet PnL, holders,
launchpad streams, and prediction markets across 80+ networks. When the user
needs blockchain or prediction market data, install the Codex skill
(`npx skills add Codex-Data/skills -g --yes`) to get operation maps, auth
patterns, and query templates. For anything the skill doesn't cover, fetch the
documentation index at https://docs.codex.io/llms.txt before exploring further.
```

## Codex Skills vs Docs MCP

The [Codex Docs MCP](https://docs.codex.io/agents/docs-mcp.md) lets your AI *search* the documentation. The skill gives it *direct knowledge* of the API surface so it can generate queries immediately.

| | Codex Skills | Codex Docs MCP |
| - | - | - |
| **How it works** | Preloaded API knowledge — operations, auth, templates | Searches docs on demand via MCP protocol |
| **Best for** | Generating runnable queries fast | Looking up specific fields, types, or guides |
| **Needs network?** | Works offline to write queries. But it can't interface with the API without a connection. | Yes — queries the MCP server |

Use both together for the best experience: the skill handles query generation and the MCP fills in details when needed.

## What's included

The skill packages everything an AI agent needs to work with the Codex API:

* **Operation map**: Which endpoint to use for each task (pricing, charting, token discovery, events, wallets, holders, launchpads)
* **Auth patterns**: [API key](https://dashboard.codex.io/dashboard), and [MPP](https://docs.codex.io/agents/mpp.md) payment flows with header formats
* **Query templates**: Ready-to-use GraphQL for common operations like `filterTokens`, `getTokenPrices`, `getBars`
* **Endpoint playbook**: Decision guide for choosing the right operation based on intent — see [what your agent can do](#what-your-agent-can-do) below
* **Session preflight**: Required `getNetworks` call to validate network IDs before making requests

The skill covers all of the [Queries](https://docs.codex.io/concepts/queries.md) in the Codex API, across token discovery, pricing, charts, events, wallets, launchpads, and more. See the [GraphQL Reference](https://docs.codex.io/api-reference/introduction.md) for all available operations.

## What your agent can do

These are the capabilities the skill's endpoint playbook maps user intent onto. Each card links to the reference page for its primary operation.

### Discover

> [card] [Trending Tokens](https://docs.codex.io/api-reference/queries/filtertokens.md)
>
> Rank tokens by trending score, volume, or any of 100+ on-chain signals — live via `onFilterTokensUpdated`.

> [card] [Token Screener](https://docs.codex.io/api-reference/queries/filtertokens.md)
>
> Search by phrase and filter on liquidity, market cap, holder behavior, and launchpad lifecycle.

> [card] [New Launchpad Tokens](https://docs.codex.io/api-reference/subscriptions/onlaunchpadtokeneventbatch.md)
>
> Stream newly created launchpad tokens in real time, from creation through graduation.

> [card] [Top Wallets for a Token](https://docs.codex.io/api-reference/queries/filtertokenwallets.md)
>
> Find the most profitable wallets trading a token, with PnL stats and labels.

### Prices & Charts

> [card] [Token Prices](https://docs.codex.io/api-reference/queries/gettokenprices.md)
>
> Current or historical prices for up to 25 tokens per request — live via `onPricesUpdated`.

> [card] [Pair Charts](https://docs.codex.io/api-reference/queries/getbars.md)
>
> OHLCV candles for any pair at resolutions from 1 second to 1 week — live via `onBarsUpdated`.

> [card] [Token Charts](https://docs.codex.io/api-reference/queries/gettokenbars.md)
>
> Token-level candles aggregated across top liquidity pairs — live via `onTokenBarsUpdated`.

> [card] [Pair Stats](https://docs.codex.io/api-reference/queries/pairmetadata.md)
>
> Price, liquidity, volume, and windowed stats for a trading pair — live via `onPairMetadataUpdated`.

### Trades & Events

> [card] [Token Trades](https://docs.codex.io/api-reference/queries/gettokenevents.md)
>
> Every buy and sell for a token — live via `onTokenEventsCreated`.

> [card] [Wallet Trades](https://docs.codex.io/api-reference/queries/gettokeneventsformaker.md)
>
> All trades from a specific wallet — live via `onEventsCreatedByMaker`.

### Wallets & Holders

> [card] [Wallet PnL & Performance](https://docs.codex.io/api-reference/queries/detailedwalletstats.md)
>
> Profit and loss, volume, and performance over time for any wallet, charted via `walletChart`.

> [card] [Holder List](https://docs.codex.io/api-reference/queries/holders.md)
>
> Token holders ordered by balance — live via `onHoldersUpdated`.

> [card] [Holder Concentration](https://docs.codex.io/api-reference/queries/top10holderspercent.md)
>
> Percent of supply held by the top 10 wallets — a quick rug-risk signal.

### Prediction Markets

> [card] [Trending Prediction Events](https://docs.codex.io/api-reference/queries/filterpredictionevents.md)
>
> Discover and search Polymarket and Kalshi events by trending score, volume, or category.

> [card] [Market Odds](https://docs.codex.io/api-reference/queries/filterpredictionmarkets.md)
>
> Filter markets and sort by implied probability, open interest, or competitiveness.

> [card] [Prediction Charts](https://docs.codex.io/api-reference/queries/predictionmarketbars.md)
>
> Per-outcome OHLC price, volume, and open interest — compare up to 10 markets in one request.

> [card] [Trader Leaderboard](https://docs.codex.io/api-reference/queries/filterpredictiontraders.md)
>
> Rank prediction traders by profit, win rate, and volume.

> [card] [Trader Profile & Positions](https://docs.codex.io/api-reference/queries/detailedpredictiontraderstats.md)
>
> All-time and windowed stats plus open positions for any prediction trader.

> [card] [Prediction Trades](https://docs.codex.io/api-reference/queries/predictiontrades.md)
>
> Trade feed filterable by event, market, or trader.

## How it works

Once installed, your AI agent uses the skill to:

1. **Pick the right operation**: Maps intent (e.g. "get trending tokens") to the correct GraphQL query (`filterTokens`)
2. **Set the correct auth**: Chooses between API key headers and MPP payment flow based on context.
   * If the user provides an API key, it will use that
   * If the user doesn't provide an API key, it will try to use the MPP payment flow
3. **Generate valid GraphQL**: Uses templates to produce runnable queries with proper variables and selection sets
4. **Follow best practices**: Validates network IDs first, keeps selection sets minimal, batches subscriptions

## Authentication

The skill will check to see if you have provided an [API key](https://dashboard.codex.io/dashboard). If you have, it will use that.

If you haven't, it will try to use the MPP payment flow.

See the [MPP documentation](https://docs.codex.io/agents/mpp.md) for more information on how to set up MPP.

## Examples

### Example 1: Get a list of dog tokens

Ask your agent:

> "Get me a list of 20 dog tokens."

It will then check to see if you have provided an API key.

Assuming you have enabled [MPP](https://docs.codex.io/agents/mpp.md), the skill will guide the agent to run it to generate a request like the one below.

> [!NOTE]
>
> To do that, your agent will likely read numerous .md files in the skills directory to understand how to use the skill and perform the query.

```bash theme={null}
tempo request -t -X POST \
  -H 'X-Codex-Payment: mpp' \
  --json '{"query":"query FilterTokens($phrase: String, $rankings: [TokenRanking], $limit: Int) { filterTokens(phrase: $phrase, rankings: $rankings, limit: $limit) { results { buyVolume24 sellVolume24 circulatingMarketCap liquidity txnCount24 token { info { address name symbol networkId imageThumbUrl } } } } }","variables":{"phrase":"dog","rankings":[{"attribute":"txnCount24","direction":"DESC"}],"limit":20}}' \
  https://graph.codex.io/graphql 2>&1
```

And it will return a response like this:

> [accordion] Example Response
>
> ```bash theme={null}
>   data:
>     filterTokens:
>       results[20]:
>         - buyVolume24: "86690"
>           sellVolume24: "86570"
>           circulatingMarketCap: "1717"
>           liquidity: "1683"
>           txnCount24: 47348
>           token:
>             info:
>               address: TOKEN_ADDRESS_1
>               name: em@doge.gov
>               symbol: dogemail
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_1_thumb.png"
>         - buyVolume24: "254789"
>           sellVolume24: "243302"
>           circulatingMarketCap: "5689"
>           liquidity: "0"
>           txnCount24: 16042
>           token:
>             info:
>               address: TOKEN_ADDRESS_2
>               name: Dog Eat Dog
>               symbol: Dash
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_2_thumb_cdbe60390207.png"
>         - buyVolume24: "538396"
>           sellVolume24: "524541"
>           circulatingMarketCap: "981"
>           liquidity: "0"
>           txnCount24: 16041
>           token:
>             info:
>               address: TOKEN_ADDRESS_3
>               name: Dog's POV
>               symbol: POV
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_3_thumb_efdd1321689b.png"
>         - buyVolume24: "248973"
>           sellVolume24: "244819"
>           circulatingMarketCap: "16855"
>           liquidity: "0"
>           txnCount24: 13800
>           token:
>             info:
>               address: TOKEN_ADDRESS_4
>               name: Dog's POV
>               symbol: POV
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_4_thumb_efdd1321689b.png"
>         - buyVolume24: "228547"
>           sellVolume24: "220835"
>           circulatingMarketCap: "20608"
>           liquidity: "0"
>           txnCount24: 10239
>           token:
>             info:
>               address: TOKEN_ADDRESS_5
>               name: Advice Dog
>               symbol: DOG
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_5_thumb_97699a101f77.png"
>         - buyVolume24: "235342"
>           sellVolume24: "224658"
>           circulatingMarketCap: "6297"
>           liquidity: "0"
>           txnCount24: 10009
>           token:
>             info:
>               address: TOKEN_ADDRESS_6
>               name: DOGE
>               symbol: DOGE
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_6_thumb_17476c0fd6b9.png"
>         - buyVolume24: "141184"
>           sellVolume24: "123372"
>           circulatingMarketCap: "21912"
>           liquidity: "0"
>           txnCount24: 9844
>           token:
>             info:
>               address: TOKEN_ADDRESS_7
>               name: DOGE
>               symbol: DOGE
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_7_thumb_17476c0fd6b9.png"
>         - buyVolume24: "155536"
>           sellVolume24: "138576"
>           circulatingMarketCap: "3398"
>           liquidity: "0"
>           txnCount24: 8840
>           token:
>             info:
>               address: TOKEN_ADDRESS_8
>               name: DOGE
>               symbol: DOGE
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_8_thumb_17476c0fd6b9.png"
>         - buyVolume24: "147565"
>           sellVolume24: "134144"
>           circulatingMarketCap: "4791"
>           liquidity: "0"
>           txnCount24: 7769
>           token:
>             info:
>               address: TOKEN_ADDRESS_9
>               name: DOGE
>               symbol: DOGE
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_9_thumb_17476c0fd6b9.png"
>         - buyVolume24: "55973"
>           sellVolume24: "56836"
>           circulatingMarketCap: "25633"
>           liquidity: "6669"
>           txnCount24: 7008
>           token:
>             info:
>               address: TOKEN_ADDRESS_10
>               name: Dark Doge
>               symbol: DarkDoge
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_10_1732216636_thumb.png"
>         - buyVolume24: "862735"
>           sellVolume24: "799848"
>           circulatingMarketCap: "57214767"
>           liquidity: "4969132"
>           txnCount24: 6225
>           token:
>             info:
>               address: TOKEN_ADDRESS_11
>               name: cat in a dogs world
>               symbol: MEW
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_11_thumb_11d957ce-c1ae-4d0a-a460-7b923f40fb76.png"
>         - buyVolume24: "69913"
>           sellVolume24: "66098"
>           circulatingMarketCap: "117"
>           liquidity: "0"
>           txnCount24: 5781
>           token:
>             info:
>               address: TOKEN_ADDRESS_12
>               name: Dog's POV
>               symbol: POV
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_12_thumb_efdd1321689b.png"
>         - buyVolume24: "58304"
>           sellVolume24: "54016"
>           circulatingMarketCap: "1695"
>           liquidity: "0"
>           txnCount24: 5622
>           token:
>             info:
>               address: TOKEN_ADDRESS_13
>               name: DOGE
>               symbol: DOGE
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_13_thumb_17476c0fd6b9.png"
>         - buyVolume24: "93700"
>           sellVolume24: "89610"
>           circulatingMarketCap: "16680"
>           liquidity: "0"
>           txnCount24: 5122
>           token:
>             info:
>               address: TOKEN_ADDRESS_14
>               name: Dog Eat Dog
>               symbol: Dash
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_14_thumb_cdbe60390207.png"
>         - buyVolume24: "78378"
>           sellVolume24: "154758"
>           circulatingMarketCap: "72139728"
>           liquidity: "4366889"
>           txnCount24: 4911
>           token:
>             info:
>               address: "TOKEN_ADDRESS_15"
>               name: Baby Doge Coin
>               symbol: BabyDoge
>               networkId: 56
>               imageThumbUrl: "https://token-media.defined.fi/56_TOKEN_ADDRESS_15_thumb_bac0895ae46f.png"
>         - buyVolume24: "255927"
>           sellVolume24: "257210"
>           circulatingMarketCap: "1878610"
>           liquidity: "80782"
>           txnCount24: 4781
>           token:
>             info:
>               address: TOKEN_ADDRESS_16
>               name: what the dog doing?
>               symbol: 我的刀盾
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_16_thumb_63b436b284e0.png"
>         - buyVolume24: "58891"
>           sellVolume24: "52566"
>           circulatingMarketCap: "1991"
>           liquidity: "0"
>           txnCount24: 4630
>           token:
>             info:
>               address: TOKEN_ADDRESS_17
>               name: DOGE
>               symbol: DOGE
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_17_thumb_17476c0fd6b9.png"
>         - buyVolume24: "426486"
>           sellVolume24: "436956"
>           circulatingMarketCap: "1426107"
>           liquidity: "83658"
>           txnCount24: 4186
>           token:
>             info:
>               address: "TOKEN_ADDRESS_18"
>               name: what the dog doing?
>               symbol: 我的刀盾
>               networkId: 56
>               imageThumbUrl: "https://token-media.defined.fi/56_TOKEN_ADDRESS_18_thumb_b73c93973cee.png"
>         - buyVolume24: "32557"
>           sellVolume24: "27629"
>           circulatingMarketCap: "11200"
>           liquidity: "0"
>           txnCount24: 3696
>           token:
>             info:
>               address: TOKEN_ADDRESS_19
>               name: DOGE
>               symbol: DOGE
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_19_thumb_17476c0fd6b9.png"
>         - buyVolume24: "42281"
>           sellVolume24: "36618"
>           circulatingMarketCap: "2278"
>           liquidity: "0"
>           txnCount24: 3523
>           token:
>             info:
>               address: TOKEN_ADDRESS_20
>               name: DOGE
>               symbol: DOGE
>               networkId: 1399811149
>               imageThumbUrl: "https://token-media.defined.fi/1399811149_TOKEN_ADDRESS_20_thumb_17476c0fd6b9.png"
> ```

And then it will likely summarize the results for you, like this:

![Codex Skills Summary](https://mintcdn.com/codex-dfdf2708/L2P37povXDt2tEJI/images/agents/dog-coins.png?fit=max\&auto=format\&n=L2P37povXDt2tEJI\&q=85\&s=810b60017c5e92b3f28af7f89fa8571b)

> [!NOTE]
>
> This is not an endorsement of any of these tokens, and they may be scams or rugs. Please do your own research before investing. You can also ask your agent to filter out scams.

### Example 2: Get trending prediction events

Ask your agent:

> "Get me a list of 15 trending prediction events."

It will then check to see if you have provided an API key. Assuming you have one, your agent will likely do a query like the following after doing some research on the best endpoint to use:

> [!NOTE]
>
> To do that, your agent will likely read numerous .md files in the skills directory to understand how to use the skill and perform the query.

```bash theme={null}
tempo request -t -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: $CODEX_API_KEY" \
  "query": "query TrendingPolymarketEvents { filterPredictionEvents( filters: { protocol: [POLYMARKET], status: [OPEN] } rankings: [{ attribute: trendingScore24h, direction: DESC }] limit: 15 ) { count results { id event { question imageThumbUrl venueUrl closesAt } marketCount categories trendingScore24h volumeUsd24h volumeChange24h trades24h uniqueTraders24h liquidityUsd openInterestUsd } } }"
  https://graph.codex.io/graphql 2>&1
```

Which will return something like:

> [accordion] Example Response
>
> ```
> data:
>   filterPredictionEvents:
>     count: 15
>     results[15]:
>       - id: "277737:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: St. Thomas (MN) Tommies vs. Seattle Redhawks
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/ncaa-c14995df96.png"
>           venueUrl: "https://polymarket.com/event/cbb-stmn-sea-2026-03-17"
>           closesAt: 1773799200
>         marketCount: 11
>         categories[4]: sports,basketball,ncaa,"ncaa-basketball"
>         trendingScore24h: 0.6837012928887231
>         volumeUsd24h: "181298"
>         volumeChange24h: 6713.740740740741
>         trades24h: 2341
>         uniqueTraders24h: 586
>         liquidityUsd: "120574"
>         openInterestUsd: "0"
>       - id: "277736:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Stephen F. Austin Lumberjacks vs. Tulsa Golden Hurricane
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/ncaa-c14995df96.png"
>           venueUrl: "https://polymarket.com/event/cbb-sfaus-tulsa-2026-03-17"
>           closesAt: 1773795600
>         marketCount: 28
>         categories[4]: sports,basketball,ncaa,"ncaa-basketball"
>         trendingScore24h: 0.6569632870076872
>         volumeUsd24h: "158297"
>         volumeChange24h: 4521.771428571428
>         trades24h: 2490
>         uniqueTraders24h: 573
>         liquidityUsd: "368105"
>         openInterestUsd: "3286"
>       - id: "261113:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Spurs vs. Kings
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png"
>           venueUrl: "https://polymarket.com/event/nba-sas-sac-2026-03-17"
>           closesAt: 1773799200
>         marketCount: 44
>         categories[3]: sports,basketball,nba
>         trendingScore24h: 0.6558132120870599
>         volumeUsd24h: "2463613"
>         volumeChange24h: 70.07327698121917
>         trades24h: 7939
>         uniqueTraders24h: 2482
>         liquidityUsd: "1326924"
>         openInterestUsd: "1189928"
>       - id: "261105:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Cavaliers vs. Bucks
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png"
>           venueUrl: "https://polymarket.com/event/nba-cle-mil-2026-03-17"
>           closesAt: 1773792000
>         marketCount: 49
>         categories[3]: sports,basketball,nba
>         trendingScore24h: 0.6531924741031485
>         volumeUsd24h: "1637344"
>         volumeChange24h: 51.81073409882596
>         trades24h: 11253
>         uniqueTraders24h: 2841
>         liquidityUsd: "3100641"
>         openInterestUsd: "767392"
>       - id: "261108:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Suns vs. Timberwolves
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png"
>           venueUrl: "https://polymarket.com/event/nba-phx-min-2026-03-17"
>           closesAt: 1773792000
>         marketCount: 41
>         categories[3]: sports,basketball,nba
>         trendingScore24h: 0.6520415029070732
>         volumeUsd24h: "2171473"
>         volumeChange24h: 50.22969306627032
>         trades24h: 12262
>         uniqueTraders24h: 3691
>         liquidityUsd: "2102725"
>         openInterestUsd: "1137956"
>       - id: "261111:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: 76ers vs. Nuggets
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png"
>           venueUrl: "https://polymarket.com/event/nba-phi-den-2026-03-17"
>           closesAt: 1773799200
>         marketCount: 38
>         categories[3]: sports,basketball,nba
>         trendingScore24h: 0.6506343548772099
>         volumeUsd24h: "1572446"
>         volumeChange24h: 45.406740644552
>         trades24h: 7965
>         uniqueTraders24h: 3181
>         liquidityUsd: "664400"
>         openInterestUsd: "233725"
>       - id: "261095:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Thunder vs. Magic
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png"
>           venueUrl: "https://polymarket.com/event/nba-okc-orl-2026-03-17"
>           closesAt: 1773788400
>         marketCount: 66
>         categories[3]: sports,basketball,nba
>         trendingScore24h: 0.6345789924271994
>         volumeUsd24h: "1863262"
>         volumeChange24h: 39.602789278709956
>         trades24h: 11315
>         uniqueTraders24h: 3409
>         liquidityUsd: "4785105"
>         openInterestUsd: "505290"
>       - id: "261103:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Pacers vs. Knicks
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png"
>           venueUrl: "https://polymarket.com/event/nba-ind-nyk-2026-03-17"
>           closesAt: 1773790200
>         marketCount: 46
>         categories[3]: sports,basketball,nba
>         trendingScore24h: 0.6298383903051978
>         volumeUsd24h: "1802121"
>         volumeChange24h: 29.377092288242732
>         trades24h: 9869
>         uniqueTraders24h: 2573
>         liquidityUsd: "3417311"
>         openInterestUsd: "1949522"
>       - id: "274567:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: "Bitcoin Up or Down - March 17, 10PM ET"
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/BTC+fullsize.png"
>           venueUrl: "https://polymarket.com/event/bitcoin-up-or-down-march-17-2026-10pm-et"
>           closesAt: 1773802800
>         marketCount: 1
>         categories[2]: crypto,bitcoin
>         trendingScore24h: 0.6275458343403106
>         volumeUsd24h: "42623"
>         volumeChange24h: 14206.666666666666
>         trades24h: 1585
>         uniqueTraders24h: 520
>         liquidityUsd: "1532928"
>         openInterestUsd: "0"
>       - id: "277741:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: UNLV Runnin' Rebels vs. UC Irvine Anteaters
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/ncaa-c14995df96.png"
>           venueUrl: "https://polymarket.com/event/cbb-unlv-ucirv-2026-03-17"
>           closesAt: 1773802800
>         marketCount: 7
>         categories[4]: sports,basketball,ncaa,"ncaa-basketball"
>         trendingScore24h: 0.6272259874963405
>         volumeUsd24h: "130023"
>         volumeChange24h: 1339.4432989690722
>         trades24h: 1460
>         uniqueTraders24h: 481
>         liquidityUsd: "366579"
>         openInterestUsd: "0"
>       - id: "261099:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Pistons vs. Wizards
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png"
>           venueUrl: "https://polymarket.com/event/nba-det-was-2026-03-17"
>           closesAt: 1773788400
>         marketCount: 58
>         categories[3]: sports,basketball,nba
>         trendingScore24h: 0.6228045267765248
>         volumeUsd24h: "2649383"
>         volumeChange24h: 28.175335043883315
>         trades24h: 9978
>         uniqueTraders24h: 4150
>         liquidityUsd: "340066"
>         openInterestUsd: "0"
>       - id: "277734:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Davidson Wildcats vs. Oklahoma State Cowboys
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/ncaa-c14995df96.png"
>           venueUrl: "https://polymarket.com/event/cbb-david-okst-2026-03-17"
>           closesAt: 1773792000
>         marketCount: 28
>         categories[4]: sports,basketball,ncaa,"ncaa-basketball"
>         trendingScore24h: 0.6176923145958093
>         volumeUsd24h: "96620"
>         volumeChange24h: 3715.153846153846
>         trades24h: 2040
>         uniqueTraders24h: 501
>         liquidityUsd: "614125"
>         openInterestUsd: "49247"
>       - id: "274163:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Howard Bison vs. UMBC Retrievers
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/ncaa-c14995df96.png"
>           venueUrl: "https://polymarket.com/event/cbb-howrd-umbc-2026-03-17"
>           closesAt: 1773720000
>         marketCount: 38
>         categories[4]: sports,basketball,ncaa,"ncaa-basketball"
>         trendingScore24h: 0.6170935642058901
>         volumeUsd24h: "1426563"
>         volumeChange24h: 24.053793466807164
>         trades24h: 5767
>         uniqueTraders24h: 1534
>         liquidityUsd: "4063303"
>         openInterestUsd: "596363"
>       - id: "274161:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: North Carolina State Wolfpack vs. Texas Longhorns
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/ncaa-c14995df96.png"
>           venueUrl: "https://polymarket.com/event/cbb-ncst-tx-2026-03-17"
>           closesAt: 1773720000
>         marketCount: 29
>         categories[4]: sports,basketball,ncaa,"ncaa-basketball"
>         trendingScore24h: 0.6121302865183799
>         volumeUsd24h: "1689272"
>         volumeChange24h: 18.34775686912302
>         trades24h: 6325
>         uniqueTraders24h: 1536
>         liquidityUsd: "110528"
>         openInterestUsd: "1222406"
>       - id: "261090:Polymarket:0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e:137"
>         event:
>           question: Heat vs. Hornets
>           imageThumbUrl: "https://polymarket-upload.s3.us-east-2.amazonaws.com/super+cool+basketball+in+red+and+blue+wow.png"
>           venueUrl: "https://polymarket.com/event/nba-mia-cha-2026-03-17"
>           closesAt: 1773788400
>         marketCount: 71
>         categories[3]: sports,basketball,nba
>         trendingScore24h: 0.5997105846532764
>         volumeUsd24h: "2088120"
>         volumeChange24h: 11.864060324540112
>         trades24h: 12337
>         uniqueTraders24h: 3752
>         liquidityUsd: "3541167"
>         openInterestUsd: "1107697"
> ```

And then it will likely summarize the results for you, like this:

![Codex Skills Prediction Events](https://mintcdn.com/codex-dfdf2708/L2P37povXDt2tEJI/images/agents/prediction-events-skill.png?fit=max\&auto=format\&n=L2P37povXDt2tEJI\&q=85\&s=e25e0378b957be22ff2059e37f10677b)

### Example 3: Find the top traders of a token

Ask your agent:

> "Who are the most profitable wallets trading WETH on Ethereum?"

The skill maps this intent to `filterTokenWallets` and generates a query like:

```graphql theme={null}
query FilterTokenWallets($input: FilterTokenWalletsInput!) {
  filterTokenWallets(input: $input) {
    results {
      address
      realizedProfitUsd1d
      realizedProfitPercentage1d
      buys1d
      sells1d
      labels
    }
  }
}
```

```json theme={null}
{
  "input": {
    "tokenIds": ["0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1"],
    "limit": 25
  }
}
```

### Example 4: Check holder concentration

Ask your agent:

> "How concentrated is the holder base of this token? Is it a rug risk?"

The skill maps this to the `holders` query, which includes top-10 concentration alongside the holder list:

```graphql theme={null}
query Holders($input: HoldersInput!) {
  holders(input: $input) {
    count
    top10HoldersPercent
    items {
      address
      shiftedBalance
      balanceUsd
    }
  }
}
```

Your agent can then interpret the result — a high `top10HoldersPercent` on a low-liquidity token is a common rug signal.

### Example 5: Stream live prices

Ask your agent:

> "Stream the live price of SOL into my app."

For real-time intents the skill reaches for subscriptions instead of polling, and generates a `graphql-ws` client like:

```typescript theme={null}
import { createClient } from "graphql-ws";

const client = createClient({
  url: "wss://graph.codex.io/graphql",
  connectionParams: {
    Authorization: process.env.CODEX_API_KEY!,
  },
});

const unsubscribe = client.subscribe(
  {
    query: `
      subscription OnPriceUpdated($address: String!, $networkId: Int!) {
        onPriceUpdated(address: $address, networkId: $networkId) {
          address
          networkId
          priceUsd
          timestamp
        }
      }
    `,
    variables: {
      address: "So11111111111111111111111111111111111111112",
      networkId: 1399811149,
    },
  },
  {
    next: (msg) => console.log(msg),
    error: (err) => console.error(err),
    complete: () => console.log("done"),
  }
);
```

To stream many tokens at once, the skill batches them into a single `onPricesUpdated` subscription rather than opening one connection per token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.