Getting Started

Trade on real-world events using Gemini's trading infrastructure. This guide takes you from zero to a live trade in three steps — each one independently runnable so you can verify as you go.

Before You Start

1. Accept terms: Log into the Gemini Exchange and accept the Prediction Markets terms of service
2. Create an API key: Visit Settings/API and create a key with these settings:
   • Scope to your trading account
   • Enable "Uses a time-based nonce" (a security timestamp — just check the box)
   • Enable "Trading" (grants NewOrder and CancelOrder)
3. Save your API key and API secret — you'll need both below
4. Fund your account: You need USD in your Gemini account to trade. Buying 100 contracts at $0.27 costs $27.

Step 1: Find a Market

Use the REST API to browse active markets. This is the only REST call you need — everything else happens over WebSocket.

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

Code
 
// Some fields omitted — see full schema in the API reference
{
  "data": [
    {
      "id": "evt_456",
      "title": "2028 Presidential Election Winner",
      "ticker": "PRES2028",
      "status": "active",
      "category": "politics",
      "type": "binary",
      "expiryDate": "2028-11-03T23:59:59.000Z",
      "contracts": [
        {
          "label": "JD Vance",
          "ticker": "PRES2028-VANCE",
          "instrumentSymbol": "GEMI-PRES2028-VANCE",
          "status": "active",
          "prices": {
            "buy": { "yes": "0.28", "no": "0.72" },
            "sell": { "yes": "0.26", "no": "0.74" },
            "bestBid": "0.26",
            "bestAsk": "0.28",
            "lastTradePrice": "0.27"
          }
        }
      ]
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 12 }
}

The field you need is instrumentSymbol — that's GEMI-PRES2028-VANCE. This is the trading symbol you'll use for WebSocket subscriptions and orders. (The shorter ticker field is just for display.)

How Pricing Works

Every contract pays $1 if correct, $0 if wrong. The price is the probability:

• YES at $0.27 = market thinks 27% chance Vance wins
• NO at $0.73 = the other side of that prediction (YES + NO = $1.00 always)
• Buy 100 YES at $0.27 = pay $27, win $100 if correct ($73 profit), lose $27 if wrong

Settlement: When an event resolves, winning contracts automatically pay out $1 each to your account. Losing contracts expire worthless. You don't need to take any action.

Step 2: Connect and See Live Prices

A REST API makes you ask for updates. A WebSocket pushes updates to you the instant they happen. You open one connection and keep it open.

Run this script to connect and stream live prices. Replace your-api-key and your-api-secret with your credentials.

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 an Order

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

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: "100",          // 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=100
Order OPEN: side=BUY outcome=YES price=$0.27 qty=100

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=100

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" },
}));

REST vs WebSocket

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

Troubleshooting

Connection rejected: Auth headers must be sent during the WebSocket handshake — you cannot authenticate after connecting. Ensure your key is account-scoped with time-based nonces.

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

-1002 Authentication required: Your connection is not authenticated. Trading methods and orders@account require auth headers at connect time.

403 Forbidden / TERMS_NOT_ACCEPTED: Accept the Prediction Markets terms in the Gemini Exchange UI before trading. On WebSocket, this surfaces as -2010 with a rejection reason.

InsufficientFunds: Ensure your account has enough USD. 100 contracts at $0.27 = $27.

Important Notes

API Stability: Only fields documented in the API specification are considered stable. Undocumented fields in API responses may change or be removed without notice.