API Reference

REST API for programmatic access to the Djinn protocol. All amounts are in plain USDC (not wei). All timestamps are ISO 8601.

Base URL: https://djinn.gg/api

Rate limit: 200 requests per minute per IP. Authenticated endpoints require a wallet signature session token.

Authentication

Endpoints marked with a lock icon require authentication. Connect your wallet and sign a challenge to receive a session token. Include it in the Authorization header.

// 1. Request a challenge
POST /api/auth/connect
{ "address": "0x68fc..." }

// 2. Sign and verify
POST /api/auth/verify
{ "address": "0x68fc...", "signature": "0x..." }

// 3. Use the session token
GET /api/genius/signals
Authorization: Bearer djn_...

Genius Endpoints

GET/api/genius/signalsAuth

List all signals for the authenticated genius.

Parameters

statusstringFilter: active, expired, cancelled, settled

sportstringFilter by sport key

limitintegerMax results (default 20)

offsetintegerPagination offset

Response

{
  "signals": [
    {
      "signal_id": "0xa3f...",
      "sport": "basketball_nba",
      "status": "active",
      "created_at": "2026-03-27T18:00:00Z",
      "expires_at": "2026-03-28T00:00:00Z",
      "purchases": 3,
      "total_notional": 750,
      "fees_earned": 37.50
    }
  ],
  "total": 1
}

DELETE/api/genius/signal/{signal_id}Auth

Cancel an active signal. Refunds unreleased escrow to buyers.

Response

{
  "signal_id": "0xa3f...",
  "status": "cancelled",
  "cancel_tx_hash": "0x..."
}

GET/api/genius/earningsAuth

Summary of fees earned, collateral status, and settlement history.

Response

{
  "total_fees_earned_usdc": 1250.00,
  "claimable_fees_usdc": 375.00,
  "collateral_deposited_usdc": 8000.00,
  "collateral_locked_usdc": 3500.00,
  "quality_score_30d": 0.72,
  "signals_settled": 14,
  "signals_active": 3
}

POST/api/genius/claimAuth

Claim all available fees (subject to 48-hour post-settlement delay).

Response

{
  "claimed_usdc": 375.00,
  "claim_tx_hash": "0x...",
  "next_claimable_at": "2026-03-29T14:00:00Z"
}

Idiot Endpoints

GET/api/idiot/browse

Browse available signals with filtering and sorting.

Parameters

sportstringFilter by sport key

geniusstringFilter by genius address

min_quality_scorenumberMinimum genius quality score (0-1)

max_fee_bpsintegerMaximum fee in basis points

sortstringSort: quality_score, fee, expires_soon, notional_remaining

limitintegerMax results (default 20)

Response

{
  "signals": [
    {
      "signal_id": "0xa3f...",
      "genius": "0x68fc...",
      "sport": "basketball_nba",
      "fee_bps": 500,
      "sla_multiplier_bps": 15000,
      "notional_remaining_usdc": 250,
      "genius_quality_score_30d": 0.72,
      "genius_win_rate": 0.64
    }
  ]
}

GET/api/idiot/genius/{address}/profile

View a genius's public track record and performance history.

Response

{
  "address": "0x68fc...",
  "quality_score_30d": 0.72,
  "total_signals": 47,
  "settled_signals": 44,
  "win_rate": 0.64,
  "sports": ["basketball_nba", "americanfootball_nfl"],
  "recent_settlements": [
    {
      "batch": 5,
      "quality_score": 1250,
      "favorable": 7,
      "unfavorable": 2,
      "void": 1
    }
  ]
}

POST/api/idiot/purchaseAuth

Purchase a signal. Triggers MPC availability check, escrow debit, and encrypted key share release. The real pick must be available at a sportsbook.

Parameters

signal_idstringrequiredThe signal ID to purchase

notional_usdcnumberrequiredAmount in USDC to commit

odds_decimalnumberDecimal odds (e.g. 1.91). Defaults to 2.0 if omitted

Response

{
  "purchase_id": 42,
  "signal_id": "0xa3f...",
  "available": true,
  "sportsbooks": ["DraftKings", "FanDuel"],
  "encrypted_key_shares": ["0x...", "0x..."],
  "purchase_tx_hash": "0x..."
}

GET/api/idiot/purchasesAuth

List all purchases with outcomes.

Parameters

statusstringFilter: pending, settled, void

limitintegerMax results (default 20)

Response

{
  "purchases": [
    {
      "purchase_id": 42,
      "signal_id": "0xa3f...",
      "genius": "0x68fc...",
      "notional_usdc": 200,
      "outcome": "favorable",
      "settled_at": "2026-03-28T06:00:00Z"
    }
  ]
}

GET/api/idiot/balanceAuth

Escrow balance, locked funds, and transaction history.

Response

{
  "escrow_balance_usdc": 2500.00,
  "locked_in_purchases_usdc": 400.00,
  "available_usdc": 2100.00,
  "net_pnl_usdc": 340.00
}

Public Endpoints

GET/api/network/config

Validator public keys, Shamir parameters, and contract addresses needed by the SDK. Cached; doesn't change per signal.

Response

{
  "validators": [
    { "uid": 2, "pubkey": "0x...", "endpoint": "..." },
    { "uid": 41, "pubkey": "0x...", "endpoint": "..." }
  ],
  "chain_id": 8453,
  "signal_commitment_address": "0x4712...",
  "shamir_n": 10,
  "shamir_k": 3
}

GET/api/odds

Current odds from third-party sports-data providers. No authentication required.

Parameters

sportstringrequiredSport key (e.g., basketball_nba)

GET/api/sports

List all supported sports with their keys.

GET/api/network/status

Network health: active validators, miner count, attestation rate.

GET/api/settlement/{genius}/{idiot}/status

Settlement status for a genius-idiot pair.

Response

{
  "contract_version": 2,
  "total_purchases": 12,
  "resolved_count": 8,
  "audited_count": 0,
  "audit_batch_count": 0,
  "ready_for_settlement": false
}

GEThttps://v{uid}.djinn.gg/health

Direct validator health endpoint via the wildcard router. Self-advertises public_hostname and a list of peer validators for gossip-style discovery. Replace {uid} with any UID currently in the metagraph.

Response

{
  "status": "ok",
  "version": "1095+18",
  "uid": 0,
  "shares_held": 1238,
  "pending_outcomes": 14,
  "chain_connected": true,
  "bt_connected": true,
  "attest_capable": true,
  "public_hostname": "v0.djinn.gg",
  "peers": [{"uid": 1, "ip": "...", "port": 8421}]
}

GEThttps://v{uid}.djinn.gg/v1/network/validators

Direct validator listing from one validator's metagraph view. Used by the static IPFS-deployable client to discover the network without bouncing through a centralized proxy.

Response

{
  "validators": [{"uid": 0, "ip": "...", "port": 8421, "hotkey": "5..."}],
  "served_by_uid": 0,
  "validator_count": 7,
  "served_at_ms": 1775941616000
}

POSThttps://v{uid}.djinn.gg/v1/odds/canonical

Canonical-schema odds for a sport+market, miner-driven. Replaces the legacy /api/odds Vercel proxy. Currently in bridge mode behind the canonical_odds feature flag.

Parameters

sportstringrequiredCanonical sport key (nba, nfl, mlb, ...)

marketstringrequiredmoneyline, spread, or total

bookmakersstring[]Optional bookmaker filter (e.g. ["DRAFTKINGS", "FANDUEL"])

event_idstringOptional event filter

Response

{
  "sport": "nba",
  "market": "moneyline",
  "observations": [],
  "miner_count": 0,
  "served_at_ms": 1775941616000,
  "feature_flag_enabled": false
}

GEThttps://v{uid}.djinn.gg/v1/cb/status/{hotkey}

Consensus circuit breaker status for a miner hotkey. Public so miners can self-monitor whether they're at risk of being flagged for sustained deviation from validator consensus.

Response

{
  "hotkey": "5Aa...",
  "score": 1.234,
  "sample_count": 543,
  "flagged": false,
  "flagged_at": 0.0,
  "last_disputes": [],
  "threshold": 5.0
}

POSThttps://v{uid}.djinn.gg/v1/cb/appeal

Submit an appeal to clear a circuit-breaker flag. Currently runs in honor-system mode behind the appeal_mechanism feature flag. Real TLSNotary verification lands in a follow-up.

Parameters

hotkeystringrequiredMiner hotkey to appeal

declared_sourcestringrequiredURL of the upstream the miner claims to source from

disputed_query_idsstring[]requiredRecent disputed query IDs from /v1/cb/status

tlsnotary_proofstringTLSNotary proof of the declared source (TBD verifier)

Response

{
  "hotkey": "5Aa...",
  "verdict": "honor_system_accepted",
  "cleared": true,
  "new_score": 0.0,
  "verification_mode": "honor_system",
  "message": "..."
}

Client-side encryption

The Genius signal creation flow requires client-side encryption. The API never sees plaintext picks. Use the Djinn SDK to handle encryption, decoy generation, Shamir splitting, and SealedBox encryption locally, then POST the encrypted bundle directly to each validator's /v1/signal/bundle endpoint. Use GET /api/network/config to discover validator URLs and on-chain encryption pubkeys.

← Back to Docs