Rating API Documentation — Drive By Numbers

Quick Start

Fetch any trader's public rating with a single GET request. No authentication required for public endpoints.

bash

# Fetch a public signed rating
curl https://dbn-rating-api.workers.dev/v1/rating/TraderMike

# With an API key for higher rate limits
curl -H "X-API-Key: your_api_key_here" \
  https://dbn-rating-api.workers.dev/v1/rating/TraderMike

# Verify a signed response
curl https://dbn-rating-api.workers.dev/v1/rating/TraderMike/verify?signature=abc123...

# Fetch full breakdown (requires your own JWT)
curl -H "Authorization: Bearer eyJhbGci..." \
  https://dbn-rating-api.workers.dev/v1/rating/TraderMike/detail

Rating Tiers

The DBN Rating is an ELO-inspired character rating tracking trading discipline, execution quality, and risk management — not just win rate. See the Rating methodology white paper for full details.

Tier	Rating Range	Description
Unranked	< 1200	Below starting threshold — behavioral regression detected
Novice	1200 – 1399	Starting level — learning fundamentals
Intermediate	1400 – 1599	Consistent execution emerging
Proficient	1600 – 1799	Unlocks minimal interface density
Advanced	1800 – 1999	Marketplace publish gate unlocked
Expert	2000 – 2199	Green verified badge on marketplace
Master	2200+	Gold verified badge — top-tier trader

Endpoints

GET /v1/rating/:handle Public signed rating ▶

Returns a cryptographically signed rating payload for any trader. The signature can be independently verified, making this suitable for prop firm applications and third-party embedding.

Parameters

Name	Type	Description
handle	string	Trader's public handle (URL path parameter)

Authentication

None required. Unauthenticated requests are rate-limited to 60/min per IP. Provide an API key via the X-API-Key header for 1,000/min.

Example Request

bash

curl https://dbn-rating-api.workers.dev/v1/rating/TraderMike

Response

json — 200 ok

{
  "handle": "TraderMike",
  "rating": 1847,
  "tier": "Advanced",
  "totalTrades": 312,
  "ratingHistory": [
    { "week": "2026-W14", "rating": 1812, "trades": 18 },
    { "week": "2026-W15", "rating": 1835, "trades": 22 },
    { "week": "2026-W16", "rating": 1847, "trades": 15 }
  ],
  "lastUpdated": "2026-04-19T08:14:22Z",
  "issuedAt": "2026-04-19T10:30:00Z",
  "issuer": "drivebynumbers.com",
  "signature": "MEUCIQD...base64...",
  "verifyUrl": "https://dbn-rating-api.workers.dev/v1/rating/TraderMike/verify?signature=MEUCIQD...",
  "publicKeyUrl": "https://dbn-rating-api.workers.dev/.well-known/rating-public-key.pem"
}

Signature format: ECDSA P-256 over the SHA-256 digest of the canonical JSON payload (all fields except signature, verifyUrl, and publicKeyUrl). Base64url-encoded.

GET /v1/rating/:handle/verify Verify a signed response ▶

Independently verifies a previously issued signed rating. Use this to confirm that a rating payload has not been tampered with and is still current.

Query Parameters

Name	Type	Description
signature	string	The `signature` value from the original response (required)

Example Request

bash

curl "https://dbn-rating-api.workers.dev/v1/rating/TraderMike/verify?signature=MEUCIQD...base64..."

Response

json — 200 ok

{
  "valid": true,
  "cryptographicallyValid": true,
  "ratingCurrent": true,
  "handleMatch": true,
  "fresh": true,
  "ageSeconds": 842,
  "rating": 1847,
  "handle": "TraderMike",
  "issuedAt": "2026-04-19T10:30:00Z"
}

Freshness: fresh is true if the signature was issued within the last 24 hours. ratingCurrent is true if the signed rating still matches the trader's current rating.

GET /v1/rating/:handle/detail Full breakdown (own JWT required) ▶

Returns the full rating breakdown including behavioral scores, Lock calibration status, and per-component rating analysis. Only accessible with the trader's own JWT — you cannot view another trader's detail endpoint.

Authentication

Required. Pass a valid JWT in the Authorization: Bearer header. The JWT must belong to the handle being queried.

Example Request

bash

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://dbn-rating-api.workers.dev/v1/rating/TraderMike/detail

Response

json — 200 ok

{
  "handle": "TraderMike",
  "rating": 1847,
  "tier": "Advanced",
  "totalTrades": 312,
  "ratingHistory": [ /* ... same as public */ ],
  "lastUpdated": "2026-04-19T08:14:22Z",
  "issuedAt": "2026-04-19T10:30:00Z",
  "issuer": "drivebynumbers.com",
  "signature": "MEUCIQD...base64...",
  "verifyUrl": "https://dbn-rating-api.workers.dev/v1/rating/TraderMike/verify?signature=...",
  "publicKeyUrl": "https://dbn-rating-api.workers.dev/.well-known/rating-public-key.pem",
  "behaviorScores": {
    "discipline": 88,
    "execution": 76,
    "riskManagement": 91,
    "emotionalStability": 72
  },
  "lockCalibrated": true,
  "ratingBreakdown": {
    "winContribution": +285,
    "lossContribution": -162,
    "revengeDeductions": -40,
    "slMoveDeductions": -15,
    "adherenceBonuses": +79,
    "netFromBase": +647
  }
}

Error Responses

Status	Code	Description
401	string	Missing or invalid JWT
403	string	JWT does not match the requested handle
404	string	Handle not found

Authentication

The Rating API supports two authentication methods. Public endpoints work without auth but have lower rate limits.

API Keys

For applications that need higher throughput on public endpoints. Pass via the X-API-Key header.

bash

curl -H "X-API-Key: dbn_rk_live_abc123..." \
  https://dbn-rating-api.workers.dev/v1/rating/TraderMike

Generate API keys from your Account Settings page. Keys are prefixed with dbn_rk_live_ (production) or dbn_rk_test_ (sandbox).

JWT Bearer Tokens

Required for the /detail endpoint. Obtain a JWT by signing in via the DBN auth flow.

bash

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://dbn-rating-api.workers.dev/v1/rating/TraderMike/detail

Security: Never expose JWTs in client-side code or public repositories. JWTs expire after 1 hour. Use refresh tokens to obtain new access tokens.

Rate Limiting

Auth Method	Limit	Window	Scope
No auth	60	per minute	Per IP address
API Key	1,000	per minute	Per key
JWT Bearer	300	per minute	Per user

Rate limit status is returned in response headers:

response headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1745054460

Exceeding the limit returns 429 Too Many Requests with a Retry-After header in seconds.

Response Format

All responses are JSON with Content-Type: application/json. Successful responses return HTTP 200. Errors follow a consistent structure:

json — error response

{
  "error": "not_found",
  "message": "No trader found with handle 'UnknownUser'",
  "status": 404
}

Status	Meaning
200	Success
400	Bad request — missing or malformed parameters
401	Unauthorized — missing or invalid credentials
403	Forbidden — valid auth but insufficient permissions
404	Not found — handle does not exist
429	Rate limited — retry after the specified window
500	Internal server error

Embeddable Widget

Display your verified rating on any website with a single script tag. The widget auto-verifies the signature on load and links back to your public profile.

Embed Code

html

<!-- DBN Rating Widget -->
<div id="dbn-rating-widget"
     data-handle="TraderMike"
     data-theme="dark"></div>
<script src="https://dbn-rating-api.workers.dev/widget.js"
        async></script>

Widget Options

Attribute	Type	Description
data-handle	string	Your trader handle (required)
data-theme	string	`dark` or `light` (default: `dark`)
data-compact	boolean	Show rating number only, no tier badge
data-verify	boolean	Show green checkmark when signature is valid (default: `true`)

Key Rotation

API keys can be rotated at any time from your Account Settings. When you rotate a key:

A new key is generated immediately
The old key remains valid for a 24-hour grace period
After 24 hours, the old key returns 401
You can have at most 3 active keys at any time

Best practice: Rotate keys on a regular schedule (e.g., quarterly). Store keys in environment variables, never in source code.

CORS & Browser Usage

The Rating API supports CORS for browser-based requests. All origins are allowed for the public /v1/rating/:handle and /verify endpoints. The /detail endpoint restricts origins to drivebynumbers.com.

javascript

// Fetch a rating from the browser
const res = await fetch(
  'https://dbn-rating-api.workers.dev/v1/rating/TraderMike'
);
const data = await res.json();
console.log(data.rating, data.tier); // 1847 "Advanced"

Portable trader credential.

Quick Start

Rating Tiers

Endpoints

Parameters

Authentication

Example Request

Response

Query Parameters

Example Request

Response

Authentication

Example Request

Response

Error Responses

Authentication

API Keys

JWT Bearer Tokens

Rate Limiting

Response Format

Embeddable Widget

Embed Code

Widget Options

Key Rotation

CORS & Browser Usage