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

POST/api/genius/signal/commitAuth

Submit an encrypted signal and distribute Shamir shares to validators. The SDK handles encryption, decoy generation, and Shamir splitting locally. The API only sees ciphertext. Use GET /api/network/config to get validator keys first.

Parameters

encrypted_blobstringrequiredHex-encoded encrypted signal blob

commit_hashstringrequiredKeccak256 hash of the blob

sharesobject[]requiredPer-validator Shamir key and index shares

commit_tx_hashstringrequiredOn-chain commit transaction hash

event_idstringrequiredThe Odds API event ID (public metadata)

Response

{
  "signal_id": "0xa3f...",
  "status": "active",
  "validators_received": 4,
  "validators_total": 4
}

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 The Odds API. 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, and Shamir splitting locally before calling the /api/genius/signal/commit endpoint.

← Back to Docs