# 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](/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](/trading/rest-api/fund-management/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](https://exchange.gemini.com/settings/api), keep its secret securely, and follow [API key authentication](/authentication/api-key) to create the nonce, payload, and signature headers. For OAuth, request the scopes described in [OAuth](/authentication/oauth).
- The API key has the Trader role for trading operations. For OAuth, request the scopes described in [OAuth](/authentication/oauth) and confirm the operation-specific requirement; [Place Order](/rest-api/prediction-markets/order-management/place-order) documents `orders:create` for order creation. See [Roles and permissions](/roles) and the endpoint-specific requirements in [Cancel Order](/rest-api/prediction-markets/order-management/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](/rest-api/common/admin/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](/authentication/api-key#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](/rest-api/prediction-markets/terms/get-terms), check the account group with [Get Terms Status](/rest-api/prediction-markets/terms/get-terms-status), and, if `hasAcceptedLatest` is `false`, accept them with [Accept Terms](/rest-api/prediction-markets/terms/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](/rest-api/prediction-markets/events/list-events), or retrieve one with [Get Event](/rest-api/prediction-markets/events/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:

```json
{
  "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](/authentication/api-key#private-api-invocation). Do not send this JSON as the HTTP request body:

```json
{
  "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:

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

See the complete request, response, authentication, roles, and parameter reference in [Place Order](/rest-api/prediction-markets/order-management/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](/rest-api/prediction-markets/order-management/get-active-orders) to find currently open orders. Use [Get Order History](/rest-api/prediction-markets/order-management/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](/prediction-markets/websocket/authentication) and subscribe to the [`orders@account` order stream](/prediction-markets/websocket/streams#order-events). 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:

```json
{
  "orderId": 12345678901
}
```

Submit it to:

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

See [Cancel Order](/rest-api/prediction-markets/order-management/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](/rest-api/prediction-markets/order-management/get-active-orders) and [Get Order History](/rest-api/prediction-markets/order-management/get-order-history) first to determine whether the original request was accepted.
- After fills, compare the order's executed quantity with [Get Positions](/rest-api/prediction-markets/positions/get-positions). Use [Get Settled Positions](/rest-api/prediction-markets/positions/get-settled-positions) as the historical source for resolved contracts and payouts.
- Use [Position Updates](/prediction-markets/websocket/streams#position-updates) and [Balance Updates](/prediction-markets/websocket/streams#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](/prediction-markets/websocket/introduction).

For the full lifecycle from discovery through settlement, see [Order Lifecycle and Settlement](/prediction-markets/order-lifecycle).