API Reference

API Reference

Base URL

Production: https://vip.betbitsports.com/api

---

Authentication

Most endpoints require a JWT Bearer token in the Authorization header:

Authorization: Bearer <jwt_token>

Tokens are issued on signup and login.

---

Endpoints

Health Check

GET /health

Returns server status. No authentication required.

Response:

{
  "status": "ok",
  "timestamp": "2026-03-09T12:00:00.000Z"
}

---

Authentication

Sign Up

POST /api/auth/signup

Creates a new user account.

Body:

{
  "username": "alex",
  "email": "[email protected]",
  "password": "securepassword"
}

Response: User object + JWT token.

Login

POST /api/auth/login

Body:

{
  "email": "[email protected]",
  "password": "securepassword"
}

Response: User object + JWT token + wallet credentials (if linked).

Link Wallet

POST /api/auth/link-wallet

Links a smart wallet address and passkey credentials to the authenticated user. Called after passkey registration.

Body:

{
  "address": "0x...",
  "credentialId": "base64...",
  "publicKey": "base64...",
  "chainId": 43113
}

---

Wagers

Create Wager Metadata

POST /api/wagers

Stores off-chain metadata and generates a shareable link. Called before the on-chain createWager transaction.

Body:

{
  "description": "Lakers vs Celtics, March 15",
  "matchDescription": "NBA regular season game",
  "mediatorContactInfo": { "name": "Dave", "contact": "[email protected]" },
  "creatorAddress": "0x...",
  "amountRaw": "50000000",
  "fundingDeadline": "2026-03-16T00:00:00Z",
  "outcomeDeadline": "2026-03-23T00:00:00Z"
}

Response:

{
  "tempId": "uuid...",
  "metadataHash": "0x...",
  "shareableSlug": "abc123xyz",
  "shareableLink": "https://vip.betbitsports.com/invite/abc123xyz"
}

Get Wager

GET /api/wagers/:id

Returns wager metadata merged with on-chain state.

Link On-Chain Wager ID

PATCH /api/wagers/:tempId

After the on-chain createWager transaction confirms, links the real wagerId to the metadata.

Body:

{
  "wagerId": "0x...",
  "transactionHash": "0x..."
}

Submit Outcome Description

POST /api/wagers/:wagerId/outcome

Stores an optional text description alongside the on-chain outcome submission.

Body:

{
  "partyAddress": "0x...",
  "description": "Lakers won 112-98"
}

---

Invites

Get Invite

GET /api/invite/:slug

Returns wager details for the shareable invite page. No authentication required.

---

Users

Get User Profile

GET /api/users/:address

Update User Profile

PUT /api/users/:address

Body:

{
  "displayName": "Alex",
  "notificationPreferences": {
    "email": true,
    "telegram": false
  }
}

---

Database Schema

Data Model

The backend stores six tables of off-chain data:

• users: Wallet address, passkey credentials, email, display name, notification preferences

• wager_metadata: Descriptions, metadata hash (matches on-chain keccak256), creator address, deadlines

• shareable_links: Invite slugs mapped to wager IDs with signed tokens

• mediator_tokens: Time-limited, address-bound tokens for dispute resolution

• outcome_descriptions: Optional text descriptions accompanying outcome submissions

• notification_log: Audit trail for notifications sent across channels

---

Rate Limits

All API endpoints are rate-limited per IP. Authentication endpoints have stricter limits to prevent brute force attacks. Rate limit responses return HTTP 429.