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

Pass your partner API key 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. Keys are issued by Voltrade and shown once at creation; only a hash is stored.

Authorization: Bearer vt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes: read (all GET endpoints), register (registration endpoints), and create (launch/fund/publish competitions).

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, "registeredByAgent": false, "tradeCount": 0,
      "projectedRewardUsd": 627.95 }
  ],
  "error": null,
  "meta": { "page": 1, "limit": 2, "total": 46, "orderBy": "points" } }

Registering

On-behalf (partner, register scope) — register a user by wallet, no end-user signature; your platform attests consent:

POST /api/v1/competitions/{slug}/register
Authorization: Bearer vt_live_…

{ "walletAddress": "0xabc…" }

Self (agent-as-player) — a wallet session (or key-bound wallet) registers itself:

POST /api/v1/competitions/{slug}/register
Authorization: Bearer <sessionToken>

{ "self": true }   → { "registered": true, "mode": "self", … }

Registration is method-matched. An agent holds only a wallet, so it can join only competitions the wallet itself satisfies. On-chain competitions must match the wallet's network (a Solana competition needs a Solana wallet; an EVM competition needs an EVM wallet). Competitions that need something a wallet can't provide return a clear 422 unsupported_campaign: a linked CEX/venue account (KuCoin, Blofin, Binance, GMX, Gryps, Hyperliquid), a dYdX address, or a verified Twitter/X connection. Send those users to Voltrade to register.

Participants registered through the agent API are flagged registeredByAgent: true on the leaderboard (and shown with an "Agent" badge on Voltrade) so viewers can tell autonomous bots from people.

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.