Build trading systems on YM.

Quickstart

The shortest safe path opens the private feed before submitting an order, then treats feed state as execution authority.

1. Get an access token

Copycurl -sS -X POST \
  'https://auth.ympredictions.com/realms/ymp/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<client-id>' \
  --data-urlencode 'client_secret=<client-secret>'

2. Find a tradeable market

Copycurl -sS \
  'https://ympredictions.com/v1/markets?view=canonical&status=active&limit=20'

Require status=OPEN, publication_state=PUBLIC_OPEN, a future close time, and market_generation > 0. The order endpoint remains the final admission authority.

3. Open the private feed

Copynpx wscat \
  -c 'wss://ympredictions.com/v1/trading-feed' \
  -H 'Authorization: Bearer <access-token>'

4. Create one resting order

Copycurl -sS -X POST 'https://ympredictions.com/v1/orders' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: strategy-a-new-000001' \
  -d '{
    "client_order_id": "strategy-a-order-000001",
    "market_id": "<market-id>",
    "market_generation": 4,
    "action": "BUY",
    "outcome": "YES",
    "price_cents": 45,
    "quantity": 10,
    "time_in_force": "GTC"
  }'

Keep the returned command and order IDs. Wait for order.working, order.fill, or a terminal event before treating the result as venue-effective. A BUY NO @ 35 request must remain BUY / NO / 35 in REST and Private Feed v2; never complement NO prices in a command.

Authentication

Professional clients use OAuth 2.0 client credentials. Tokens are short-lived, account-bound bearer credentials.

• Never put user_id in an order command.
• Keep client secrets and access tokens out of logs and URLs.
• Obtain a replacement token before expiry and reconnect the feed from the last applied cursor.

Market identity

Trade immutable market leaves, not titles, slugs, provider references, event IDs or family IDs.

Actions, outcomes and prices

Every public price is an integer from 0 through 100 in the selected outcome's coordinate. YM derives venue side and accounting effect.

Do not complement NO prices. BUY NO at 35 means pay 35 cents for NO. The retired v1 fields side, position_side, intent, and decimal price are rejected.

Time in force: use GTC for resting liquidity and IOC for protected immediate execution. DAY is venue-session scoped and is not a substitute for long-lived prediction-market liquidity.

Order lifecycle

YM separates command admission, venue execution and financial posting. Do not collapse them into one generic accepted state.

• pending_action=REPLACE or CANCEL means the prior venue-effective state remains authoritative until confirmation.
• state_quality=RECONCILIATION_REQUIRED means stop mutating that order until YM restores confirmed venue truth.
• Only fills with settlement_status=POSTED are financially complete.

Idempotency and recovery

Every economic command needs a stable client identity before transmission.

• Use one unique Idempotency-Key per command and one unique client_order_id per new order.
• For an uncertain response, retry the exact payload with the same key. Never manufacture a new identity until the original outcome is known.
• Deduplicate private-feed delivery by event_id and apply only newer order_version values.
• Persist the signed feed cursor only after the event has been durably applied locally.

Market data

Public REST supports discovery, command preflight and snapshot recovery. It is not yet a professional streaming market-data contract.

Create an order

POST /v1/orders admits one canonical limit order. Participant identity comes from the bearer token.

Replace an order

REPLACE mutates one existing venue order while retaining its stable YM and DX identity.

Copycurl -sS -X POST \
  'https://ympredictions.com/v1/orders/<order-id>/replace' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: strategy-a-replace-000001' \
  -d '{
    "expected_order_version": 4,
    "price_cents": 44,
    "total_quantity": 10
  }'

• expected_order_version must come from the latest canonical order.
• price_cents stays in the order's immutable outcome coordinate, including for NO.
• total_quantity includes quantity already filled.
• 202 means admitted; the old price and quantity remain effective until order.replaced.
• A rejected replacement leaves the prior effective order in place.

Cancel an order

Cancellation is final only when the canonical order is terminal or the private feed delivers order.cancelled.

Copycurl -sS -X POST \
  'https://ympredictions.com/v1/orders/<order-id>/cancel' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: strategy-a-cancel-000001' \
  -d '{}'

Batch cancellation is not enabled for the v2 pilot. It will remain outside the participant contract until per-item replay and error-envelope conformance passes.

Account state

Private REST reads are self-scoped by bearer identity. Optional user_id filters cannot select another participant.

Private trading feed

The authenticated WebSocket is the live participant channel for canonical commands, orders, replacements, fills and terminal state.

Bootstrap

1. stream.welcome
2. stream.snapshot_started
3. zero or more stream.snapshot_chunk frames
4. stream.snapshot_completed
5. events after the snapshot high-water mark
6. stream.ready

Do not begin strategy command flow before stream.ready.

Lifecycle events

Resume

Copywss://ympredictions.com/v1/trading-feed?cursor=<URL-encoded-signed-cursor>

Delivery is at least once. Require schema_version == 2. The cursor is opaque, signed, participant-bound and not a DXmatch offset. On reconnect, replay from the last event your system durably applied. Before cutover, finish v1 through the announced boundary and retain its terminal/fill history. A cursorless v2 snapshot replaces nonterminal state only; it does not replay v1 history.

Errors and retries

Use the machine-readable code, not free-form text, to choose an action.

Limits

These are current protocol and controlled-pilot limits, not a public production SLA.

Capacity is assigned during onboarding and may be narrower. Cancellation uses independently reserved capacity. Clients must handle 429 and Retry-After.

In development

These capabilities are not part of the current contract. Do not build a production dependency on them yet.