Copy page

Trading

Trading Quickstart

This guide walks through a first Prediction Markets trade using the REST API. It covers the checks to perform before trading, how to select a current contract, and how to place, monitor, cancel, and reconcile a limit order.

For active trading and market making, use the Prediction Markets WebSocket streams. REST is useful for discovery, one-off workflows, and recovery or audit snapshots.

Prerequisites

Before sending a private request, confirm all of the following:

• You have a Gemini account with Prediction Markets access and an account you intend to trade.
• The account is funded. Check available balances with Get Available Balances.
• Your credential is supported by the interface you are using. For an API key, create an account-scoped key in API Settings, keep its secret securely, and follow API key authentication to create the nonce, payload, and signature headers. For OAuth, request the scopes described in OAuth.
• The API key has the Trader role for trading operations. For OAuth, request the scopes described in OAuth and confirm the operation-specific requirement; Place Order documents orders:create for order creation. See Roles and permissions and the endpoint-specific requirements in Cancel Order.
• You are operating on the intended account. Account-level keys trade the account to which they are scoped; if you use a group-level workflow, follow the documented account-selection rules in Accounts and subaccounts.

Prediction Markets order requests are private REST requests. With API-key authentication, merge the endpoint fields with request and nonce, base64-encode that complete payload into X-GEMINI-PAYLOAD, sign it, and send an empty HTTP body as described in Private API invocation. Never place an API secret in source code, logs, or a client application.

Terms and order vocabulary

Prediction Markets terms are versioned and accepted for the account group. Read the current content with Get Terms, check the account group with Get Terms Status, and, if hasAcceptedLatest is false, accept them with Accept Terms before retrying an order.

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.