Voltrade Partner API

Overview

The Voltrade Partner API is a versioned REST API that exposes our competitions and deals — including real-time leaderboards — and lets approved partners register their users into competitions programmatically. Responses are JSON with a consistent envelope; money is returned as strings and timestamps as ISO-8601 UTC.

Why integrate

Getting access

Authentication

Every request needs your API key. Pass it as a bearer token (or the x-api-key header). Keys are server-side secrets — call from your backend, never expose them in a browser.

Authorization: Bearer vt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes: read (all GET endpoints) and optionally register (the registration endpoints).

Conventions

Every response shares one shape:

{ "data": <payload>, "error": null, "meta": { "page": 1, "limit": 25, "total": 42 } }

// on error:
{ "data": null, "error": { "code": "unauthorized", "message": "…" } }

Rate limits are per-key, per-minute; each response includes X-RateLimit-Limit / -Remaining / -Reset. A 429 means slow down until reset.

Endpoints

Response objects

The fields returned by the read endpoints. List endpoints return the core fields; the {slug} detail endpoints add the reward/eligibility/scoring objects.

Example: competition leaderboard response

GET /api/v1/competitions/<slug>/leaderboard?limit=2

{ "data": [
    { "rank": 1, "walletAddress": "0x0cc1…32ee", "displayName": "lucky",
      "traderSlug": "0x0cc1…32ee", "totalPoints": 119316,
      "totalVolumeUsd": "119319.79", "uncappedTotalVolumeUsd": "120006.00",
      "totalPnlUsd": "0", "totalPnlPercent": null, "totalLotteryRewardUsd": "0",
      "challengesCompleted": 0, "twitterConnected": false, "tradeCount": 0,
      "projectedRewardUsd": 627.95 }
  ],
  "error": null,
  "meta": { "page": 1, "limit": 2, "total": 46, "orderBy": "points" } }

Registering users

With the register scope, register a user by wallet address from your backend:

POST /api/v1/competitions/{slug}/register
Authorization: Bearer vt_live_…
Content-Type: application/json

{ "walletAddress": "0xabc…" }

No end-user wallet signature is required — your platform attests the user's consent. This is supported for wallet-matched competitions. Competitions that need a user action you can't perform (a verified Twitter connection, a linked Blofin/dYdX account, or a Solana wallet) return a clear 422; send those users to Voltrade to register.

Attribution & stats

Every registration is tagged to your key, so GET /stats reports the users you referred, registrations, volume driven, and your estimated referral VXP — no setup required. Provide a referral code with your key and we attribute the activity to you.

GET /api/v1/stats

{ "data": {
  "registrations": { "competitions": 42, "deals": 5, "uniqueUsers": 38 },
  "activity": { "totalVolumeUsd": "1250000.00", "totalPointsEarnedByUsers": 980000 },
  "attribution": { "code": "YOURCODE", "usersReferred": 38, "referralVxpEstimated": 98000 },
  "perCompetition": [ … ]
} }

Examples

KEY=vt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
BASE=https://voltrade.xyz/api/v1

# List active competitions
curl -s -H "Authorization: Bearer $KEY" "$BASE/competitions?status=ACTIVE&limit=10"

# Leaderboard with projected rewards
curl -s -H "Authorization: Bearer $KEY" "$BASE/competitions/<slug>/leaderboard?limit=50"

# Register a user
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"walletAddress":"0xabc…"}' "$BASE/competitions/<slug>/register"

# Your usage stats
curl -s -H "Authorization: Bearer $KEY" "$BASE/stats"

Support

Questions, higher rate limits, or want registration enabled? Reach the team on Telegram or X. See also the partner overview.