# Trading Risk API
> Trading risk-management maths as an API, computed locally and deterministically — the position-sizing and money-management numbers every disciplined trader runs before a trade. The position-size endpoint is instrument-agnostic: from an account balance, the percentage of it you are willing to risk, an entry and a stop-loss it returns the position size in units (shares, contracts, lots or coins), the cash at risk and, with a target, the potential reward and the risk-reward ratio — risk 1 % of a $10,000 account on a 50-pip stop and you trade 0.2 lots, losing exactly $100 if the stop hits. The pip-value endpoint gives the forex pip value for a lot or unit size in the quote currency, with a quote-to-account rate for non-account pairs — a standard lot at a 0.0001 pip is 10 units of the quote currency. The kelly endpoint computes the Kelly criterion optimal bet fraction f* = W − (1−W)/R from a win rate and the win/loss payoff ratio (or average win and loss), plus the half-Kelly many traders prefer and the per-unit expectancy, flagging whether the edge is positive at all. Everything is computed locally and deterministically, so it is instant and private. Ideal for trading-journal, broker, prop-firm, backtesting and fintech app developers, position-sizing and risk-management tools, and trading education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. This is risk and position-sizing maths; for FX rate conversion use a currency API and for option pricing a Black-Scholes API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/trading-api/..."
```

## Pricing
- **Free** (Free) — 3,450 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 38,000 calls/Mo, 6 req/s
- **Pro** ($22/Mo) — 186,000 calls/Mo, 15 req/s
- **Mega** ($63/Mo) — 1,050,000 calls/Mo, 40 req/s

## Endpoints

### Trading

#### `GET /v1/kelly` — Kelly criterion & expectancy

**Parameters:**
- `win_rate` (query, required, string) — Win rate (0–1 or %) Example: `0.6`
- `win_loss_ratio` (query, optional, string) — Win/loss payoff ratio Example: `2`
- `avg_win` (query, optional, string) — Average win (with avg_loss)
- `avg_loss` (query, optional, string) — Average loss

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/trading-api/v1/kelly?win_rate=0.6&win_loss_ratio=2"
```

**Response:**
```json
{
    "data": {
        "note": "Kelly f* = W − (1−W)/R; bet that fraction of capital for fastest long-run growth. Many traders use half-Kelly for a smoother ride. Expectancy = W·R − (1−W) per unit risked.",
        "inputs": {
            "win_rate": 0.6,
            "win_loss_ratio": 2
        },
        "kelly_percent": 40,
        "positive_edge": true,
        "kelly_fraction": 0.4,
        "half_kelly_percent": 20,
        "expectancy_per_unit": 0.8
    },
    "meta": {
        "timestamp": "2026-06-05T21:48:46.506Z",
        "request_id": "bd378b6b-ed0c-4469-b8d9-264f63590e43"
    },
    "status": "ok",
    "message": "Kelly criterion",
    "success": true
}
```

#### `GET /v1/pip-value` — Forex pip value

**Parameters:**
- `lots` (query, optional, string) — Lots (default 1) Example: `1`
- `contract_size` (query, optional, string) — Contract size (default 100000)
- `pip_size` (query, optional, string) — Pip size (default 0.0001; 0.01 for JPY)
- `units` (query, optional, string) — Units (instead of lots)
- `quote_to_account_rate` (query, optional, string) — Quote→account rate (default 1)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/trading-api/v1/pip-value?lots=1"
```

**Response:**
```json
{
    "data": {
        "note": "Pip value = position units × pip size, in the quote currency. A standard lot (100,000) at a 0.0001 pip is 10 of the quote currency; multiply by the quote-to-account rate for non-account quotes.",
        "inputs": {
            "lots": 1,
            "pip_size": 0.0001,
            "contract_size": 100000,
            "position_units": 100000,
            "quote_to_account_rate": 1
        },
        "pip_value_quote_currency": 10,
        "pip_value_account_currency": 10
    },
    "meta": {
        "timestamp": "2026-06-05T21:48:46.611Z",
        "request_id": "12e53744-20fa-4490-98eb-eafa552a41ab"
    },
    "status": "ok",
    "message": "Pip value",
    "success": true
}
```

#### `GET /v1/position-size` — Position size & risk-reward

**Parameters:**
- `account_balance` (query, required, string) — Account balance Example: `10000`
- `risk_percent` (query, required, string) — Risk per trade (%) Example: `1`
- `entry` (query, required, string) — Entry price Example: `1.2000`
- `stop_loss` (query, required, string) — Stop-loss price Example: `1.1950`
- `target` (query, optional, string) — Take-profit price Example: `1.2100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/trading-api/v1/position-size?account_balance=10000&risk_percent=1&entry=1.2000&stop_loss=1.1950&target=1.2100"
```

**Response:**
```json
{
    "data": {
        "note": "Units = (account × risk%) / |entry − stop|. The most you lose if the stop hits is the risk amount, whatever the instrument.",
        "inputs": {
            "entry": 1.2,
            "stop_loss": 1.195,
            "risk_percent": 1,
            "account_balance": 10000
        },
        "target": 1.21,
        "risk_amount": 100,
        "risk_per_unit": 0.005,
        "position_units": 20000,
        "position_value": 24000,
        "reward_per_unit": 0.01,
        "potential_reward": 200,
        "risk_reward_ratio": 2
    },
    "meta": {
        "timestamp": "2026-06-05T21:48:46.717Z",
        "request_id": "46dcc8a7-2771-4ced-9c68-27738bffa1f5"
    },
    "status": "ok",
    "message": "Position size",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/trading-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Position sizing is instrument-agnostic (stocks, futures, crypto, forex). Risk % is a percentage (1.5 = 1.5%). For FX rate conversion use a currency API and for option pricing a Black-Scholes API.",
        "service": "trading-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/kelly": "Kelly criterion fraction and expectancy from win rate and payoff ratio.",
            "GET /v1/pip-value": "Forex pip value for a lot/unit size in the quote (and account) currency.",
            "GET /v1/position-size": "Position size and risk-reward from account balance, risk %, entry, stop (and target)."
        },
        "description": "Trading risk-management maths: position sizing from account risk, forex pip value, and the Kelly criterion / expectancy."
    },
    "meta": {
        "timestamp": "2026-06-05T21:48:46.828Z",
        "request_id": "0214d5d0-0270-43a3-8e3e-fa7f98dbb5d1"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/trading-api
OpenAPI spec: https://www.oanor.com/api/trading-api/openapi.json