Getting Started

Trade on real-world events — elections, crypto prices, sports — using Gemini's trading infrastructure. By the end of this guide you'll have browsed live markets, streamed real-time prices, and placed your first order.

Try It Now — No Account Needed

The markets API is public. Open a terminal and run:

Code
curl "https://api.gemini.com/v1/prediction-markets/events?status=active&limit=3"

You just pulled live prediction markets from Gemini. No API key, no signup.

New to prediction markets? Here's how they work.

Code
Event                        "2028 Presidential Election Winner"
  └─ Contract                "JD Vance"
       ├─ YES ask: $0.28     ~28% implied probability he wins
       └─ NO  ask: $0.73     ~73% implied probability he doesn't

Events are real-world questions. Each event contains one or more contracts — the possible outcomes you can trade. Every contract has a YES and NO side.

The price approximates the probability. A YES contract asking $0.28 means the market thinks there's roughly a 28% chance that outcome happens. Because of the bid-ask spread, buying both YES and NO will cost slightly more than $1.00 — the difference is the spread.

Payout is always $1. Exactly one side of every contract settles at $1, the other at $0. If you buy 100 YES contracts at $0.28, you pay $28. If the outcome happens, you receive $100 ($72 profit). If it doesn't, you lose your $28.

Settlement is automatic. When an event resolves, winning contracts pay out $1 each to your account. Losing contracts expire worthless. No action needed.

Step 1: Browse Markets

Every response follows the same shape: an event containing an array of contracts, each with live prices.

Code
# Filter by category — try crypto, politics, sports, or omit for all
curl "https://api.gemini.com/v1/prediction-markets/events?status=active&category=politics"


Code
// Fields omitted for brevity — see full schema in the API reference
{
  "data": [
    {
      "title": "2028 Presidential Election Winner",
      "status": "active",
      "category": "politics",
      "contracts": [
        {
          "label": "JD Vance",
          "instrumentSymbol": "GEMI-PRES2028-VANCE",
          "prices": {
            "bestBid": "0.26",
            "bestAsk": "0.28",
            "lastTradePrice": "0.27"
          }
        }
      ]
    }
  ]
}

The field you need for everything that follows is instrumentSymbol — that's the trading symbol you'll use for WebSocket subscriptions and orders.

Field	What it means
`instrumentSymbol`	Trading symbol (e.g., `GEMI-PRES2028-VANCE`). Use this for subscriptions and orders.
`bestBid` / `bestAsk`	Current best buy and sell prices on the order book.

There are also endpoints for newly listed, recently settled, and upcoming markets — all public, no auth required.

Step 2: Stream Live Prices

REST gives you snapshots, but prices move fast — especially around news events. The WebSocket streams every price change to you instantly.

Use Case	Channel	Why
Browse markets	REST `GET /v1/prediction-markets/events`	One-time lookups
Check positions	REST `POST /v1/prediction-markets/positions`	Snapshot queries
Live prices	WebSocket `{symbol}@bookTicker`	Real-time, no polling
Place/cancel orders	WebSocket `order.place` / `order.cancel`	Lowest latency
Order fills	WebSocket `orders@account`	Pushed as they happen
Balance changes	WebSocket `balances@account`	Real-time buying power

Account Setup (~2 minutes)

Steps 2 and 3 require authentication.

Log into the Gemini Exchange and accept the Prediction Markets terms of service (you'll see a prompt)
Visit Settings/API and create a key:
- Scope to your trading account
- Check the time-based nonce box (required for WebSocket auth)
- Check the Trading box (grants NewOrder and CancelOrder)
Save your API key and API secret — you'll need both below

Connection will fail without these settings

WebSocket authentication requires account-scoped keys with time-based nonces. Keys without these settings will be rejected at connection time.

Replace your-api-key and your-api-secret with your credentials, then run:

You should see prices streaming in your terminal:

Code
GEMI-PRES2028-VANCE  bid: $0.26 (5000 contracts)  ask: $0.28 (3200 contracts)
GEMI-PRES2028-VANCE  bid: $0.26 (4800 contracts)  ask: $0.28 (3200 contracts)
GEMI-PRES2028-VANCE  bid: $0.27 (1200 contracts)  ask: $0.28 (3200 contracts)

If you see prices, your connection and authentication are working. Press Ctrl+C to stop, then move on to Step 3.

Try it in the playground → — subscribe to any stream without writing code.

Connection rejected?

Auth headers must be sent during the WebSocket handshake — you cannot authenticate after connecting. Double-check that your key is account-scoped with time-based nonces enabled.

Step 3: Place Your First Trade

Now the real thing. This script connects, subscribes to prices and your order updates, waits for a price, then places a limit order.

Fund your account first: You need USD in your Gemini account. Start small — buying 10 contracts at $0.27 costs $2.70.

You should see:

Code
Best bid: $0.26  Best ask: $0.28
Placing order...
Order NEW: side=BUY outcome=YES price=$0.27 qty=10
Order OPEN: side=BUY outcome=YES price=$0.27 qty=10

Try it in the playground → — place orders interactively without writing code.

Your order is now live on the book at $0.27. When someone sells at your price, you'll see:

Code
Order FILLED: side=BUY outcome=YES price=$0.27 qty=10

Cancelling Orders

To cancel, send order.cancel with the order ID from the i field in the order event:

Order rejected?

-2010: Price must be between $0.01–$0.99, quantity must be > 0, and eventOutcome must be YES or NO. The market may also be closed.

TERMS_NOT_ACCEPTED: Accept the Prediction Markets terms in the Gemini Exchange UI first.

InsufficientFunds: Your account needs enough USD to cover the order. 10 contracts at $0.27 = $2.70.

Next Steps

WebSocket playground — Test every method interactively
Stream reference — All data streams (depth, trades, order events)
Authentication details — Signature generation for other languages
Prediction Markets API — Full REST API reference
Ticker formats — How prediction market symbols are structured
Maker Rebate Program — Earn rebates by providing liquidity

Last modified on May 5, 2026

Getting Started

Try It Now — No Account Needed

The markets API is public. Open a terminal and run:

Code
curl "https://api.gemini.com/v1/prediction-markets/events?status=active&limit=3"

You just pulled live prediction markets from Gemini. No API key, no signup.

New to prediction markets? Here's how they work.

Code
Event                        "2028 Presidential Election Winner"
  └─ Contract                "JD Vance"
       ├─ YES ask: $0.28     ~28% implied probability he wins
       └─ NO  ask: $0.73     ~73% implied probability he doesn't

Events are real-world questions. Each event contains one or more contracts — the possible outcomes you can trade. Every contract has a YES and NO side.

Settlement is automatic. When an event resolves, winning contracts pay out $1 each to your account. Losing contracts expire worthless. No action needed.

Step 1: Browse Markets

Every response follows the same shape: an event containing an array of contracts, each with live prices.

Code
# Filter by category — try crypto, politics, sports, or omit for all
curl "https://api.gemini.com/v1/prediction-markets/events?status=active&category=politics"


Code
// Fields omitted for brevity — see full schema in the API reference
{
  "data": [
    {
      "title": "2028 Presidential Election Winner",
      "status": "active",
      "category": "politics",
      "contracts": [
        {
          "label": "JD Vance",
          "instrumentSymbol": "GEMI-PRES2028-VANCE",
          "prices": {
            "bestBid": "0.26",
            "bestAsk": "0.28",
            "lastTradePrice": "0.27"
          }
        }
      ]
    }
  ]
}

The field you need for everything that follows is instrumentSymbol — that's the trading symbol you'll use for WebSocket subscriptions and orders.

Field	What it means
`instrumentSymbol`	Trading symbol (e.g., `GEMI-PRES2028-VANCE`). Use this for subscriptions and orders.
`bestBid` / `bestAsk`	Current best buy and sell prices on the order book.

There are also endpoints for newly listed, recently settled, and upcoming markets — all public, no auth required.

Step 2: Stream Live Prices

REST gives you snapshots, but prices move fast — especially around news events. The WebSocket streams every price change to you instantly.

Use Case	Channel	Why
Browse markets	REST `GET /v1/prediction-markets/events`	One-time lookups
Check positions	REST `POST /v1/prediction-markets/positions`	Snapshot queries
Live prices	WebSocket `{symbol}@bookTicker`	Real-time, no polling
Place/cancel orders	WebSocket `order.place` / `order.cancel`	Lowest latency
Order fills	WebSocket `orders@account`	Pushed as they happen
Balance changes	WebSocket `balances@account`	Real-time buying power

Account Setup (~2 minutes)

Steps 2 and 3 require authentication.

Log into the Gemini Exchange and accept the Prediction Markets terms of service (you'll see a prompt)
Visit Settings/API and create a key:
- Scope to your trading account
- Check the time-based nonce box (required for WebSocket auth)
- Check the Trading box (grants NewOrder and CancelOrder)
Save your API key and API secret — you'll need both below

Connection will fail without these settings

WebSocket authentication requires account-scoped keys with time-based nonces. Keys without these settings will be rejected at connection time.

Replace your-api-key and your-api-secret with your credentials, then run:

You should see prices streaming in your terminal:

Code
GEMI-PRES2028-VANCE  bid: $0.26 (5000 contracts)  ask: $0.28 (3200 contracts)
GEMI-PRES2028-VANCE  bid: $0.26 (4800 contracts)  ask: $0.28 (3200 contracts)
GEMI-PRES2028-VANCE  bid: $0.27 (1200 contracts)  ask: $0.28 (3200 contracts)

If you see prices, your connection and authentication are working. Press Ctrl+C to stop, then move on to Step 3.

Try it in the playground → — subscribe to any stream without writing code.

Connection rejected?

Auth headers must be sent during the WebSocket handshake — you cannot authenticate after connecting. Double-check that your key is account-scoped with time-based nonces enabled.

Step 3: Place Your First Trade

Now the real thing. This script connects, subscribes to prices and your order updates, waits for a price, then places a limit order.

Fund your account first: You need USD in your Gemini account. Start small — buying 10 contracts at $0.27 costs $2.70.

You should see:

Code
Best bid: $0.26  Best ask: $0.28
Placing order...
Order NEW: side=BUY outcome=YES price=$0.27 qty=10
Order OPEN: side=BUY outcome=YES price=$0.27 qty=10

Try it in the playground → — place orders interactively without writing code.

Your order is now live on the book at $0.27. When someone sells at your price, you'll see:

Code
Order FILLED: side=BUY outcome=YES price=$0.27 qty=10

Cancelling Orders

To cancel, send order.cancel with the order ID from the i field in the order event:

Order rejected?

-2010: Price must be between $0.01–$0.99, quantity must be > 0, and eventOutcome must be YES or NO. The market may also be closed.

TERMS_NOT_ACCEPTED: Accept the Prediction Markets terms in the Gemini Exchange UI first.

InsufficientFunds: Your account needs enough USD to cover the order. 10 contracts at $0.27 = $2.70.

Next Steps

WebSocket playground — Test every method interactively
Stream reference — All data streams (depth, trades, order events)
Authentication details — Signature generation for other languages
Prediction Markets API — Full REST API reference
Ticker formats — How prediction market symbols are structured
Maker Rebate Program — Earn rebates by providing liquidity

Last modified on May 5, 2026

Try It Now — No Account Needed

Step 1: Browse Markets

Step 2: Stream Live Prices

Account Setup (~2 minutes)

Connect and Subscribe

Step 3: Place Your First Trade

Cancelling Orders

Next Steps

Try It Now — No Account Needed

Step 1: Browse Markets

Step 2: Stream Live Prices

Account Setup (~2 minutes)

Connect and Subscribe

Step 3: Place Your First Trade

Cancelling Orders

Next Steps