Create a competition

{
  "success": true,
  "data": {
    "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "name": "Weekend PnL Cup",
    "description": "Best realized PnL on Solana over the weekend.",
    "chain": "solana",
    "chain_name": "Solana",
    "metric": "pnl_usd",
    "wallet_trust": "all",
    "enrollment": "opt_in",
    "status": "scheduled",
    "starts_at": "2026-11-01T18:00:00Z",
    "duration_hours": 48.0,
    "started_at": null,
    "ends_at": null,
    "ended_at": null,
    "min_participants": 10,
    "max_participants": 500,
    "participants": 0,
    "min_trades": 3,
    "min_volume_usd": 100.0,
    "late_join": true,
    "prizes": [{ "rank": 1, "prize": "1,000 USDC" }, { "rank": 2, "prize": "500 USDC" }],
    "rules_version": 1,
    "standings_updated_at": null,
    "created_at": "2026-10-26T08:04:11Z",
    "updated_at": "2026-10-26T08:04:11Z",
    "changes": [],
    "changed_while_running": false
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-26T08:04:11Z"
  }
}

{
  "success": true,
  "data": {
    "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "name": "Weekend PnL Cup",
    "description": "Best realized PnL on Solana over the weekend.",
    "chain": "solana",
    "chain_name": "Solana",
    "metric": "pnl_usd",
    "wallet_trust": "all",
    "enrollment": "opt_in",
    "status": "scheduled",
    "starts_at": "2026-11-01T18:00:00Z",
    "duration_hours": 48.0,
    "started_at": null,
    "ends_at": null,
    "ended_at": null,
    "min_participants": 10,
    "max_participants": 500,
    "participants": 0,
    "min_trades": 3,
    "min_volume_usd": 100.0,
    "late_join": true,
    "prizes": [{ "rank": 1, "prize": "1,000 USDC" }, { "rank": 2, "prize": "500 USDC" }],
    "rules_version": 1,
    "standings_updated_at": null,
    "created_at": "2026-10-26T08:04:11Z",
    "updated_at": "2026-10-26T08:04:11Z",
    "changes": [],
    "changed_while_running": false
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-26T08:04:11Z"
  }
}

Creates a trading competition for your instance. It starts at starts_at, or at once, as soon as min_participants have joined.

At most 5 competitions can be open at the same time per developer account, across all your instances. A sixth is refused with competition_limit.

Body

string

required

Name, 1 to 100 characters.

string

required

The chain traded on: solana, bnb, base, eth or rh.

string

required

What ranks the traders: pnl_usd, pnl, volume_usd, volume, trades or win_rate. See Metrics.

number

required

How long it runs once started, 1 to 8760 hours (one year). Fractions are allowed.

string

Earliest start, ISO 8601, for example 2026-11-01T18:00:00Z. Without a time zone UTC is assumed. Leave it out to start as soon as enough participants joined.

string

Description, at most 2,000 characters.

string

opt_in: you join users one by one. all_users: every platform user takes part.

integer

Participants needed before it starts, 1 to 1,000,000.

integer

Maximum participants, at least min_participants. null for no limit.

integer

Trades a participant needs to be ranked, 0 to 1,000,000.

number

USD volume a participant needs to be ranked, 0 or more.

boolean

Whether users can join after the start.

string

all or verified_only: whether unverified wallets count in this competition.

any

Free-form JSON describing the prizes, at most 5,000 characters as JSON. Stored and returned as you send it, for display. CabalSpy ID does not pay out prizes.

Fields you leave out take their default value; the response shows every value in effect.

Usage Example

curl -X POST "https://api-id.cabalspy.xyz/v1/competitions" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend PnL Cup",
    "description": "Best realized PnL on Solana over the weekend.",
    "chain": "solana",
    "metric": "pnl_usd",
    "duration_hours": 48,
    "starts_at": "2026-11-01T18:00:00Z",
    "enrollment": "opt_in",
    "min_participants": 10,
    "max_participants": 500,
    "min_trades": 3,
    "min_volume_usd": 100,
    "late_join": true,
    "prizes": [{"rank": 1, "prize": "1,000 USDC"}, {"rank": 2, "prize": "500 USDC"}]
  }'

import requests

r = requests.post("https://api-id.cabalspy.xyz/v1/competitions", json={
    "name": "Weekend PnL Cup", "chain": "solana", "metric": "pnl_usd",
    "duration_hours": 48, "starts_at": "2026-11-01T18:00:00Z",
    "min_participants": 10, "min_trades": 3,
}, headers={"Authorization": "Bearer YOUR_KEY"})
c = r.json()["data"]
print(c["id"], c["status"], c["starts_at"])

const res = await fetch("https://api-id.cabalspy.xyz/v1/competitions", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Volume Sprint", chain: "base", metric: "volume_usd",
    duration_hours: 24, enrollment: "all_users",
  }),
});
const { data } = await res.json();
console.log(data.id, data.status);

Response

201 with the competition object.

string

The competition id.

string

Name and description.

string

Chain id and name.

string

The ranking metric.

string

all or verified_only.

string

opt_in or all_users.

string

scheduled, waiting, running, ended or cancelled. See Lifecycle.

string

Earliest start, or null.

number

Duration in hours.

string

Actual start, planned end and actual end. Null until they happen.

integer

Participant limits. max_participants is null for no limit.

integer

Current number of participants.

number

Minimums to be ranked.

boolean

Whether users can join after the start.

any

Your prizes JSON, or null.

integer

Raised by one with every rule change.

string

When the standings were last computed, or null.

string

Creation and last change.

array

Every rule change, see Competition detail. Empty for a new competition.

boolean

Whether a rule was changed while the competition ran.

{
  "success": true,
  "data": {
    "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "name": "Weekend PnL Cup",
    "description": "Best realized PnL on Solana over the weekend.",
    "chain": "solana",
    "chain_name": "Solana",
    "metric": "pnl_usd",
    "wallet_trust": "all",
    "enrollment": "opt_in",
    "status": "scheduled",
    "starts_at": "2026-11-01T18:00:00Z",
    "duration_hours": 48.0,
    "started_at": null,
    "ends_at": null,
    "ended_at": null,
    "min_participants": 10,
    "max_participants": 500,
    "participants": 0,
    "min_trades": 3,
    "min_volume_usd": 100.0,
    "late_join": true,
    "prizes": [{ "rank": 1, "prize": "1,000 USDC" }, { "rank": 2, "prize": "500 USDC" }],
    "rules_version": 1,
    "standings_updated_at": null,
    "created_at": "2026-10-26T08:04:11Z",
    "updated_at": "2026-10-26T08:04:11Z",
    "changes": [],
    "changed_while_running": false
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-26T08:04:11Z"
  }
}

Errors

Status	Code	Meaning
400	missing_parameter	name, chain, metric or duration_hours missing.
400	invalid_parameter	A field has an invalid value, or an unknown field was sent. `parameter` names it.
401	missing_api_key	API key missing.
403	invalid_api_key	API key invalid or not enabled for CabalSpy ID.
409	competition_limit	5 competitions are already open.
429	rate_limit_exceeded	Rate limit exceeded.

See Errors for the full list.

Introduction

Login

Data API

Users

Trading

Theses

Streams

White-Label

Competitions

Reference

Create a competition

Body

Usage Example

Response

Errors

​Body

​Usage Example

​Response

​Errors

Body

Usage Example

Response

Errors