> ## 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.
# Get your unrealized PnL
> | | |
| --- | --- |
| **Key** | `any` |
| **Throttle** | `account` |
| **Cost** | `1 /request` |
| **Answers** | 200 400 401 403 423 429 451 |
| **Idempotent** | `true` |
Marks each open position's market to its last trade, net of any payout you
already received for holding both outcomes, and sums basis and value over every
match. Unrealized PnL is `value − basis`. Positions page by outcome id.
## OpenAPI
````yaml /api-reference/spec-files/openapi-v3.json get /v3/portfolio/pnl
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/portfolio/pnl:
get:
tags:
- Execution
summary: Get your unrealized PnL
description: >-
| | |
| --- | --- |
| **Key** | `any` |
| **Throttle** | `account` |
| **Cost** | `1 /request` |
| **Answers** | 200 400 401 403 423 429 451 |
| **Idempotent** | `true` |
Marks each open position's market to its last trade, net of any payout
you
already received for holding both outcomes, and sums basis and value
over every
match. Unrealized PnL is `value − basis`. Positions page by outcome id.
operationId: getPortfolioPnl
parameters:
- description: Every market of one event.
in: query
name: event
required: false
schema:
format: uuid
type: string
- description: One market. With `event`, the market must belong to that event.
in: query
name: market
required: false
schema:
format: uuid
type: string
- 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
- description: >-
The management key's own id reads the primary wallet. A subaccount
key's id reads that
subaccount. Only a management key may pass it.
in: query
name: keyId
required: false
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PerWalletResponse_Pnl'
description: One page of positions, and the sums over every match.
'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/portfolio/pnl"
QUERY="limit=100"
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/portfolio/pnl";
let url = format!("{HOST}{path}?limit=100");
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/portfolio/pnl"
query = "limit=100"
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/portfolio/pnl";
const query = "limit=100";
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:
PerWalletResponse_Pnl:
description: >-
The response body of a personal read. A trading key or a session reads
its own wallet, so the
body is bare. A management key reads many, each under the key id that
addresses it.
oneOf:
- allOf:
- $ref: '#/components/schemas/Page_MarkedPosition'
- properties:
basis:
description: >-
What the matched positions cost, less any payout you already
received for
holding both outcomes of a market.
example: '55'
type: string
value:
description: >-
What settling every matched market at its `last` would still
pay you. A
position without a `last` counts at its cost. Cash plus
`value` is your
net liquidation value, and unrealized PnL is `value −
basis`.
example: '60'
type: string
required:
- basis
- value
type: object
description: >-
One page of positions in open markets, and sums over every market
the
filter matches. A closed market's positions show in
`/v3/history/positions`
until it settles.
- additionalProperties:
allOf:
- $ref: '#/components/schemas/Page_MarkedPosition'
- properties:
basis:
description: >-
What the matched positions cost, less any payout you
already received for
holding both outcomes of a market.
example: '55'
type: string
value:
description: >-
What settling every matched market at its `last` would
still pay you. A
position without a `last` counts at its cost. Cash plus
`value` is your
net liquidation value, and unrealized PnL is `value −
basis`.
example: '60'
type: string
required:
- basis
- value
type: object
description: >-
One page of positions in open markets, and sums over every market
the
filter matches. A closed market's positions show in
`/v3/history/positions`
until it settles.
propertyNames:
format: uuid
type: string
type: object
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
Page_MarkedPosition:
allOf:
- $ref: '#/components/schemas/PageCursorResponse'
- properties:
items:
items:
description: >-
An open position and the last trade on its outcome, the price
it marks at.
properties:
cost:
description: Net dollars the wallet paid for them.
example: '55'
type: string
last:
description: >-
Price of the market's latest trade on this outcome, the
catalog's `last`.
Absent before the first trade.
example: '0.6'
type: string
marketId:
format: uuid
type: string
outcomeId:
format: uuid
type: string
qty:
description: Contracts held.
format: int32
minimum: 0
type: integer
required:
- marketId
- outcomeId
- qty
- cost
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.
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
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
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.