API Reference
Heron's backend exposes a REST API (FastAPI) that serves the consumer wallet UI and provides programmatic access to vault state, decisions, and pay.sh management.
Base URL
http://localhost:8787/apiEndpoints
Health
| Method | Path | Description |
|---|---|---|
| GET | /api/health | Server health check |
Response:
{ "ok": true, "llm": true }Configuration
| Method | Path | Description |
|---|---|---|
| GET | /api/config | Vault addresses + chain info for signing |
Query params: chain (arc, giwa, solana), wallet (user's address)
Response (Solana):
{
"program": "BSPwK2zXA4K887pbm5ovxzVQS2rWJAaQkkiEU3TRY632",
"token": "So11111111111111111111111111111111111111112",
"mandateRoot": "a1b2c3...",
"executor": "HeroN...",
"decimals": 9,
"vault": "...",
"asset": "wSOL",
"assetSym": "◎",
"network": "Solana"
}Summary
| Method | Path | Description |
|---|---|---|
| GET | /api/summary | TVL, APY, decision count for a chain |
Query params: chain
Response:
{
"tvl": 1.5,
"tvlDisplay": "1.5000 wSOL",
"netApy": 0.89,
"verifiedDecisions": 12,
"reservesLive": true,
"chain": "solana",
"asset": "wSOL",
"network": "Solana"
}Overview (Dashboard)
| Method | Path | Description |
|---|---|---|
| GET | /api/overview | Full dashboard data for a vault |
Query params: chain, wallet
Returns: TVL, idle/deployed breakdown, net APY, decision history, allocations, money-flow chart data, and activity feed.
Portfolio
| Method | Path | Description |
|---|---|---|
| GET | /api/portfolio | Vault positions breakdown |
Query params: chain, wallet
Response:
{
"total": 1.5,
"idle": 0.5,
"deployed": 1.0,
"reservesLive": true,
"positions": [...]
}Chains
| Method | Path | Description |
|---|---|---|
| GET | /api/chains | All chains with aggregate TVL/decisions |
Returns multi-chain portfolio view.
Tiers
| Method | Path | Description |
|---|---|---|
| GET | /api/tiers | Risk tier presets (safe, balanced, aggressive) |
Query params: chain
Portfolio Plan
| Method | Path | Description |
|---|---|---|
| GET | /api/portfolio-plan | Target-weight preview for a tier |
Query params: tier (safe, balanced, aggressive), chain
TEE Attestation
| Method | Path | Description |
|---|---|---|
| GET | /api/tee | Current attestation status + metadata |
| POST | /api/tee/verify | Run cryptographic verification |
| GET | /api/tee/download | Full attestation document (JSON) |
Pay.sh Wallet
| Method | Path | Description |
|---|---|---|
| GET | /api/paysh-wallet | Wallet address + USDC balance |
| POST | /api/paysh-wallet/create | Create new pay.sh wallet |
| POST | /api/paysh-wallet/fund | Get fund-to address for USDC |
Query params: wallet (user's connected wallet address)
Pay.sh Subscriptions
| Method | Path | Description |
|---|---|---|
| GET | /api/paysh-subscriptions | Which services are enabled |
| POST | /api/paysh-subscriptions | Toggle services on/off |
POST body:
{
"wallet": "...",
"subscriptions": { "vybe-token-price": true }
}Pay.sh Activity
| Method | Path | Description |
|---|---|---|
| GET | /api/paysh-activity | Spending log for a wallet |
Query params: wallet
Paid Loop (LLM)
| Method | Path | Description |
|---|---|---|
| GET | /api/paid-loop | LLM inference loop status |
| POST | /api/paid-loop/paysh-llm-budget | Set pay.sh LLM spend limits |
| POST | /api/paid-loop/run | Trigger paid-inference distribution run |
Authentication
Most read endpoints are public. Write endpoints that affect system state require a bearer token:
Authorization: Bearer <HERON_API_TOKEN>Rate limiting is applied to expensive operations (e.g., paid-loop runs: 5/hour).