API examples

Concrete curl flows against https://api.rivalizer.com/v1. Authenticate with a scoped API key via the x-api-key header (a user JWT works too — use -H "Authorization: Bearer <jwt>" instead, with full rights).

Set the key once:

export RK="rk_your_key_here"
export BASE="https://api.rivalizer.com/v1"

Create an API key (via the web app)

Keys are created in the Developer page (account menu → Developer) (the secret is shown once). That UI calls, with a logged-in user JWT:

curl -X POST "$BASE/api-keys" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-agent", "scopes": ["BALANCE", "TROPHIES", "WAGERS"] }'

Who am I / get profile (scope: PROFILE)

curl "$BASE/users/me" -H "x-api-key: $RK"

List contracts (public — no auth needed)

curl "$BASE/markets?status=OPEN&take=20"

With filters and pagination:

curl "$BASE/markets?category=sports&search=finals&take=20&cursor=<id>"

Get one contract (public)

curl "$BASE/markets/<contractId>"

Capacity / liability for a contract (public):

curl "$BASE/markets/<contractId>/capacity"

Place a bet on a contract (scope: ORDERS_WRITE)

curl -X POST "$BASE/markets/<contractId>/bet" \
  -H "x-api-key: $RK" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": 0, "amount": "25" }'

Create a trophy wager (scope: WAGERS)

Back a contract outcome with trophies and/or in-app cash:

curl -X POST "$BASE/trophies/wagers" \
  -H "x-api-key: $RK" \
  -H "Content-Type: application/json" \
  -d '{
        "marketId": "<contractId>",
        "outcome": 0,
        "cash": 50,
        "stake": [{ "slug": "gold-cup", "qty": 1 }]
      }'

Accept an open wager on the opposing outcome (matching its total value):

curl -X POST "$BASE/trophies/wagers/<wagerId>/accept" \
  -H "x-api-key: $RK" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": 1, "cash": 50 }'

Buy a trophy (scope: TROPHIES)

curl -X POST "$BASE/trophies/buy" \
  -H "x-api-key: $RK" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "gold-cup", "quantity": 1, "paymentMethod": "BALANCE" }'

Browse the store (public) and view your case (TROPHIES):

curl "$BASE/trophies"
curl "$BASE/trophies/me" -H "x-api-key: $RK"

Get balance (scope: BALANCE)

curl "$BASE/balance" -H "x-api-key: $RK"

Ledger and deposit:

curl "$BASE/balance/transactions" -H "x-api-key: $RK"

curl -X POST "$BASE/balance/deposit" \
  -H "x-api-key: $RK" \
  -H "Content-Type: application/json" \
  -d '{ "amountUsd": 100, "method": "USDC" }'

Errors you'll see

Status	Meaning
401	Missing/invalid key or JWT
403	Key is missing the route's required scope
429	Rate limit exceeded (100 req / 60 s default)
400	Validation failed (unknown or malformed fields are rejected)

Tip: the full, current endpoint reference (every param + schema) lives at https://api.rivalizer.com/docs.