Copy page

Trading

Trading Quickstart

This guide walks you through your first Prediction Markets trade using the REST API. You will learn how to verify prerequisites, select contracts, and manage limit orders.

For active trading and market making, use the Prediction Markets WebSocket streams. REST is best for discovery, one-off orders, and state reconciliation.

Prerequisites

Before sending private requests, confirm the following:

• You have a Gemini account with Prediction Markets access.
• The account is funded. Check available balances with Get Available Balances.
• Your credential supports your chosen interface. For API keys, create an account-scoped key in API Settings. Follow API key authentication to generate HMAC headers. For OAuth, request the required scopes.
• The credential has trading permissions. API keys require the Trader role. OAuth tokens require the orders:create scope for Place Order. See Roles and permissions.
• You target the correct account. Account-level keys trade their scoped account. Master keys must specify the account shortname per Accounts and subaccounts.

Prediction Markets order endpoints are private REST routes. For API keys, merge endpoint fields with request and nonce. Base64-encode this payload into X-GEMINI-PAYLOAD, sign it, and send an empty HTTP body per Private API invocation. Never expose API secrets in source code or client apps.

Terms and order vocabulary

Prediction Markets terms are versioned and accepted at the account group level. Check status with Get Terms Status. If hasAcceptedLatest is false, call Accept Terms before placing orders.

The REST order fields used in this guide are:

Field	Meaning
symbol	The contract's exact instrumentSymbol, returned by event discovery.
orderType	limit for this guide. REST also supports stop-limit.
side	buy or sell.
outcome	yes or no.
quantity	The number of contracts, represented as a string.
price	The limit price, represented as a string in the 0–1 range.
timeInForce	good-til-cancel keeps the order active until it fills or is canceled. It is the default in the schema.

Choose an instrument symbol

Do not construct a symbol from an event title, contract label, or ticker pattern. Discover an event with List Events, or retrieve one with Get Event, then select a contract whose status and trading state indicate that it is available to trade. Use the contract's exact instrumentSymbol value.

For example, an event response can contain a contract like this:

Code
{
  "ticker": "FEDJAN26-DN25",
  "instrumentSymbol": "GEMI-FEDJAN26-DN25",
  "status": "active",
  "marketState": "open"
}

The value in instrumentSymbol is passed as symbol to REST order endpoints. Treat the event and contract metadata, including the outcome and expiry, as part of your pre-trade review.

REST flow

The smallest safe REST flow is:

1. Discover an active, open contract and save its exact instrumentSymbol.
2. Check and, if necessary, accept the latest Prediction Markets terms.
3. Confirm the account, role or OAuth scope, and available balance.
4. Submit a small limit order with POST /v1/prediction-markets/order.
5. Record the returned orderId, then query active orders or order history as needed.
6. Cancel the order with POST /v1/prediction-markets/order/cancel if it should no longer remain active.
7. Reconcile orders and positions after the response, a timeout, reconnect, or any suspected message gap.

Place a first limit order

The following is the complete API-key payload before base64 encoding. Replace <instrumentSymbol> and <nonce> with current values, then follow the signing flow in Private API invocation. Do not send this JSON as the HTTP request body:

Code
{
  "request": "/v1/prediction-markets/order",
  "nonce": "<nonce>",
  "symbol": "<instrumentSymbol>",
  "orderType": "limit",
  "side": "buy",
  "quantity": "1",
  "price": "0.50",
  "outcome": "yes",
  "timeInForce": "good-til-cancel"
}

Submit it to:

Code
POST https://api.gemini.com/v1/prediction-markets/order

See the complete request, response, authentication, roles, and parameter reference in Place Order. An accepted response includes an orderId and an order status such as open; acceptance does not mean that the order has filled.

Monitor the order

For a REST-only integration, call Get Active Orders to find currently open orders. Use Get Order History to review filled or canceled orders. Match records using the server orderId, and track filledQuantity separately from remainingQuantity because an order can be partially filled.

For live state, authenticate a connection as described in WebSocket Authentication and subscribe to the orders@account order stream. Order events report transitions such as NEW, OPEN, PARTIALLY_FILLED, FILLED, and CANCELED. Keep the WebSocket state separate from REST snapshots and rebuild it from REST after startup, reconnects, or detected gaps.

Cancel the order

Cancel by the orderId returned when the order was placed:

Code
{
  "orderId": 12345678901
}

Submit it to:

Code
POST https://api.gemini.com/v1/prediction-markets/order/cancel

See Cancel Order for the exact request and response. A cancellation request does not undo fills that already occurred, so check the final filled quantity and reconcile the resulting position.

Safety and reconciliation

• Use a small quantity for the first order and verify the event definition, outcome, price, and expiry before submitting it.
• Treat instrumentSymbol as an opaque value returned by Gemini. Do not derive it from display text or assume that symbols are interchangeable across markets.
• Persist the event, contract, instrumentSymbol, orderId, quantities, prices, timestamps, and order status from every response or event.
• On a timeout, do not blindly retry a placement. Query Get Active Orders and Get Order History first to determine whether the original request was accepted.
• After fills, compare the order's executed quantity with Get Positions. Use Get Settled Positions as the historical source for resolved contracts and payouts.
• Use Position Updates and Balance Updates for responsive account state, then use REST snapshots for recovery and audit.
• If you enable WebSocket cancelOnDisconnect, understand that all open orders placed through that WebSocket session are canceled when it disconnects. See WebSocket Introduction.

For the full lifecycle from discovery through settlement, see Order Lifecycle and Settlement.