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.

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

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.

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.

Account Setup (~2 minutes)

Steps 2 and 3 require authentication.

1. Log into the Gemini Exchange and accept the Prediction Markets terms of service (you'll see a prompt)
2. 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)
3. Save your API key and API secret — you'll need both below

Connect and Subscribe

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

Node.js
 
// npm install ws
const crypto = require("crypto");
const WebSocket = require("ws");

const API_KEY = "your-api-key";
const API_SECRET = "your-api-secret";
const SYMBOL = "GEMI-PRES2028-VANCE";

// Authentication — signs a timestamp with your secret so Gemini
// can verify your identity. You don't need to modify this block.
const nonce = Math.floor(Date.now() / 1000).toString();
const payload = Buffer.from(nonce).toString("base64");
const signature = crypto
  .createHmac("sha384", API_SECRET)
  .update(payload)
  .digest("hex");

const ws = new WebSocket("wss://ws.gemini.com", {
  headers: {
    "X-GEMINI-APIKEY": API_KEY,
    "X-GEMINI-NONCE": nonce,
    "X-GEMINI-PAYLOAD": payload,
    "X-GEMINI-SIGNATURE": signature,
  },
});

ws.on("open", () => {
  ws.send(JSON.stringify({
    id: "1",
    method: "subscribe",
    params: [`${SYMBOL}@bookTicker`],
  }));
});

ws.on("message", (raw) => {
  const data = JSON.parse(raw);
  if (data.b && data.a) {
    console.log(`${data.s}  bid: $${data.b} (${data.B} contracts)  ask: $${data.a} (${data.A} contracts)`);
  }
});

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.

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.

Node.js
 
// npm install ws
const crypto = require("crypto");
const WebSocket = require("ws");

const API_KEY = "your-api-key";
const API_SECRET = "your-api-secret";
const SYMBOL = "GEMI-PRES2028-VANCE";

const nonce = Math.floor(Date.now() / 1000).toString();
const payload = Buffer.from(nonce).toString("base64");
const signature = crypto
  .createHmac("sha384", API_SECRET)
  .update(payload)
  .digest("hex");

const ws = new WebSocket("wss://ws.gemini.com", {
  headers: {
    "X-GEMINI-APIKEY": API_KEY,
    "X-GEMINI-NONCE": nonce,
    "X-GEMINI-PAYLOAD": payload,
    "X-GEMINI-SIGNATURE": signature,
  },
});

ws.on("open", () => {
  ws.send(JSON.stringify({
    id: "1",
    method: "subscribe",
    params: [
      `${SYMBOL}@bookTicker`,  // live prices
      "orders@account",         // your order updates
    ],
  }));
});

let orderPlaced = false;

ws.on("message", (raw) => {
  const data = JSON.parse(raw);

  // Once we see a price, place an order
  if (!orderPlaced && data.b && data.a && data.s === SYMBOL) {
    console.log(`Best bid: $${data.b}  Best ask: $${data.a}`);
    console.log("Placing order...");
    orderPlaced = true;

    ws.send(JSON.stringify({
      id: "2",
      method: "order.place",
      params: {
        symbol: SYMBOL,
        side: "BUY",
        type: "LIMIT",
        timeInForce: "GTC",       // Good Til Cancelled — stays open until filled or you cancel it
        price: "0.27",            // your price — set at or above the ask to fill immediately
        quantity: "10",           // number of contracts (costs price x quantity in USD)
        eventOutcome: "YES",      // YES = predicting the event happens, NO = predicting it doesn't
        clientOrderId: "my-first-prediction",
      },
    }));
  }

  // Order lifecycle updates from orders@account stream
  // X = status, S = side, O = outcome, p = price, q = quantity
  if (["NEW", "OPEN", "FILLED", "PARTIALLY_FILLED"].includes(data.X)) {
    console.log(`Order ${data.X}: side=${data.S} outcome=${data.O} price=$${data.p} qty=${data.q}`);
  }
});

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:

Node.js
 
ws.send(JSON.stringify({
  id: "3",
  method: "order.cancel",
  params: { orderId: "73797746498585286" },
}));

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