API v1

Signal Publishing API

For analysts who want to publish signals — and read back how they settled — from a script or bot instead of the web app. One API key, no magic-link login required.

Quickstart

The whole flow, start to finish.

  1. Log in and generate a key under Settings → API access.
  2. Send it as X-API-Key on every request below.
  3. Look up a market with GET /v1/markets, then publish with POST /v1/signals.

Get an API key

Keys are generated from the web app — only analyst and admin accounts can hold one.

Log in, then open Settings → API access and click Generate key. The full key is shown once — copy it immediately. After that, only its prefix and label are visible, so if you lose it, revoke it and generate a new one.

Prefer the API itself? The same thing is one authenticated call:

curl
curl -X POST https://app.gainr.pro/api/analyst/api-keys \
  -H "Cookie: gainr_token=<your web session>" \
  -H "Content-Type: application/json" \
  -d '{"label": "my trading bot"}'

Manage keys with GET /analyst/api-keys (list, never shows the full key again) and DELETE /analyst/api-keys/:id (revoke immediately).

Authentication

Every /v1/* call needs your key in a header — no cookies, no login flow.

X-API-Key: gnr_...

A missing, invalid, or revoked key gets a 401 Unauthorized. Keys don't expire on their own — they're valid until you revoke them.

Endpoints

Look up a market, publish a signal against your own strategy, and read back how it settled.

GET/v1/strategies

Your own strategies, so you know which strategy_id to publish against.

curl
curl https://app.gainr.pro/api/v1/strategies \
  -H "X-API-Key: gnr_..."
200 OK
[
  {
    "id": "b3b9b5b0-...",
    "name": "Value Favourites",
    "sport": "football",
    "nominal_bank": "1000.00",
    "bet_range_min": "10.00",
    "bet_range_max": "100.00",
    "is_active": true,
    "last_signal_at": "2026-11-05T14:30:00.000Z",
    "analyst": { "id": "...", "display_name": "Marcus Chen", "avatar_url": null }
  }
]
GET/v1/markets

Look up the market, event, and selection identifiers a signal needs.

curl
curl "https://app.gainr.pro/api/v1/markets?sport=football&q=arsenal" \
  -H "X-API-Key: gnr_..."

curl "https://app.gainr.pro/api/v1/markets?event_id=<source_event_id>" \
  -H "X-API-Key: gnr_..."
200 OK
[
  {
    "id": "f1a2...",
    "source_event_id": "12345",
    "source_market_id": "12345:1",
    "event_name": "Arsenal vs Chelsea (Premier League)",
    "market_name": "Match Winner",
    "sport": "football",
    "status": "OPEN",
    "starts_at": "2026-11-10T15:00:00.000Z",
    "selections": [
      { "outcomeId": 1, "name": "Arsenal", "price": 1.85, "bookmaker": "..." }
    ]
  }
]
POST/v1/signals

Publish a signal. You must own the strategy_id you publish against.

curl
curl -X POST https://app.gainr.pro/api/v1/signals \
  -H "X-API-Key: gnr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": "...",
    "source_market_id": "...",
    "event_name": "Arsenal vs Chelsea (Premier League)",
    "market_name": "Match Winner",
    "selection_name": "Arsenal",
    "selection_outcome_id": 1,
    "min_odds": 1.85,
    "stake": 50,
    "expiry": "2026-11-10T18:00:00.000Z",
    "sport": "football"
  }'
201 Created
{
  "id": "9e8d...",
  "strategy_id": "...",
  "analyst_id": "...",
  "event_name": "Arsenal vs Chelsea (Premier League)",
  "market_name": "Match Winner",
  "selection_name": "Arsenal",
  "selection_outcome_id": 1,
  "min_odds": "1.8500",
  "frozen_price": "1.8700",
  "stake": "50.00",
  "expiry": "2026-11-10T18:00:00.000Z",
  "status": "OPEN",
  "created_at": "2026-11-07T09:12:00.000Z"
}

Field notes

  • strategy_id, source_market_id, event_name, market_name, selection_name, min_odds, stake, expiry are required
  • selection_outcome_id, sport, notes are optional
  • min_odds must be at least 1.01, stake at least 1
  • expiry is an ISO 8601 timestamp and must be in the future
GET/v1/signals

Your own signals, so you can record fills instead of copying them from the web app.

curl
curl "https://app.gainr.pro/api/v1/signals?strategy_id=...&status=SETTLED" \
  -H "X-API-Key: gnr_..."

Both strategy_id and status are optional filters — omit either to see everything. Always scoped to your own signals regardless of what you pass.

GET/v1/signals/:id

A single signal by id, with its current settlement fields.

curl
curl https://app.gainr.pro/api/v1/signals/<id> \
  -H "X-API-Key: gnr_..."
200 OK
{
  "id": "9e8d...",
  "strategy_id": "...",
  "analyst_id": "...",
  "status": "SETTLED",
  "min_odds": "1.8500",
  "frozen_price": "1.8700",
  "achieved_price": "1.9000",
  "stake": "50.00",
  "result": "WIN",
  "return_amount": "95.00",
  "resolved_outcome": "Arsenal",
  "void_reason": null,
  "expiry": "2026-11-10T18:00:00.000Z",
  "created_at": "2026-11-07T09:12:00.000Z",
  "updated_at": "2026-11-10T18:03:00.000Z"
}

status moves OPEN → SETTLED (or EXPIRED / CANCELLED). Once SETTLED, result is WIN, LOSS, PUSH, or VOID (with void_reason set). Someone else's signal id returns 403, not a 404 that would leak its existence.

Errors

Publishing through the API follows exactly the same rules as publishing from the web app.

  • 400Stake outside the strategy's configured bet range, or expiry not in the future.
  • 401Missing, invalid, or revoked X-API-Key.
  • 403You don't own the strategy_id or signal you're asking about, or chip actions are currently withheld on your account.
  • 404The strategy_id doesn't exist.
  • 429Rate limit exceeded — see below.

Rate limits

Applied per key, independent of your IP or anyone else calling from the same network.

30 requests / minute per API key.

Questions or issues? Reach out to the Gainr team.