API Documentation

Introduction

Everything hangs off one host: http://localhost:3000. Read every path below as relative to it, and expect JSON back on every call.

Browser sessions use an httpOnly cookie after login/register. Once signed in, call the /api/v1/* endpoints from the same origin — the cookie is sent automatically.

Authentication

Sign in or register first, then reuse the session cookie on protected routes.

1. POST /api/auth/register or POST /api/auth/login
2. Server sets vb_session (httpOnly JWT, 14 days)
3. Call /api/v1/value-bets, /api/v1/settled, or package purchase with that cookie

# Register, keep cookies, then list value bets
curl -c cookies.txt -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret1","name":"You"}'

curl -b cookies.txt "http://localhost:3000/api/v1/value-bets?sport=Soccer&min_ev=5"

Errors

{
  "error": "missing_session",
  "message": "Sign in to call this endpoint."
}

Rate limits

Quotas are plan-oriented (product tiers). Hard HTTP throttling is not enforced yet — treat these as the intended ceilings when you integrate bots.

* Fair-use on Elite until hard limits ship.

Value bets

Returns the current +EV board from MySQL — the same rows powering the Scanner. Each bet includes soft-book odds, fair odds, sharp book, and a similar array for cross-book comparison.

Query parameters

curl -b cookies.txt \
  "http://localhost:3000/api/v1/value-bets?sport=Soccer&min_ev=5&live=0"

{
  "count": 12,
  "last": 1729410000000,
  "bets": [
    {
      "id": "vb-001",
      "sport": "Soccer",
      "league": "Premier League",
      "home": "Tottenham",
      "away": "Coventry",
      "bookmaker": "Marathon",
      "odds": 2.34,
      "fairOdds": 2.22,
      "sharpBook": "Betfair",
      "similar": [{ "bookmaker": "Bet365", "odds": 2.25 }]
    }
  ]
}

Settled bets

Historical settled sample used by the Results page — win/loss, stake, and ROI inputs.

Query parameters

curl -b cookies.txt "http://localhost:3000/api/v1/settled?result=win"

Login

Exchange email and password for a session cookie.

curl -c cookies.txt -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret1"}'

Register

Create an account (password min 6 chars) and receive a session cookie.

curl -c cookies.txt -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret1","name":"You"}'

Current user

Returns the signed-in user, including active planId when a package was purchased.

curl -b cookies.txt http://localhost:3000/api/auth/me

Purchase package

Creates a NOWPayments invoice for starter, pro, or elite. Pass network as trc20, bep20, or erc20 (maps to usdttrc20 / usdtbsc / usdterc20). Redirect the user to invoiceUrl. When NOWPayments confirms payment, POST /api/payments/nowpayments/ipn marks the order paid and sets users.plan_id.

curl -b cookies.txt -X POST http://localhost:3000/api/packages/checkout \
  -H "Content-Type: application/json" \
  -d '{"planId":"pro","network":"trc20"}'

# Response
# { "orderId": "...", "payCurrency": "usdttrc20", "invoiceUrl": "https://nowpayments.io/payment/?iid=..." }

Configure NOWPAYMENTS_API_KEY and NOWPAYMENTS_IPN_SECRET. IPN cannot reach localhost — set a public NEXT_PUBLIC_APP_URL. See Packages.