Grandtake API

Programmatic access to prediction markets. Read real-time data, execute trades, and build powerful applications on Grandtake.

Get API Key

99.9% uptime·<100ms response·REST + WebSocket·Real-time data

Overview

The Grandtake API gives you programmatic access to prediction markets - read real-time market data, execute trades, and build powerful applications on top of Grandtake. Everything the app does, you can do through the API.

Market API

Public market data - prices, order books, search and history.

https://api.grandtake.com/v1

Trading API

Authenticated - place orders, manage positions and portfolio.

https://api.grandtake.com/v1 · Bearer

Getting Started / Introduction

Introduction

Grandtake exposes two complementary surfaces over the same base URL:

1. Market API - https://api.grandtake.com/v1. Public endpoints for market data, prices, order books and search. Great for dashboards and research tools.

2. Trading API - https://api.grandtake.com/v1 (authenticated). Place orders, manage positions and read your portfolio. Requires a Bearer API key.

All responses are JSON. All timestamps are ISO 8601 (UTC). All prices are probabilities in the range 0-1.

Getting Started / Quick Start

Quick Start

Create an account at grandtake.com.
Generate a key in Settings → API Keys → Generate Key.
Make your first request with the key in the Authorization header.

bash

curl https://api.grandtake.com/v1/markets \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response looks like this:

json

{
  "markets": [
    {
      "id": "mkt_001",
      "question": "Will Arsenal win the Premier League?",
      "category": "football",
      "subcategory": "epl",
      "yesPrice": 0.34,
      "noPrice": 0.66,
      "volume": 125000,
      "endDate": "2025-05-25T23:59:59Z",
      "status": "open"
    }
  ],
  "total": 51,
  "page": 1
}

Getting Started / API Keys

API Keys

API keys authenticate every request. Generate, name and revoke keys from Settings → API Keys. Each key inherits your account’s KYC tier and rate-limit plan.

Treat keys like passwords - never commit them or expose them in client-side code.
Use a separate key per integration so you can revoke one without breaking the others.
Rotate keys regularly. Revoking a key takes effect immediately.

Getting Started / Environments

Environments

Grandtake offers two environments. Generate keys for each independently.

Environment	Base URL	Settlement
production	api.grandtake.com/v1	Base · live USDC
sandbox	sandbox.grandtake.com/v1	Base Sepolia · test USDC

Authentication

The Grandtake API uses Bearer token authentication. Pass your API key in the Authorization header on every request:

http

Authorization: Bearer YOUR_API_KEY

From JavaScript:

javascript

fetch('https://api.grandtake.com/v1/portfolio/positions', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})

⚠️ Keep your key secret. Never expose it in browser code or public repos, and rotate keys regularly. A leaked key can read your portfolio and place trades.

Rate Limits

Rate limits are applied per API key. Limits scale with your plan:

Tier	Requests / min	WebSocket connections
Free	60	1
Pro	600	5
Enterprise	Unlimited	Unlimited

Every response includes your current limit state in the headers:

http

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1718000000

REST · Markets / List markets

List markets

GET/v1/markets

Returns a paginated list of markets. Filter by category, subcategory and status, and sort by volume or close date.

Parameters

Parameter	Type	Required	Description
category	string	No	e.g. football, basketball, politics, crypto
subcategory	string	No	e.g. epl, la-liga, nba
status	string	No	open · resolving · resolved
sort	string	No	volume · closing · newest
page	integer	No	Page number, default 1
limit	integer	No	Results per page, max 100

Request

bash

curl "https://api.grandtake.com/v1/markets?category=football&status=open" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "markets": [
    {
      "id": "mkt_001",
      "question": "Will Arsenal win the Premier League?",
      "category": "football",
      "subcategory": "epl",
      "yesPrice": 0.34,
      "noPrice": 0.66,
      "volume": 125000,
      "endDate": "2025-05-25T23:59:59Z",
      "status": "open"
    }
  ],
  "total": 51,
  "page": 1
}

REST · Markets / Get market

Get market

GET/v1/markets/:id

Retrieve a single market by its id, including live prices and 24h volume.

Parameters

Parameter	Type	Required	Description
id	string (path)	Yes	Market id, e.g. mkt_001

Request

bash

curl "https://api.grandtake.com/v1/markets/mkt_001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "id": "mkt_001",
  "question": "Will Arsenal win the Premier League?",
  "category": "football",
  "subcategory": "epl",
  "yesPrice": 0.34,
  "noPrice": 0.66,
  "volume": 125000,
  "liquidity": 48200,
  "endDate": "2025-05-25T23:59:59Z",
  "status": "open"
}

REST · Markets / Price history

Price history

GET/v1/markets/:id/prices

Time series of YES price for a market. Use interval to control resolution.

Parameters

Parameter	Type	Required	Description
id	string (path)	Yes	Market id
interval	string	No	1m · 1h · 1d (default 1h)
from	ISO 8601	No	Start timestamp
to	ISO 8601	No	End timestamp

Request

bash

curl "https://api.grandtake.com/v1/markets/mkt_001/prices?interval=1h" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "marketId": "mkt_001",
  "interval": "1h",
  "points": [
    { "t": "2025-05-01T10:00:00Z", "yesPrice": 0.31 },
    { "t": "2025-05-01T11:00:00Z", "yesPrice": 0.33 },
    { "t": "2025-05-01T12:00:00Z", "yesPrice": 0.34 }
  ]
}

REST · Markets / Order book

Order book

GET/v1/markets/:id/orderbook

Current bids and asks for the YES outcome. Prices are in probability (0-1).

Parameters

Parameter	Type	Required	Description
id	string (path)	Yes	Market id
depth	integer	No	Levels per side, default 10

Request

bash

curl "https://api.grandtake.com/v1/markets/mkt_001/orderbook?depth=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "marketId": "mkt_001",
  "bids": [
    { "price": 0.33, "shares": 1200 },
    { "price": 0.32, "shares": 3400 }
  ],
  "asks": [
    { "price": 0.35, "shares": 900 },
    { "price": 0.36, "shares": 2100 }
  ]
}

REST · Markets / Search markets

Search markets

GET/v1/markets/search

Full-text search across market questions. Optionally scope to a category.

Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query, e.g. "arsenal"
category	string	No	Restrict to a category
limit	integer	No	Max results, default 20

Request

bash

curl "https://api.grandtake.com/v1/markets/search?q=arsenal" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "results": [
    {
      "id": "mkt_001",
      "question": "Will Arsenal win the Premier League?",
      "category": "football",
      "yesPrice": 0.34
    }
  ],
  "total": 1
}

REST · Trading / Place order

Place order

POST/v1/orders

Place a market or limit order on a market outcome. Returns the created order with its fill status.

Parameters

Parameter	Type	Required	Description
marketId	string	Yes	Target market, e.g. mkt_001
outcome	string	Yes	YES or NO
type	string	Yes	market or limit
shares	number	Yes	Number of shares to buy
limitPrice	number	No	Required for limit orders (0-1)

Request

bash

curl -X POST "https://api.grandtake.com/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "marketId": "mkt_001", "outcome": "YES", "type": "market", "shares": 100 }'

Response

json

{
  "id": "ord_8f21",
  "marketId": "mkt_001",
  "outcome": "YES",
  "type": "market",
  "shares": 100,
  "avgPrice": 0.34,
  "cost": 34.00,
  "status": "filled"
}

REST · Trading / List orders

List orders

GET/v1/orders

List your orders, newest first. Filter by status or market.

Parameters

Parameter	Type	Required	Description
status	string	No	open · filled · cancelled
marketId	string	No	Restrict to one market

Request

bash

curl "https://api.grandtake.com/v1/orders?status=open" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "orders": [
    {
      "id": "ord_8f21",
      "marketId": "mkt_001",
      "outcome": "YES",
      "shares": 100,
      "limitPrice": 0.33,
      "status": "open"
    }
  ],
  "total": 1
}

REST · Trading / Cancel order

Cancel order

DELETE/v1/orders/:id

Cancel an open order. Filled orders cannot be cancelled.

Parameters

Parameter	Type	Required	Description
id	string (path)	Yes	Order id, e.g. ord_8f21

Request

bash

curl -X DELETE "https://api.grandtake.com/v1/orders/ord_8f21" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "id": "ord_8f21",
  "status": "cancelled"
}

REST · Portfolio / Open positions

Open positions

GET/v1/portfolio/positions

Your current open positions marked to live market prices.

Request

bash

curl "https://api.grandtake.com/v1/portfolio/positions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "positions": [
    {
      "marketId": "mkt_001",
      "question": "Will Arsenal win the Premier League?",
      "outcome": "YES",
      "shares": 100,
      "avgPrice": 0.34,
      "markPrice": 0.36,
      "unrealizedPnl": 2.00
    }
  ]
}

REST · Portfolio / Trade history

Trade history

GET/v1/portfolio/history

Paginated history of your filled trades.

Parameters

Parameter	Type	Required	Description
page	integer	No	Page number, default 1
limit	integer	No	Results per page, max 100

Request

bash

curl "https://api.grandtake.com/v1/portfolio/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "trades": [
    {
      "id": "trd_44a1",
      "marketId": "mkt_001",
      "outcome": "YES",
      "shares": 100,
      "price": 0.34,
      "side": "buy",
      "executedAt": "2025-05-01T12:03:11Z"
    }
  ],
  "total": 1,
  "page": 1
}

REST · Portfolio / Profit and loss

Profit and loss

GET/v1/portfolio/pnl

Aggregate realized and unrealized P&L across all your markets.

Request

bash

curl "https://api.grandtake.com/v1/portfolio/pnl" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "realizedPnl": 128.50,
  "unrealizedPnl": 14.00,
  "totalVolume": 4200.00,
  "winRate": 0.61
}

REST · User / Profile

Profile

GET/v1/user

The authenticated user’s public profile and KYC tier.

Request

bash

curl "https://api.grandtake.com/v1/user" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "id": "usr_19c2",
  "username": "naijatrader",
  "wallet": "0x23896a...D552",
  "kycLevel": 1,
  "createdAt": "2025-03-12T09:21:00Z"
}

REST · User / Balance

Balance

GET/v1/user/balance

Your trading balance and on-chain wallet balances.

Request

bash

curl "https://api.grandtake.com/v1/user/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "tradingBalance": 312.40,
  "currency": "USDC",
  "wallet": {
    "USDC": 50.00,
    "USDT": 0.00
  }
}

REST · Leaderboard / Rankings

Rankings

GET/v1/leaderboard

Top traders by profit or win rate over a period.

Parameters

Parameter	Type	Required	Description
period	string	No	weekly · monthly · all (default weekly)
by	string	No	profit · winRate
category	string	No	Restrict to a category

Request

bash

curl "https://api.grandtake.com/v1/leaderboard?period=weekly&by=profit" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "period": "weekly",
  "by": "profit",
  "rankings": [
    { "rank": 1, "username": "naijatrader", "profit": 1240.00 },
    { "rank": 2, "username": "lagoslukas", "profit": 980.50 }
  ]
}

WebSocket API / Connecting

Connecting

Subscribe to real-time updates over WebSocket at wss://ws.grandtake.com/v1. After connecting, send a subscribe message for the channel you want.

javascript

const ws = new WebSocket('wss://ws.grandtake.com/v1');
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'market',
  marketId: 'mkt_001'
}));
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Price update:', data.yesPrice, data.noPrice);
};

Three channels are available: market (price and volume), trades (live trade feed) and user (your order fills and resolutions - requires authentication).

WebSocket API / Event types

Event types

Every WebSocket message has a type field:

Event	Description
market.update	Price and volume update
trade.new	New trade executed on a market
order.filled	Your order was filled
market.resolved	Market resolved with an outcome

SDKs & Libraries

Official SDKs wrap authentication, pagination and types so you can ship faster.

JavaScript / TypeScript

bash

npm install @grandtake/sdk

typescript

import { GrandtakeClient } from '@grandtake/sdk';

const client = new GrandtakeClient({ apiKey: 'YOUR_API_KEY' });
const markets = await client.markets.list({ category: 'football' });

Python

bash

pip install grandtake

python

from grandtake import Client

client = Client(api_key='YOUR_API_KEY')
markets = client.markets.list(category='football')

Go, Rust and Java SDKs are on the roadmap.

Use Cases

🤖

Trading bots

Automate your prediction strategy with programmatic orders.

📊

Market data dashboards

Build analytics tools on live prices and volume.

💼

Portfolio trackers

Monitor positions and P&L across every market.

🔬

Research tools

Analyze market trends, order books and resolution patterns.

🧩

Third-party integrations

Embed Grandtake markets directly in your own app.

Changelog

v1 · Latest
Initial public REST + WebSocket API: markets, trading, portfolio, user and leaderboard.
Upcoming
Webhooks, Go & Rust SDKs, and granular per-key scopes.