API Reference

Complete REST API documentation for Halo Protocol. All endpoints use JSON request and response bodies.

Base URL

https://app.haloprotocol.io

All endpoints are relative to this base URL. Authentication is performed via session tokens passed in the Authorization header.

Authentication

Wallet-based authentication using HMAC-signed session tokens. Connect your Solana wallet and receive a session token for subsequent API calls.

POST/api/auth/connect

Connect wallet and create a session. Returns an HMAC-signed session token.

POST/api/auth/verify

Verify an existing session token. Returns wallet address and expiration.

POST/api/auth/disconnect

Invalidate the current session token.

Circles

Create, manage, and query lending circles. All write operations require authentication.

GET/api/circles

List all available circles. Supports filtering by status, trust tier, and contribution amount.

POST/api/circles

Create a new lending circle. Requires authentication. Returns the circle address.

GET/api/circles/:id

Fetch details for a specific circle including members, round state, and escrow balance.

POST/api/circles/:id/join

Join an existing circle. Requires authentication and meeting the minimum trust score.

POST/api/circles/:id/contribute

Make a contribution to the current round. Requires authentication and circle membership.

POST/api/circles/:id/distribute

Trigger payout distribution for the current round. Requires circle authority.

GET/api/circles/my

List circles the authenticated user is a member of.

Trust Score

Query and manage on-chain trust scores. Scores range from 0-1000 across four tiers: Newcomer, Silver, Gold, Platinum.

GET/api/trust-score

Fetch the trust score for the authenticated wallet. Returns score, tier, and component breakdown.

POST/api/trust-score/initialize

Initialize a trust score account on-chain for the authenticated wallet.

POST/api/trust-score/batch

Fetch trust scores for multiple wallet addresses in a single request.

Users

Manage user profiles and query user data. Profiles are linked to Solana wallet addresses.

GET/api/users/me

Fetch the authenticated user's profile including display name, avatar, and stats.

PATCH/api/users/me

Update the authenticated user's profile (display name, avatar URL).

GET/api/users/:wallet

Fetch a public user profile by wallet address.

GET/api/users/:wallet/stats

Fetch user statistics: circles joined, circles completed, total contributions, trust score.

Webhooks

Helius-powered webhook endpoints for real-time on-chain event processing. These endpoints are called by the Helius indexer, not by clients directly.

POST/api/webhooks/helius

Receive and process Solana transaction events from Helius. Requires HELIUS_WEBHOOK_SECRET.

Need More Detail?

For request/response schemas, error codes, and code examples, visit our SDK documentation or browse the source code.

TypeScript SDKFull Documentation