> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novig.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List event participants
> | | |
| --- | --- |
| **Key** | `any` |
| **Throttle** | `read` |
| **Cost** | `1 /request` |
| **Answers** | 200 400 401 403 423 429 451 |
| **Idempotent** | `true` |
## OpenAPI
````yaml /api-reference/spec-files/openapi-v3.json get /v3/catalog/participants
openapi: 3.1.0
info:
contact:
email: tech@novig.com
name: Contact
url: https://novig.com
description: >-
Place orders over signed REST. Watch the book and your fills on one
websocket.
title: Novig API
version: 3.0.0
servers:
- description: Paper
url: https://api.paper.novig.com
security: []
tags:
- description: >-
The tradable world: events, markets and outcomes, and the vocabularies
their fields use.
name: Catalog
- description: >-
Markets and events that are no longer in the catalog, and the caller's
positions. These records have no age limit.
name: History
- description: The catalog reads without a signature, cached at the edge.
name: Public
- description: 'Signature debugging: the string the server built from your request.'
name: Authentication
- description: Subaccounts and their ledgers.
name: Accounts
- description: Orders, and the caller's own trading state.
name: Execution
- description: The websocket entry point.
name: Streaming
- description: The rate-limit schedule, read at runtime.
name: Throttle
- description: >-
The gateway clock, and whether the exchange takes orders. Both answer
through a system lock.
name: Exchange
paths:
/v3/catalog/participants:
get:
tags:
- Catalog
summary: List event participants
description: >-
| | |
| --- | --- |
| **Key** | `any` |
| **Throttle** | `read` |
| **Cost** | `1 /request` |
| **Answers** | 200 400 401 403 423 429 451 |
| **Idempotent** | `true` |
operationId: listParticipants
parameters:
- description: Comma-separated canonical league names.
example: NFL,NBA
in: query
name: league
required: false
schema:
type: string
- description: Comma-separated event IDs.
in: query
name: event
required: false
schema:
type: string
- description: Comma-separated event statuses.
example: OPEN_PREGAME
in: query
name: status
required: false
schema:
type: string
- description: Exclusive lower bound on the event's scheduled start.
example: 1756512000000
in: query
name: startsAfter
required: false
schema:
format: int64
type: integer
- description: Exclusive upper bound on the event's scheduled start.
example: 1756598400000
in: query
name: startsBefore
required: false
schema:
format: int64
type: integer
- description: >-
Page size. Defaults to **500**, not the maximum. 1 to 5000. A value
outside that range
answers `400`.
in: query
name: limit
required: false
schema:
default: 500
format: int32
maximum: 5000
minimum: 1
type: integer
- description: The `next` cursor from the previous page. Opaque.
in: query
name: after
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Page_ParticipantsResponse'
description: One page of events, each with its competitors and players.
'400':
content:
application/json:
example:
code: PAGE_LIMIT_OUT_OF_RANGE
message: Limit must be between 1 and 5000
schema:
$ref: '#/components/schemas/ErrorBody'
description: The request is malformed.
'401':
content:
application/json:
example:
code: SIGNATURE_REJECTED
message: signature verification failed
schema:
$ref: '#/components/schemas/ErrorBody'
description: >-
The signature is absent or invalid, or the key is unknown, revoked,
or expired.
'403':
content:
application/json:
example:
code: SCOPE_INSUFFICIENT
message: api key scope is insufficient for this route
schema:
$ref: '#/components/schemas/ErrorBody'
description: The key's scope does not grant this route.
'423':
content:
application/json:
example:
code: ACCOUNT_LOCKED
message: The account is locked out of trading.
schema:
$ref: '#/components/schemas/ErrorBody'
description: The account is locked out of trading.
'429':
content:
application/json:
example:
code: RATE_LIMIT_EXCEEDED
message: Rate limit exceeded. Please wait before retrying.
schema:
$ref: '#/components/schemas/ErrorBody'
description: >-
The throttle is empty. Wait the number of seconds in `Retry-After`.
Then retry.
'451':
content:
application/json:
example:
code: ANONYMIZED_NETWORK
message: The request came over a VPN, a proxy, or a Tor exit.
schema:
$ref: '#/components/schemas/ErrorBody'
description: >-
Geolocation refused the request: an anonymized network, a restricted
region, or, for a placement, no device geolocation in the last 3
days.
security:
- keyId: []
signature: []
timestamp: []
x-codeSamples:
- lang: bash
source: |
HOST=https://api.paper.novig.com
KEY_ID=2c9a7e1d-5b3f-4e8a-a6d0-9f1b3c5e7a24
PEM=novig-api-key-mgmt-1.pem
REQ_PATH="/v3/catalog/participants"
QUERY="league=NFL"
BODY=''
TS=$(date +%s000)
HASH=$(printf %s "$BODY" \
| openssl dgst -sha256 -r | cut -d" " -f1)
# openssl signs a file, not a pipe. base64 -A never wraps.
printf 'NOVIG-V3\n%s\nGET\n%s\n%s\n%s' \
"$TS" "$REQ_PATH" "$QUERY" "$HASH" > canon.bin
SIG=$(openssl pkeyutl -sign -rawin -inkey "$PEM" \
-in canon.bin | openssl base64 -A)
curl -s -X GET "$HOST$REQ_PATH${QUERY:+?$QUERY}" \
-H "Novig-Key-Id: $KEY_ID" \
-H "Novig-Timestamp: $TS" \
-H "Novig-Signature: $SIG"
- lang: rust
source: |
use base64::prelude::*;
use ed25519_dalek::pkcs8::DecodePrivateKey;
use ed25519_dalek::{Signer, SigningKey};
use reqwest::blocking::{Client, Request};
use reqwest::{Method, Url};
use sha2::{Digest, Sha256};
use std::time::{SystemTime, UNIX_EPOCH};
const HOST: &str = "https://api.paper.novig.com";
const KEY_ID: &str =
"2c9a7e1d-5b3f-4e8a-a6d0-9f1b3c5e7a24";
const PEM: &str = "novig-api-key-mgmt-1.pem";
fn main() -> anyhow::Result<()> {
let key = Key::load(KEY_ID, PEM)?;
let client = Client::new();
let path = "/v3/catalog/participants";
let url = format!("{HOST}{path}?league=NFL");
let req = client
.get(url)
.build()?
.sign(&key)?;
println!("{}", client.execute(req)?.text()?);
Ok(())
}
/// An API key: the id the server looks up, and the
/// private half that signs.
struct Key {
id: &'static str,
signer: SigningKey,
}
impl Key {
fn load(id: &'static str, pem: &str) -> anyhow::Result {
let signer =
SigningKey::read_pkcs8_pem_file(pem)?;
Ok(Self { id, signer })
}
}
/// Signs a built request over the method, path, query and
/// body it will send, so the two can never disagree.
trait Sign: Sized {
fn sign(self, key: &Key) -> anyhow::Result;
}
impl Sign for Request {
fn sign(mut self, key: &Key) -> anyhow::Result {
let ts = SystemTime::now()
.duration_since(UNIX_EPOCH)?
.as_millis()
.to_string();
let body = self.body().and_then(|b| b.as_bytes());
let body = body.unwrap_or_default();
let canon = Canonical::new(
&ts,
self.method(),
self.url(),
body,
);
let sig = key.signer.sign(canon.0.as_bytes());
let sig = BASE64_STANDARD.encode(sig.to_bytes());
let headers = self.headers_mut();
headers.insert("Novig-Key-Id", key.id.parse()?);
headers.insert("Novig-Timestamp", ts.parse()?);
headers.insert("Novig-Signature", sig.parse()?);
Ok(self)
}
}
/// The six NOVIG-V3 lines, joined by LF.
struct Canonical(String);
impl Canonical {
fn new(
ts: &str,
method: &Method,
url: &Url,
body: &[u8],
) -> Self {
let query =
Query::from(url.query().unwrap_or(""));
let hash = format!("{:x}", Sha256::digest(body));
let method = method.as_str();
let path = url.path();
let lines = [
"NOVIG-V3", ts, method, path, &query.0, &hash,
];
Self(lines.join("\n"))
}
}
/// Each part decoded and re-encoded, then sorted by
/// name and value.
struct Query(String);
impl From<&str> for Query {
fn from(raw: &str) -> Self {
let mut pairs = raw
.split('&')
.filter(|pair| !pair.is_empty())
.map(|pair| {
pair.split_once('=').unwrap_or((pair, ""))
})
.map(|(k, v)| {
(Self::encode(k), Self::encode(v))
})
.collect::>();
pairs.sort();
let pairs =
pairs.iter().map(|(k, v)| format!("{k}={v}"));
Self(pairs.collect::>().join("&"))
}
}
impl Query {
fn encode(part: &str) -> String {
Self::decode(part)
.iter()
.map(|&b| match b {
b'-' | b'.' | b'_' | b'~' => {
(b as char).to_string()
}
_ if b.is_ascii_alphanumeric() => {
(b as char).to_string()
}
_ => format!("%{b:02X}"),
})
.collect()
}
/// Only `%XX` decodes. A bare `+` stays a `+`.
fn decode(part: &str) -> Vec {
let raw = part.as_bytes();
let mut out = Vec::with_capacity(raw.len());
let mut i = 0;
while i < raw.len() {
let escape =
raw.get(i + 1..i + 3).and_then(Self::hex);
match (raw[i], escape) {
(b'%', Some(byte)) => {
out.push(byte);
i += 3;
}
(byte, _) => {
out.push(byte);
i += 1;
}
}
}
out
}
fn hex(pair: &[u8]) -> Option {
let hi = (pair[0] as char).to_digit(16)?;
let lo = (pair[1] as char).to_digit(16)?;
Some((hi * 16 + lo) as u8)
}
}
- lang: python
source: |
import base64, hashlib, time, urllib.request
from cryptography.hazmat.primitives.serialization import (
load_pem_private_key)
HOST = "https://api.paper.novig.com"
KEY_ID = "2c9a7e1d-5b3f-4e8a-a6d0-9f1b3c5e7a24"
PEM = "novig-api-key-mgmt-1.pem"
path = "/v3/catalog/participants"
query = "league=NFL"
body = b""
ts = str(int(time.time() * 1000))
canon = "\n".join(["NOVIG-V3", ts, "GET", path, query,
hashlib.sha256(body).hexdigest()])
key = load_pem_private_key(open(PEM, "rb").read(), None)
headers = {
"Novig-Key-Id": KEY_ID,
"Novig-Timestamp": ts,
"Novig-Signature": base64.b64encode(
key.sign(canon.encode())).decode(),
}
url = f"{HOST}{path}?{query}"
req = urllib.request.Request(
url, data=body or None,
method="GET", headers=headers)
print(urllib.request.urlopen(req).read().decode())
- lang: typescript
source: |
import {
createHash, createPrivateKey, sign,
} from "node:crypto";
import { readFileSync } from "node:fs";
const HOST = "https://api.paper.novig.com";
const KEY_ID = "2c9a7e1d-5b3f-4e8a-a6d0-9f1b3c5e7a24";
const PEM = "novig-api-key-mgmt-1.pem";
const path = "/v3/catalog/participants";
const query = "league=NFL";
const body = "";
const ts = Date.now().toString();
const hash =
createHash("sha256").update(body).digest("hex");
const canon = [
"NOVIG-V3", ts, "GET", path, query, hash,
].join("\n");
const key = createPrivateKey(readFileSync(PEM));
const headers: Record = {
"Novig-Key-Id": KEY_ID,
"Novig-Timestamp": ts,
"Novig-Signature": sign(null, Buffer.from(canon), key)
.toString("base64"),
};
const url = `${HOST}${path}?${query}`;
const r = await fetch(url, {
method: "GET",
headers,
});
console.log(await r.text());
components:
schemas:
Page_ParticipantsResponse:
allOf:
- $ref: '#/components/schemas/PageCursorResponse'
- properties:
items:
items:
description: >-
The competitors and players of one event, each with the IDs of
the markets
about it. Map a market to a team or a player by these IDs.
properties:
awayCompetitorId:
description: >-
ID of the away competitor. Absent on an event that is not
a game.
format: uuid
type: string
competitors:
description: >-
The home and away competitors, and each competitor a
market is about.
items:
$ref: '#/components/schemas/Competitor'
type: array
eventId:
description: Event ID.
format: uuid
type: string
homeCompetitorId:
description: >-
ID of the home competitor. Absent on an event that is not
a game, such
as a future.
format: uuid
type: string
players:
description: Each player a market is about.
items:
$ref: '#/components/schemas/Player'
type: array
required:
- eventId
- competitors
- players
type: object
type: array
required:
- items
type: object
description: >-
One page of a listing: the items in the listing's order, then the link
to
the next page. Every paged route answers this shape.
ErrorBody:
description: Every error on the surface carries this body.
properties:
code:
description: Stable identifier. The only field to branch on.
example: MARKET_NOT_FOUND
type: string
message:
description: Human-readable. Not stable. Never match on it.
type: string
nonce:
description: The websocket request that failed. Absent on REST.
format: int64
maximum: 9007199254740991
minimum: 0
type:
- integer
- 'null'
rejected:
description: >-
One entry per refused order in a batch. Present only on an error
that a batch caused.
items:
$ref: '#/components/schemas/BatchOrderError'
type:
- array
- 'null'
required:
- code
- message
type: object
PageCursorResponse:
description: The link to the next page of a listing.
properties:
next:
description: >-
Pass it as `after` for the next page. Opaque: do not build or parse
one. Absent on the last page.
type: string
type: object
Competitor:
description: A team, or one competitor in an individual sport.
properties:
competitorId:
description: Competitor ID. A competitor keeps its ID from event to event.
format: uuid
type: string
marketIds:
description: >-
IDs of the event's markets about this competitor alone, such as its
team
total. A market on the whole game, such as a moneyline, lists under
neither side.
items:
format: uuid
type: string
type: array
name:
description: Full name, such as `Kansas City Chiefs`.
type: string
shortName:
description: Short name, such as `Chiefs`.
type: string
symbol:
description: Abbreviation, such as `KC`.
type: string
required:
- competitorId
- marketIds
type: object
Player:
description: A player one or more of the event's markets are about.
properties:
competitorId:
description: ID of the player's team, a competitor.
format: uuid
type: string
marketIds:
description: IDs of the event's markets about this player.
items:
format: uuid
type: string
type: array
name:
description: Display name, such as `Patrick Mahomes`.
type: string
playerId:
description: Player ID. A player keeps the ID from event to event.
format: uuid
type: string
position:
description: Position, such as `QB`.
type: string
required:
- playerId
- marketIds
type: object
BatchOrderError:
description: >-
One rejected order within a batch placement: which order failed, and
why.
properties:
index:
description: Zero-based position in the request.
minimum: 0
type: integer
outcomeId:
description: The outcome ID of the rejected order.
type: string
reason:
description: >-
Human-readable. Not stable. Branch on the envelope's `code` and on
`index`.
type: string
required:
- index
- outcomeId
- reason
type: object
securitySchemes:
keyId:
description: The key's UUID.
in: header
name: Novig-Key-Id
type: apiKey
signature:
description: Standard padded base64 of the NOVIG-V3 signature.
in: header
name: Novig-Signature
type: apiKey
timestamp:
description: Unix milliseconds. ±30 s.
in: header
name: Novig-Timestamp
type: apiKey
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.