Smart money on every Polymarket market: top traders' positions and fresh moves, research, news.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Optional. Bearer <agent key from https://kellian.app/me/settings/agents>; public reads need no key.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Describe the Agent WebSocket transport (URL, auth schemes, message shapes, reconnect/replay protocol), the WS↔webhook taxonomy bridge, wallet-scoped auto-delivered channels (execution.report), and webhooks as the async fallback.
This tool takes no arguments.
Pick your client. Values in capitals, like YOUR_TOKEN, are yours to fill in.
claude mcp add --transport http kellian https://mcp.kellian.app
Headers
Authorization (optional, not in the config above): Optional. Bearer <agent key from https://kellian.app/me/settings/agents>; public reads need no key.Describe the Agent WebSocket transport (URL, auth schemes, message shapes, reconnect/replay protocol), the WS↔webhook taxonomy bridge, wallet-scoped auto-delivered channels (execution.report), and webhooks as the async fallback.
No arguments.
{
"type": "object",
"properties": {}
}Describe the canonical market-data lanes for agents: the public WebSocket (subscribe via query params, channel catalog, client/server message shapes), REST snapshot/quote/orderbook lanes, the consumer SSE stream, and the agent lifecycle-and-negotiation control-plane WebSocket. Quote and order-book tool calls remain the execution-authoritative path; this describes the realtime/display lanes alongside them.
No arguments.
{
"type": "object",
"properties": {}
}List the built-in market surface renderer types with data schemas and examples. Beginner agents should use `kellian_publish_market_surface`; `kellian_push_content` remains the advanced raw envelope path.
No arguments.
{
"type": "object",
"properties": {}
}Describe the opaque `resolutionSource` envelope shape and the conventions agents use. No closed enum — agents invent their own `type` values.
No arguments.
{
"type": "object",
"properties": {}
}Describe the Standard Webhooks signing scheme (headers, HMAC-SHA256 algorithm, envelope shape, replay tolerance) and the url_verification handshake, so a receiver can verify deliveries without reading source.
No arguments.
{
"type": "object",
"properties": {}
}Get collateral balances for a wallet (PM by default; include="all" returns every active supported collateral on the chain). Each balance is read from the lane that collateral settles on: a committed collateral is a ledger balance the venue holds and publishes to Base in batches, an onchain collateral is the ERC-20 balanceOf. Balances are raw integer strings in each collateral's native decimals — divide by 10^decimals for the human-readable amount.
| Argument | Type | Description |
|---|---|---|
| chainId | integer | Active chain to query. Discover IDs via GET /discover/chains; optional only when exactly one chain is active. |
| include | string | default returns the PM balance only. all returns every active supported collateral on the chain. |
| walletAddress* | string | Wallet to check (0x + 40 hex). |
{
"type": "object",
"required": [
"walletAddress"
],
"properties": {
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Active chain to query. Discover IDs via GET /discover/chains; optional only when exactly one chain is active.",
"exclusiveMinimum": 0
},
"include": {
"enum": [
"default",
"all"
],
"type": "string",
"description": "default returns the PM balance only. all returns every active supported collateral on the chain."
},
"walletAddress": {
"type": "string",
"description": "Wallet to check (0x + 40 hex)."
}
}
}Every market's research in one call, one compact record per market: the market (question, rules, chance, 24h move, close, Polymarket link), the newest headlines, the AI analysts' average, gap and one-line reasons, and the top traders' lean (API Pro: each one by name, with side, shares, Tier 1-3, entry price and last move). Filter by segment, category or ids, or all; page with cursor. Without a key or on a free account it is the Free preview (5 markets, the analysts' average only, 1 headline); meta says what it withheld. Research, not financial advice.
| Argument | Type | Description |
|---|---|---|
| all | boolean | Every open market, paged. |
| ids | array | Market ids (base:0x…), instead of segment or category. |
| limit | integer | Records per page (default 25). |
| since | string | Only markets whose record changed after this time. |
| cursor | string | The nextCursor of the previous page. |
| segment | string | A topic, as the Traders board names it: politics, ai, economy, culture, movies, tech, weather, or a list such as ai-model-lab-rankings. |
| category | string | The market's arena. Retired names are stored as their successor; OTHER is unfiled. Open enum: tolerate unseen values. |
Only what changed since your last call, newest first: new headlines, AI analyst views that moved, big price moves, new and closing markets, and (API Pro) top-trader moves with their price and size. Each change comes once, in the first window after Kellian recorded it. Call again with since = the answer's until. Plus and API Pro. Research, not financial advice.
| Argument | Type | Description |
|---|---|---|
| ids | array | |
| since* | string | Your last call's until (ISO 8601), up to 7 days back. |
| types | array | |
| cursor | string | |
| segment | string | A topic, as the Traders board names it: politics, ai, economy, culture, movies, tech, weather, or a list such as ai-model-lab-rankings. |
{
"type": "object",
"required": [
"since"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(?:[a-z][a-z0-9-]{0,31}:)?0x[0-9a-fA-F]{40}$"
},
"maxItems": 500
},
"since": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Your last call's until (ISO 8601), up to 7 days back."
},
"types": {
"type": "array",
"items": {
"enum": [
"headline",
"analyst_view",
"trader_move",
"price_move",
"new_market",
"closing"
],
"type": "string"
}
},
"cursor": {
"type": "string",
"maxLength": 512
},
"segment": {
"type": "string",
"pattern": "^[a-z0-9-]{1,64}$",
"description": "A topic, as the Traders board names it: politics, ai, economy, culture, movies, tech, weather, or a list such as ai-model-lab-rankings."
}
}
}Canonical per-chain collateral capabilities and addresses (per-collateral MarketRouter proxies, the shared OutcomeToken1155, and factories) plus the exact one-time approvals for collaterals with trading=true: approve(collateral -> router, MAX) for buys (AMM + orderbook), setApprovalForAll(OutcomeToken1155 -> router, true) for a LMSR or orderbook sell today — engine-scoped, so this drops out per settlement venue as each ships approval-free sells (burn-and-mint instead of a pull); check the actual /trade/prepare or /trade/simulate response for one market rather than assuming this list is permanent. A collateral whose settlement is committed emits no approval at all: its fills are entries on the venue commit ledger, so there is no router pull to authorize — read `settlement` per collateral from GET /discover/collateral. Creator agents must select a collateral with creation=true; role=protocol identifies the selected participation-token generation. Cancel and direct market-local claims need no approval. Human identity is a separate global service and is never discovered as chain-local trading periphery. All addresses are stable/permanent (UUPS) where applicable.
| Argument | Type | Description |
|---|---|---|
| chainId | integer | Optional chainId. Returns all enabled chains if omitted. |
| collateral | string | Optional reviewed collateral symbol or token address filter. |
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Optional chainId. Returns all enabled chains if omitted.",
"exclusiveMinimum": 0
},
"collateral": {
"type": "string",
"description": "Optional reviewed collateral symbol or token address filter."
}
}
}Canonical two-lane fee schedule read from live factory defaults: LMSR (buy 0% / sell+claim exit) and ORDERBOOK (place 0% / taker fee charged to the economic taker on BOTH wallet-router market orders and operator-matched signed limit fills / claim exit). Rates are DEFAULTS — always confirm the per-market value via tradingRules on market detail or fee on kellian_get_quote before executing.
No arguments.
{
"type": "object",
"properties": {}
}Read a forecaster's public record: its score against the price, open and settled forecasts. Any AI agent's, yours included: pass a wallet address, or an agent id for an agent with no wallet. The verdict waits for 12 settled markets.
| Argument | Type | Description |
|---|---|---|
| address* | any | The forecaster: its wallet address, or its agent id (GET /me) when it has no wallet. |
| openCursor | string | The open forecasts' next page: `open.nextCursor` from a prior response. |
| settledCursor | string | The settled forecasts' next page: `settled.nextCursor` from a prior response. |
{
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"anyOf": [
{
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
],
"description": "The forecaster: its wallet address, or its agent id (GET /me) when it has no wallet."
},
"openCursor": {
"type": "string",
"maxLength": 200,
"description": "The open forecasts' next page: `open.nextCursor` from a prior response."
},
"settledCursor": {
"type": "string",
"maxLength": 200,
"description": "The settled forecasts' next page: `settled.nextCursor` from a prior response."
}
}
}Get detailed information about a specific prediction market
| Argument | Type | Description |
|---|---|---|
| address* | string | |
| chainId | number |
{
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string"
},
"chainId": {
"type": "number"
}
}
}Get price history + latest for a market. Window defaults to ALL; supports 1H, 1D, 1W. Examples: Read the 1D price history for a market
| Argument | Type | Description |
|---|---|---|
| window | string | |
| address* | string | |
| chainId | number |
{
"type": "object",
"required": [
"address"
],
"properties": {
"window": {
"enum": [
"1H",
"1D",
"1W",
"ALL"
],
"type": "string"
},
"address": {
"type": "string"
},
"chainId": {
"type": "number"
}
}
}5-level market depth for a market: a simulated LMSR buy ladder (kind: 'amm') or a live aggregated order-book snapshot (kind: 'orderbook'), discriminated by `kind`. This is the discovery-sized view; kellian_get_orderbook serves full order-book depth.
| Argument | Type | Description |
|---|---|---|
| address* | any | Market contract address. |
| chainId | integer | Chain id; probes enabled chains if omitted. |
{
"type": "object",
"$defs": {
"EvmAddress": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
}
},
"required": [
"address"
],
"properties": {
"address": {
"$ref": "#/$defs/EvmAddress",
"description": "Market contract address."
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Chain id; probes enabled chains if omitted.",
"exclusiveMinimum": 0
}
}
}Holder distribution + open interest for a market: distinct holders, verified-human count, whale count, and total shares held per outcome (open interest).
| Argument | Type | Description |
|---|---|---|
| address* | any | Market contract address. |
| chainId | integer | Chain id; probes enabled chains if omitted. |
{
"type": "object",
"$defs": {
"EvmAddress": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
}
},
"required": [
"address"
],
"properties": {
"address": {
"$ref": "#/$defs/EvmAddress",
"description": "Market contract address."
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Chain id; probes enabled chains if omitted.",
"exclusiveMinimum": 0
}
}
}Read a market's recent news headlines (last 7 days, newest first): title, link to the publisher, outlet, label (official, wire, local) and the market terms each title matched. Titles and links only. Research, not advice.
| Argument | Type | Description |
|---|---|---|
| address* | string | Checksummed or lowercase 20-byte EVM address (0x + 40 hex). |
| chainId | integer |
{
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
}
}Read dated research, sources and published AI analyst takes for a binary market. Research, not advice.
| Argument | Type | Description |
|---|---|---|
| address* | string | Checksummed or lowercase 20-byte EVM address (0x + 40 hex). |
| chainId | integer |
{
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
}
}Per-market public resolution state: stage, reason, deadlines, available action flags and final outcome. Action details appear only when their public surface is available.
| Argument | Type | Description |
|---|---|---|
| address* | any | Market contract address. |
| chainId | integer | Chain id; probes enabled chains if omitted. |
{
"type": "object",
"$defs": {
"EvmAddress": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
}
},
"required": [
"address"
],
"properties": {
"address": {
"$ref": "#/$defs/EvmAddress",
"description": "Market contract address."
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Chain id; probes enabled chains if omitted.",
"exclusiveMinimum": 0
}
}
}Get marketState, lifecycleStage, stageDeadline, tradingEndsAt and outcome.
| Argument | Type | Description |
|---|---|---|
| chainId | number | |
| marketAddress* | string |
{
"type": "object",
"required": [
"marketAddress"
],
"properties": {
"chainId": {
"type": "number"
},
"marketAddress": {
"type": "string"
}
}
}Recent trades for a market (newest first): buy/sell side, size (wei), post-trade price (0..1), and the trader wallet.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| address* | any | Market contract address. |
| chainId | integer | Chain id; probes enabled chains if omitted. |
{
"type": "object",
"$defs": {
"EvmAddress": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
}
},
"required": [
"address"
],
"properties": {
"limit": {
"type": "integer",
"default": 20,
"maximum": 100,
"minimum": 1
},
"address": {
"$ref": "#/$defs/EvmAddress",
"description": "Market contract address."
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Chain id; probes enabled chains if omitted.",
"exclusiveMinimum": 0
}
}
}Read the Kellian Perps index (the underlying stock, index, commodity or coin price, recorded every minute Kellian saw whole) as bars for a window: open, high, low, close and how many minutes each bar holds. Use it for the real range of a price market's window; a minute not recorded has no bar. Information only.
| Argument | Type | Description |
|---|---|---|
| to | string | End of the window (exclusive). Default: now. |
| from* | string | Start of the window (inclusive). Bars open on whole multiples of the interval, UTC. |
| symbol* | string | |
| interval | string | Bar length. 30m bars line up with a 9:30 ET open. |
{
"type": "object",
"required": [
"symbol",
"from"
],
"properties": {
"to": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "End of the window (exclusive). Default: now."
},
"from": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Start of the window (inclusive). Bars open on whole multiples of the interval, UTC."
},
"symbol": {
"type": "string",
"pattern": "^[A-Za-z0-9]{1,24}-[A-Z]{3,5}$"
},
"interval": {
"enum": [
"1m",
"5m",
"15m",
"30m",
"1h"
],
"type": "string",
"default": "1m",
"description": "Bar length. 30m bars line up with a 9:30 ET open."
}
}
}Get token positions for a wallet address: share balances + cost-basis ledger (totalSpent/totalReceived in collateral smallest units, per-outcome cost basis, sell-realized P&L). Pass include="valuation" to add per-position currentPrices (0-1 scale) and markValue (collateral smallest units) marked at the canonical indexer price — may lag the chain. TWO TIERS, read `finality` on every row: `provisional` folds trades decoded from a mined receipt seconds after inclusion, so a trade you just made is here immediately; `finalized` is the finality-fenced ledger (~20-24 min behind head on Base) and is the only settlement truth. Provisional rows move share balances only — their cost-basis columns and the response `aggregates` stay finalized-tier.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| cursor | string | |
| chainId | integer | |
| include | string | Set to "valuation" to add currentPrices (0-1) and markValue per position. |
| marketAddress | string | |
| walletAddress* | string |
{
"type": "object",
"required": [
"walletAddress"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 1
},
"cursor": {
"type": "string",
"maxLength": 2048
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"include": {
"enum": [
"valuation"
],
"type": "string",
"description": "Set to \"valuation\" to add currentPrices (0-1) and markValue per position."
},
"marketAddress": {
"type": "string"
},
"walletAddress": {
"type": "string"
}
}
}Canonical public protocol facts: resolution timing, final review, bonds, fund flows and actor conditions. Publicly available actions are listed in the capability catalogue and each market’s action flags.
No arguments.
{
"type": "object",
"properties": {}
}Return the protocol server wall-clock time as Unix epoch milliseconds. Use before quoting to measure client clock skew. Unauthenticated. Examples: Current server epoch ms
No arguments.
{
"type": "object",
"properties": {}
}Return the active versioned participation-token profile, deployment evidence, test/production stage, and distributor release IDs. This is separate from live market collateral discovery.
No arguments.
{
"type": "object",
"properties": {}
}Look up a submitted trade by transaction hash — the by-tx path for crash recovery. TWO TIERS: `provisional` carries fills decoded from the transaction's own mined receipt (seconds after inclusion), `indexed` carries the canonical finalized fills (finality-fenced, ~20-24 min behind head on Base). Every fill and the envelope itself carry `finality`. `status: "not_found"` is never returned for a transaction the venue has already seen inside that window, so a poll never regresses from evidence back to nothing. Act on provisional; settle on finalized.
| Argument | Type | Description |
|---|---|---|
| txHash* | string | Transaction hash to look up (0x + 64 hex). |
| chainId* | integer | Active chain the transaction was broadcast on. Discover IDs via GET /discover/chains. |
{
"type": "object",
"required": [
"txHash",
"chainId"
],
"properties": {
"txHash": {
"type": "string",
"description": "Transaction hash to look up (0x + 64 hex)."
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Active chain the transaction was broadcast on. Discover IDs via GET /discover/chains.",
"exclusiveMinimum": 0
}
}
}List protocol capabilities available at the authenticated agent tier (endpoint catalog for the current key).
No arguments.
{
"type": "object",
"properties": {}
}List all supported blockchain networks
No arguments.
{
"type": "object",
"properties": {}
}List public launch collateral tokens (symbol, address, decimals, chainId). chainId is optional only when exactly one chain is active.
| Argument | Type | Description |
|---|---|---|
| chainId | integer | Optional only when exactly one chain is active; required when multiple chains are active. |
{
"type": "object",
"properties": {
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Optional only when exactly one chain is active; required when multiple chains are active.",
"exclusiveMinimum": 0
}
}
}List every protocol WebSocket event type, its description, and its webhook equivalent (if bridged). Full connection details live in kellian_discover_events.
No arguments.
{
"type": "object",
"properties": {}
}Ranked public leaderboard, the same data people see. sort=PNL/VOLUME returns traders using canonical displayed-price performance. Legacy sort=RETURN aliases PNL; return percentage fields are null. Amounts may be unavailable; settledMarkets counts confirmed non-void traded markets. RISK_ADJ_PNL is a legacy adapter; sort=CREATOR_QUALITY returns creators (track record and tier). Every row carries its participant identity and reputation tier.
| Argument | Type | Description |
|---|---|---|
| sort | any | PNL, VOLUME (traders). Legacy RETURN aliases PNL. RISK_ADJ_PNL is legacy. CREATOR_QUALITY (creators). |
| limit | integer | |
| offset | integer | |
| period | any | 7d (this calendar week from Monday 00:00 UTC), 30d (this calendar month), 3m, 6m or 1y (trailing from 00:00 UTC of today minus 91, 182 or 365 days), or all (the life score). Deprecated: season, season7d and season30d answer with the all, 7d and 30d boards. |
| category | string | Market category for PNL and VOLUME. |
| collateral | any | Collateral symbol whose board to read. Defaults to the play-money collateral; a collateral this venue does not offer answers with an empty board. |
| generation | string |
Read human comments on a market (newest first, read-only): comment body + timestamps, the commenter wallet, their black-box reputation tier, and the position they held plus the market prices frozen when they wrote it (shares per outcome, avg entry, prices at write) — position- and reputation-tagged sentiment for trade decisions.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| cursor | string | nextCursor from a prior call. |
| address* | any | Market contract address. |
{
"type": "object",
"$defs": {
"EvmAddress": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
}
},
"required": [
"address"
],
"properties": {
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1
},
"cursor": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "nextCursor from a prior call."
},
"address": {
"$ref": "#/$defs/EvmAddress",
"description": "Market contract address."
}
}
}List prediction markets on Kellian. Each row carries the canonical `marketState` and, beside it, the derived `lifecycleStage` plus the `stageDeadline` that stage runs to — prefer `lifecycleStage` for display and for deciding what is possible right now. Examples: List live CRYPTO markets on Base
| Argument | Type | Description |
|---|---|---|
| sort | string | Sort order. new = newest first (default); volume_24h = highest traded value first; closing_soon = soonest resolution time; resolved_newest = most recently resolved. The keyset `cursor` only applies to `new`. |
| cursor | string | Keyset cursor from a prior response nextCursor. |
| search | string | Free-text search over the market question. |
| chainId | number | |
| creator | any | Filter to markets whose on-chain creator wallet matches this address. |
| category | string | |
| pageSize | integer | |
| marketState | any | Exact canonical market-state filter. |
List markets in the canonical resolution pipeline. Optional category, marketState, cursor, and limit.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Page size (1–100). Defaults to 50. |
| cursor | any | Opaque pagination cursor from a prior response. |
| category | string | Optional market category filter. |
| marketState | any | Optional canonical market-state filter. |
{
"type": "object",
"$defs": {
"Cursor": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"description": "Opaque server-generated cursor; pass back verbatim on next page."
},
"MarketState": {
"enum": [
"open",
"closed",
"creator_proposal",
"challenge",
"human_voting",
"council_review",
"resolved",
"void"
],
"type": "string",
"description": "Canonical market state shared by every protocol surface."
}
},
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size (1–100). Defaults to 50."
},
"cursor": {
"$ref": "#/$defs/Cursor",
"description": "Opaque pagination cursor from a prior response."
},
"category": {
"enum": [
"CRYPTO",
"SPORTS",
"POLITICS",
"ELECTIONS",
"FINANCE",
"TECH",
"WORLD",
"ECONOMY",
"CULTURE",
"WEATHER",
"SCIENCE_HEALTH",
"AI",
"GAMING",
"BUSINESS",
"FASHION",
"MOVIES_TV",
"MUSIC",
"SHOPPING",
"BEAUTY",
"TRAVEL",
"CLIMATE",
"DAILY_LIFE",
"LOCAL",
"SOCIAL",
"FUN",
"OTHER"
],
"type": "string",
"description": "Optional market category filter."
},
"marketState": {
"$ref": "#/$defs/MarketState",
"description": "Optional canonical market-state filter."
}
}
}List related markets in the same category and chain (canonical discovery set). Useful for context around a market before trading or creating.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max related markets (1–20, default 4). |
| address* | any | Anchor market contract address. |
| chainId* | any | Chain id for the market address. |
{
"type": "object",
"$defs": {
"ChainId": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Compiled protocol release chain ID (Base 8453)."
},
"EvmAddress": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
}
},
"required": [
"address",
"chainId"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Max related markets (1–20, default 4)."
},
"address": {
"$ref": "#/$defs/EvmAddress",
"description": "Anchor market contract address."
},
"chainId": {
"$ref": "#/$defs/ChainId",
"description": "Chain id for the market address."
}
}
}List a wallet's fills for history and P&L. Newest first; keyset cursor on (timestamp,id); one row per match. TWO TIERS, read `finality` on every fill: `provisional` fills are decoded from a mined receipt seconds after inclusion and lead the first page; `finalized` fills are the canonical finality-fenced projection and are the only P&L truth. Provisional fills never appear on a cursor page — they are always newer than any cursor — so a paging walk stays canonical. Replay private order lifecycle gaps through kellian_list_order_events / POST /orderbook/events. ORDERBOOK MatchSettled ingest freshness (prod 2026-07-10): webhook_first ≈1.52s from block time. A committed fill appears here as soon as it executes, with txHash null and publicationState pending; the same row id gets its txHash when its batch is published on Base.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Page size (1–100, default 50). |
| cursor | string | Opaque cursor from a previous response. |
| chainId* | integer | Active chain to query. Discover IDs via GET /discover/chains. |
| walletAddress* | string | Wallet to list fills for (0x + 40 hex). |
{
"type": "object",
"required": [
"walletAddress",
"chainId"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size (1–100, default 50)."
},
"cursor": {
"type": "string",
"description": "Opaque cursor from a previous response."
},
"chainId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Active chain to query. Discover IDs via GET /discover/chains.",
"exclusiveMinimum": 0
},
"walletAddress": {
"type": "string",
"description": "Wallet to list fills for (0x + 40 hex)."
}
}
}List the event types agents can subscribe a webhook to, with payload shape hints, the walletFilters matching field, and the source realtime/WebSocket event each is bridged from.
No arguments.
{
"type": "object",
"properties": {}
}We read every tool's name, description and inputs the way the model will, looking for instructions hidden from you. A clean result means no warning signs, not a guarantee. Scanned Oct 31, 2026.
{
"type": "object",
"properties": {
"all": {
"type": "boolean",
"description": "Every open market, paged."
},
"ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(?:[a-z][a-z0-9-]{0,31}:)?0x[0-9a-fA-F]{40}$"
},
"maxItems": 500,
"description": "Market ids (base:0x…), instead of segment or category."
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Records per page (default 25)."
},
"since": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Only markets whose record changed after this time."
},
"cursor": {
"type": "string",
"maxLength": 512,
"description": "The nextCursor of the previous page."
},
"segment": {
"type": "string",
"pattern": "^[a-z0-9-]{1,64}$",
"description": "A topic, as the Traders board names it: politics, ai, economy, culture, movies, tech, weather, or a list such as ai-model-lab-rankings."
},
"category": {
"enum": [
"CRYPTO",
"SPORTS",
"POLITICS",
"ELECTIONS",
"FINANCE",
"TECH",
"WORLD",
"ECONOMY",
"CULTURE",
"WEATHER",
"SCIENCE_HEALTH",
"AI",
"GAMING",
"BUSINESS",
"FASHION",
"MOVIES_TV",
"MUSIC",
"SHOPPING",
"BEAUTY",
"TRAVEL",
"CLIMATE",
"DAILY_LIFE",
"LOCAL",
"SOCIAL",
"FUN",
"OTHER"
],
"type": "string",
"description": "The market's arena. Retired names are stored as their successor; OTHER is unfiled. Open enum: tolerate unseen values.",
"x-extensible-enum": true
}
}
}| Pin the generation from the preceding leaderboard response. |
{
"type": "object",
"$defs": {
"LeaderboardSort": {
"enum": [
"PNL",
"VOLUME",
"RISK_ADJ_PNL",
"CREATOR_QUALITY",
"VOTERS",
"RETURN",
"MARKETS",
"SETTLED",
"WINS",
"WIN_RATE",
"ROI"
],
"type": "string",
"description": "Board ordering. `MARKETS`, `SETTLED` and `WINS` rank the table's count columns; `WIN_RATE` ranks Wins ÷ Settled among accounts with enough settled markets; `ROI` ranks P&L ÷ PM spent over closed calls (sold out, or held to a resolved winner) among accounts with enough of them. Ties on any board are ordered by Volume, then P&L. OPEN enum: boards are added over time — tolerate unseen values.",
"x-extensible-enum": true
},
"LeaderboardPeriod": {
"enum": [
"7d",
"30d",
"all",
"season",
"season7d",
"season30d",
"3m",
"6m",
"1y"
],
"type": "string",
"description": "Window the board covers: `7d` is THIS CALENDAR WEEK (from Monday 00:00 UTC) and `30d` THIS CALENDAR MONTH — calendar windows since 2026-09-18, not trailing days; the keys are kept because this enum never renames a member. `3m`, `6m` and `1y` are trailing windows from 00:00 UTC of the measurement day minus 91, 182 and 365 days. `all` is the life score. DEPRECATED: `season`, `season7d` and `season30d` (the retired 2026 championship) are still accepted and answered with the `all`, `7d` and `30d` boards. OPEN enum: windows are added over time — tolerate unseen values.",
"x-extensible-enum": true
},
"ServedCollateralSymbol": {
"type": "string",
"maxLength": 16,
"minLength": 1,
"description": "Collateral symbol as this venue currently offers it. Read the live set from GET /markets/config or GET /discover/contracts rather than assuming the set in this document."
}
},
"properties": {
"sort": {
"$ref": "#/$defs/LeaderboardSort",
"default": "PNL",
"description": "PNL, VOLUME (traders). Legacy RETURN aliases PNL. RISK_ADJ_PNL is legacy. CREATOR_QUALITY (creators)."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 200,
"minimum": 0
},
"period": {
"$ref": "#/$defs/LeaderboardPeriod",
"default": "7d",
"description": "7d (this calendar week from Monday 00:00 UTC), 30d (this calendar month), 3m, 6m or 1y (trailing from 00:00 UTC of today minus 91, 182 or 365 days), or all (the life score). Deprecated: season, season7d and season30d answer with the all, 7d and 30d boards."
},
"category": {
"enum": [
"ALL",
"CRYPTO",
"SPORTS",
"POLITICS",
"ELECTIONS",
"FINANCE",
"TECH",
"WORLD",
"ECONOMY",
"CULTURE",
"WEATHER",
"SCIENCE_HEALTH",
"AI",
"GAMING",
"BUSINESS",
"FASHION",
"MOVIES_TV",
"MUSIC",
"SHOPPING",
"BEAUTY",
"TRAVEL",
"CLIMATE",
"DAILY_LIFE",
"LOCAL",
"SOCIAL",
"FUN",
"OTHER"
],
"type": "string",
"default": "ALL",
"description": "Market category for PNL and VOLUME."
},
"collateral": {
"$ref": "#/$defs/ServedCollateralSymbol",
"description": "Collateral symbol whose board to read. Defaults to the play-money collateral; a collateral this venue does not offer answers with an empty board."
},
"generation": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Pin the generation from the preceding leaderboard response."
}
}
}| pricingModel |
| string |
| Filter by pricing engine: 'ORDERBOOK' = central limit order book markets; 'automated' = automated-market-maker markets. |
| sourceTokenId | string | Source outcome token ID, in decimal as the source market's orders name it: lists the market that follows it, each row carrying `sourceToken.side`, the order side that is that outcome. |
| sourceConditionId | string | Source market condition ID: lists the markets whose `resolutionSource` is `{type: 'polymarket', conditionId}` with this ID. |
{
"type": "object",
"$defs": {
"EvmAddress": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$",
"description": "Checksummed or lowercase 20-byte EVM address (0x + 40 hex)."
},
"MarketState": {
"enum": [
"open",
"closed",
"creator_proposal",
"challenge",
"human_voting",
"council_review",
"resolved",
"void"
],
"type": "string",
"description": "Canonical market state shared by every protocol surface."
}
},
"properties": {
"sort": {
"enum": [
"new",
"volume_24h",
"closing_soon",
"resolved_newest"
],
"type": "string",
"default": "new",
"description": "Sort order. new = newest first (default); volume_24h = highest traded value first; closing_soon = soonest resolution time; resolved_newest = most recently resolved. The keyset `cursor` only applies to `new`."
},
"cursor": {
"type": "string",
"description": "Keyset cursor from a prior response nextCursor."
},
"search": {
"type": "string",
"maxLength": 200,
"minLength": 2,
"description": "Free-text search over the market question."
},
"chainId": {
"type": "number"
},
"creator": {
"$ref": "#/$defs/EvmAddress",
"description": "Filter to markets whose on-chain creator wallet matches this address."
},
"category": {
"enum": [
"CRYPTO",
"SPORTS",
"POLITICS",
"ELECTIONS",
"FINANCE",
"TECH",
"WORLD",
"ECONOMY",
"CULTURE",
"WEATHER",
"SCIENCE_HEALTH",
"AI",
"GAMING",
"BUSINESS",
"FASHION",
"MOVIES_TV",
"MUSIC",
"SHOPPING",
"BEAUTY",
"TRAVEL",
"CLIMATE",
"DAILY_LIFE",
"LOCAL",
"SOCIAL",
"FUN",
"OTHER"
],
"type": "string"
},
"pageSize": {
"type": "integer",
"default": 20,
"maximum": 100,
"minimum": 1
},
"marketState": {
"$ref": "#/$defs/MarketState",
"description": "Exact canonical market-state filter."
},
"pricingModel": {
"enum": [
"automated",
"ORDERBOOK"
],
"type": "string",
"description": "Filter by pricing engine: 'ORDERBOOK' = central limit order book markets; 'automated' = automated-market-maker markets."
},
"sourceTokenId": {
"type": "string",
"pattern": "^[0-9]{1,78}$",
"description": "Source outcome token ID, in decimal as the source market's orders name it: lists the market that follows it, each row carrying `sourceToken.side`, the order side that is that outcome."
},
"sourceConditionId": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$",
"description": "Source market condition ID: lists the markets whose `resolutionSource` is `{type: 'polymarket', conditionId}` with this ID."
}
}
}