Authentication

OddsForge uses two authentication methods: API Key for programmatic access and Wallet Signature for browser-based access.

Public Endpoints (No Auth)

Most read-only endpoints are publicly accessible:

• All GET /api/markets/* endpoints
• All GET /api/events/* endpoints
• All GET /api/trades/* endpoints
• All GET /api/portfolio/* endpoints
• All GET /api/users/* endpoints
• GET /api/search
• GET /api/pool/balance/:wallet
• GET /api/pool/:marketId (pool info)
• POST /api/pool/estimate (trade estimation)

API Key Authentication

For programmatic access (bots, scripts, integrations), use API Key authentication.

Generating API Keys

1. Go to Settings → Builder Codes
2. Connect your wallet
3. Click "Generate New API Key"
4. Save your API Key, Secret, and Passphrase securely

Level 1: API Key Only (Read Endpoints)

For read-only endpoints, just include your API key in the header:

curl https://oddsforge.org/api/markets \
  -H "x-api-key: YOUR_API_KEY"

Level 2: API Key + HMAC (Write Endpoints)

Write operations (trade, withdraw) require HMAC-SHA256 signing to prove you hold the secret without exposing it.

Required Headers

Signing Process

1. Get the current UNIX timestamp (seconds)
2. Build the payload: timestamp + HTTP_METHOD + path + request_body
3. Sign with HMAC-SHA256 using your secret key
4. Send the hex-encoded signature in the x-api-signature header

// Signing payload format:
payload = timestamp + method + path + body

// Example:
timestamp = "1709000000"
method    = "POST"
path      = "/api/pool/trade"
body      = '{"wallet_addr":"0x1234...","market_id":142,"side":"yes","amount":100}'

// Full payload:
"1709000000POST/api/pool/trade{\"wallet_addr\":\"0x1234...\",\"market_id\":142,\"side\":\"yes\",\"amount\":100}"

// HMAC-SHA256 with your secret → hex digest

JavaScript Example

const crypto = require('crypto');

const API_KEY = 'your-api-key';
const SECRET = 'your-secret';

async function signedRequest(method, path, body = null) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyStr = body ? JSON.stringify(body) : '';
  const payload = timestamp + method + path + bodyStr;
  
  const signature = crypto
    .createHmac('sha256', SECRET)
    .update(payload)
    .digest('hex');

  const res = await fetch(`https://oddsforge.org${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
      'x-api-timestamp': timestamp,
      'x-api-signature': signature,
    },
    body: bodyStr || undefined,
  });

  return res.json();
}

// Place a trade
const result = await signedRequest('POST', '/api/pool/trade', {
  wallet_addr: '0x1234...abcd',
  market_id: 142,
  side: 'yes',
  amount: 100
});

Shell (curl) Example

TIMESTAMP=$(date +%s)
BODY='{"wallet_addr":"0x1234...","market_id":142,"side":"yes","amount":100}'
PAYLOAD="${TIMESTAMP}POST/api/pool/trade${BODY}"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "YOUR_SECRET" | awk '{print $2}')

curl -X POST https://oddsforge.org/api/pool/trade \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-timestamp: $TIMESTAMP" \
  -H "x-api-signature: $SIGNATURE" \
  -d "$BODY"

Wallet Signature Authentication

For browser-based frontend access (used by the OddsForge web app):

The message format includes the action, timestamp, and is verified to belong to the wallet address in the request body. Signatures must be within 5 minutes.

Security Best Practices

• Never share your API secret or expose it in client-side code
• Use environment variables to store API credentials
• Rotate keys periodically — revoke old keys from Settings
• The HMAC 30-second window prevents replay attacks
• API key wallet is permanently bound — trades can only be made from your wallet