API Reference

Authentication

Create a key in the web app under API keys. The token is shown once and cannot be recovered — if you lose it, rotate the key. Keys expire after 90 days by default and a year at most.

curl "https://api.cupelar.com/forward-runs" \
  -H "Authorization: Bearer $CUPELAR_KEY"

Set CUPELAR_KEY to your cup_sk_… token in your local environment. Send it as a Bearer token, or in an X-API-Key header. Keep the key in server-side code, out of browser bundles and source control.

Permissions

A key carries only the permissions ticked when it was made. Demo shares the live permission because both drive an authenticated Kalshi credential.

The three modes

A run is opened in one mode and stays in it. The mode declares whose money is moving, and every result the run produces is read against it.

Open a run

Create and start a shadow run using a key with runs:manage, or use Forward tests. Then use its ID and an execution key to submit orders and read results. The mode is fixed at creation. New runs begin in draft until you start them.

curl -X POST "https://api.cupelar.com/strategies" \
  -H "Authorization: Bearer $CUPELAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Mention model",
  "status": "draft",
  "visibility": "private",
  "series": [
    "KXUST5AD"
  ]
}'

curl -X POST "https://api.cupelar.com/forward-runs" \
  -H "Authorization: Bearer $CUPELAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Mention model, shadow",
  "mode": "shadow",
  "strategy_id": 12,
  "bankroll_cents": 100000,
  "policy": {
    "min_edge_cents": 3,
    "kelly_multiplier": 0.25,
    "auto_execute": true
  }
}'

curl -X POST "https://api.cupelar.com/forward-runs/7/status?state=running" \
  -H "Authorization: Bearer $CUPELAR_KEY"

Policy defaults

Every policy key and its default. Retrieve the deployed defaults with any valid key. Changing a policy creates a new version; orders continue to point to the version they ran under. Use PUT /forward-runs/{id}/policy with runs:manage for shadow runs, or a signed-in session.

For numeric fields, numeric strings are converted ("3" becomes 3); non-numeric strings fall back to the field’s default, and negative numbers are clamped to zero.

Supply allowed_series as a list, such as ["KXTEST"]. A bare string is split into individual characters: "KXTEST" becomes ["K", "X", "T", "E", "S", "T"], which can cause unexpected series_not_allowed refusals.

The recorded assumptions entry_book_source, maker_policy and exit_rule are converted to strings without checking supported values. An arbitrary value can be stored and included in the policy hash without changing execution behavior. These coercions do not produce a validation error. Use the documented values and review the returned config before using the policy.

Include bankroll_cents when merging: omitting it resets the policy’s sizing bankroll to 100000. This does not reset the run’s cash balance or its recorded starting bankroll.

Read the full version history at GET /forward-runs/{run_id}/policies with read and membership. Recorded assumptions describe the policy; the worker’s deployment schedule controls when work actually runs.

Place an order

Requires orders:shadow on a shadow run, or orders:live on a demo or live run. The run’s mode decides where the order goes. Use a run you have opened and started.

Body parameters

curl -X POST "https://api.cupelar.com/forward-runs/7/orders" \
  -H "Authorization: Bearer $CUPELAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client_order_id": "my-strategy-001",
  "ticker": "YOUR_MARKET_TICKER",
  "side": "yes",
  "action": "buy",
  "count": 5,
  "limit_price_cents": 20
}'

Replace YOUR_MARKET_TICKER with a tradable market. Use a new client_order_id for each new intent; reuse the same ID after a timeout to retrieve the original order. Both new submissions and retries return HTTP 200.

Poll the order list to follow execution. limit accepts 1–1000 and defaults to 200.

Why an order is refused

Admission failures normally return HTTP 409 with a machine-readable detail.reason. These common reasons let your code distinguish a limit from a stopped run.

{
  "detail": {
    "reason": "kill_switch",
    "message": "This run's kill switch is on."
  }
}

Auto-execute fair values

Publish a fair value, link the strategy to a running forward run, and enable auto_execute in its policy. Each worker cycle compares eligible values with the book, checks edge net of fees, and sizes orders by fractional Kelly within the run’s caps.

curl -X POST "https://api.cupelar.com/signals" \
  -H "Authorization: Bearer $CUPELAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "strategy_id": 12,
  "ticker": "YOUR_MARKET_TICKER",
  "side": "yes",
  "fair_value_cents": 65,
  "note": "Latest model estimate"
}'

strategy_id, ticker and fair_value_cents are required. Fair value is always on the YES axis, from 0 to 100, even if side is no. Publishing the same strategy and ticker updates its current value and records a new revision. The response includes revision_id; pass it as signal_revision_id when submitting your own forward-run order to preserve its forecast and predicted edge.

Use PUT /signals/{signal_id} with the same body shape to update a signal, or DELETE /signals/{signal_id} to retire it. Both require fair-values:write and membership. Decisions use the permanent revision history so the numbers acted on stay reconstructible.

Reading the results

All of these endpoints require the read scope and an active membership when billing is enabled. Monetary fields ending in _cents are in cents; ratios such as roi and fill_rate are fractions.

curl "https://api.cupelar.com/forward-runs/7/summary" \
  -H "Authorization: Bearer $CUPELAR_KEY"

Publish a track record

Attach a run to your strategy’s public page and finalize it. Publication freezes its policy and execution record, with an integrity fingerprint and a public execution manifest.

Qualifies when

• At least 30 completed position cycles

  Closing a position in several fills does not multiply the sample size.

• Across at least 3 distinct close dates

  Markets closing on the same day can share what moved that day.

• At least 14 days since the run started

  The age is measured from started_at, not creation.

• No policy change in the last 24 hours

  The terms must have stood still long enough to read the results against.

• A strategy attached and no orders still executing

  Cancel or finish outstanding orders and wait for exchange reconciliation.

Run responses include a stable owner_key and a name-based slug. Website links use /runs/{owner_key}/{slug}, or /runs/public/{owner_key}/{slug} for published records. Existing numeric links redirect; numeric API endpoints remain supported.

The public execution manifest is at /forward-runs/public/{run_id}/manifest. Neither public endpoint needs authentication.

Stopping a run

Block new order submissions with any of your credentials, including a read-only API key. Turning the switch off requires runs:manage for shadow runs, or a signed-in session. No active membership is needed to use the kill switch or cancel an order.

curl -X POST "https://api.cupelar.com/forward-runs/7/kill-switch?on=true&reason=manual-stop" \
  -H "Authorization: Bearer $CUPELAR_KEY"

Find your runs without a membership through GET /forward-runs/control/list, or inspect a known run with GET /forward-runs/{run_id}/control. Both accept any valid key.

A shadow-management key or signed-in session can set POST /forward-runs/{run_id}/status?state=paused or state=stopped. A paused run can resume. A stopped run cannot restart.