API Reference

Complete REST API documentation for the Halo Protocol backend. All endpoints are served from the Next.js 14 application at the same origin as the frontend.

Base URL

Production: https://halo-protocol.app

Development: http://localhost:3000

Authentication

Most endpoints require an authenticated session. The API uses NextAuth.js v4 with JWT strategy. Sessions are established via OAuth (Google or GitHub) and passed as HTTP-only cookies.

Session Auth

Automatic via HTTP-only cookie after OAuth sign-in. No manual token management required.

Bearer Token

Admin endpoints use Authorization: Bearer ADMIN_API_KEY header.

Rate Limiting

Sliding window: 60 req/min (standard), 10 req/min (auth), 20 req/min (write operations).

System

GET/api/health

Health check endpoint returning system status, database connectivity, and version info.

Returns JSON with status, database check result, version, and timestamp. Uses no-store cache header.

Auth:None

Authentication

GET/api/auth/[...nextauth]

NextAuth.js authentication handler. Supports Google and GitHub OAuth providers.

JWT strategy with configurable session duration. Handles sign-in, sign-out, session, and callback routes.

Auth:None (OAuth flow)

POST/api/auth/[...nextauth]

NextAuth.js POST handler for sign-in and sign-out actions.

Processes OAuth callbacks, CSRF token validation, and session creation.

Auth:None (OAuth flow)

Identity

GET/api/identity

Retrieve the authenticated user's on-chain identity and wallet binding status.

Returns the user's Stacks address, DID, registration block height, and identity status.

Auth:Session (JWT)

POST/api/identity

Accepts a Stacks address. Creates the on-chain identity via halo-identity contract and updates the user record.

Auth:Session (JWT)

Circles

GET/api/circles

List all circles the authenticated user is a member of, with status and member counts.

Returns an array of circle objects including name, contribution amount, total/current members, status, and token type.

Auth:Session (JWT)

POST/api/circles

Create a new lending circle with specified parameters.

Accepts name, contribution amount, total members, and token type. Creates the circle on-chain and in the database.

Auth:Session (JWT)

GET/api/circle/[id]

Get detailed information about a specific circle including members, rounds, and on-chain state.

Returns circle details, member list with wallet addresses, current round, payout schedule, and sync status.

Auth:Session (JWT)

Credit

GET/api/credit/score

Retrieve the authenticated user's current credit score and component breakdown.

Returns score (300-850), total payments, on-time payments, late payments, circles completed/defaulted, and total volume.

Auth:Session (JWT)

GET/api/credit/history

Retrieve the authenticated user's payment history across all circles.

Returns an array of payment records with circle name, round, amount, on-time status, transaction ID, and timestamp.

Auth:Session (JWT)

Faucet

POST/api/faucet

Claim testnet tokens: 1,000 hUSD and 0.01 sBTC. Rate limited to once per 24 hours.

Mints mock tokens to the user's Stacks address via the deployer account. Uses nonce manager for transaction ordering.

Auth:Session (JWT)

Admin

POST/api/admin/sync

Trigger batch synchronization of on-chain circle state to the database.

Syncs circle status, current round, and member state from on-chain contracts to PostgreSQL. Uses timing-safe token comparison.

Auth:Bearer token (ADMIN_API_KEY)

Response Format

All endpoints return JSON responses. Successful responses use standard HTTP status codes. Error responses include a consistent error object.

Success Response (200)

{
  "score": 650,
  "totalPayments": 12,
  "onTimePayments": 11,
  "latePayments": 1,
  "circlesCompleted": 2,
  "circlesDefaulted": 0,
  "totalVolume": "50000000"
}

Error Response (4xx/5xx)

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

Status Codes

Code	Description
200	Success. Response body contains requested data.
201	Created. Resource successfully created (e.g., new circle, identity).
400	Bad Request. Invalid parameters or missing required fields.
401	Unauthorized. Missing or invalid authentication credentials.
403	Forbidden. Authenticated but insufficient permissions.
429	Too Many Requests. Rate limit exceeded. Retry after cooldown period.
500	Internal Server Error. Unexpected failure. Check server logs.