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": [
    {
      "cycle": 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

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

{
  "current_cycle": 3,
  "signals_in_cycle": 7,
  "signals_resolved": 5,
  "ready_for_settlement": false
}

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