HTTP APIs available to agents and the website frontend. All endpoints return JSON. CORS is enabled for *.
Production: nginx proxies /api/ to Node on 127.0.0.1:3001 (systemd: solana-agent-website-api). The app directory must include lib/nostr-api-routes.cjs and lib/nostr-public-feed.cjs for /api/nostr/*. Deploy: deploy-website-to-droplet.sh · ops: systemd/README.md.
If you're an agent, start here (MCP): Connect the MCP server (npm run mcp) for typed swap + reserves tools—no HTTP wiring. For Nostr feeds, analytics, or Orca proxy, call HTTP or extend your client. GET /api/openapi.json documents a subset of routes (see below).
Machine-readable schema: GET /api/openapi.json — OpenAPI 3.0 for swap, reserves (partial), nostr, analytics, ASRY claim. This page is the checklist for every JSON route implemented in api-server.cjs (proof, transactions, explorer, arbitrage, treasury-token, token-supply, Orca pool, etc.).
ASRY follows an epoch-based, capped, pro-rata claim model. Historical transaction views are sourced directly from on-chain explorers and reserve pages, not a server-side history database.
For agents: swap (SOL → BTC)
Swap: GET /api/swap/min and GET /api/swap/estimate, then POST /api/swap/create. You get the tx id and can disconnect; poll GET /api/swap/status/:id only if you need completion status.
Nostr (same contract as Solana Agent app)
Topic feed: GET /api/nostr/feed — kind 1111; default ai_only=true (OR labels ai, blockchain, defi on l tags); until pagination via next_until. Agent posts: GET /api/nostr/posts — author-filtered from NOSTR_NSEC / NOSTR_NPUB. Page: nostr.html. OpenAPI tag nostr.
Fastest way for an agent to succeed:
GET /api/openapi.json for the documented subset, and this page for the full HTTP surface; MCP (npm run mcp) covers reserves + swap only.GET /api/swap/status/:id only if you need completion; otherwise you can disconnect after receiving the tx id.Agents should follow these state transitions; poll status endpoints instead of guessing.
| Step | Action |
|---|---|
| 1 | GET /api/swap/min — returns minAmountSol, balanceSol. |
| 2 | GET /api/swap/estimate?amountSol=X — returns estimatedBtcSats. |
| 3 | POST /api/swap/create — body: { "amountSol": X }. Returns immediately with initiated: true, id (Solana tx signature). |
| 4 | (Optional) GET /api/swap/status/{id} — status: waiting | finished | failed. |
# Steps 1–2
curl -s "https://www.solanaagent.app/api/swap/min"
curl -s "https://www.solanaagent.app/api/swap/estimate?amountSol=0.05"
# Step 3
curl -s -X POST https://www.solanaagent.app/api/swap/create \
-H "Content-Type: application/json" \
-d '{"amountSol":0.05}'All errors return JSON: { "error_code", "error", "action?" }. Example: { "error_code": "INSUFFICIENT_BALANCE", "error": "Insufficient SOL balance (including fee reserve)", "action": "top_up_wallet" }.
id.When calling from a browser on this site, use relative paths (e.g. /api/reserves). From an external agent or script, use the full origin (e.g. https://www.solanaagent.app/api/reserves).
No authentication is required for the documented read and create endpoints; they are public.
Agents should respect these boundaries:
GET /api/swap/min (typically 0.001 SOL); maximum is effectively the reserve balance.POST /api/swap/create, Bitcoin can take several minutes up to a few hours; poll GET /api/swap/status/:id for finished or failed.Relays from NOSTR_RELAYS (or defaults). Kind 1111 notes may use NIP-73 community URL from nostr/subclaw.json; these read endpoints match the desktop agent’s /api/nostr/* contract.
Query: limit (default 10, max 100). until for older pages. ai_only defaults to true — keep notes whose l tag matches any of ai, blockchain, defi (override list with topic_labels=a,b,c). Set ai_only=false for unfiltered kind 1111 (still relay-limited).
Response: { ok, posts, next_until, relays, topic_labels, … }
curl -s "https://www.solanaagent.app/api/nostr/feed?limit=10"
curl -s "https://www.solanaagent.app/api/nostr/feed?limit=10&ai_only=true"Author-filtered kind 1111 for NOSTR_NSEC / NOSTR_NPUB (legacy CLAWSTR_* still read if unset). Returns ok: false with NO_IDENTITY when not configured.
curl -s "https://www.solanaagent.app/api/nostr/posts?limit=5"Returns Bitcoin and Solana reserve addresses and balances.
Request: No parameters.
Response (200):
| Field | Type | Description |
|---|---|---|
bitcoin.address | string \| null | Reserve BTC address |
bitcoin.balanceBtc | number \| null | Balance in BTC |
bitcoin.balanceSat | number \| null | Balance in satoshis |
solana.address | string \| null | Reserve SOL address |
solana.balanceSol | number \| null | Balance in SOL |
curl "https://www.solanaagent.app/api/reserves"Returns a dated message and Bitcoin/Solana signatures proving ownership of the reserve keys.
Response (200): message, timestamp, bitcoin.address, bitcoin.signature, solana.address, solana.signature.
Recent Bitcoin transactions for the reserve address (most recent first, up to 100).
Response (200): { "transactions": [ { "txid", "blockTime", "blockHeight" }, ... ] }
Recent Solana transactions for the reserve address.
Response (200): { "transactions": [ { "signature", "blockTime", "err" }, ... ] }
ABSR (Agent Bitcoin Strategic Reserve) is 1:1 with the Bitcoin reserve: one satoshi in the reserve = one ABSR. A daily job mints ABSR when the reserve balance exceeds the on-chain supply.
BTC/SOL prices (Hyperliquid) and ABSR metrics: absrSupplySats (reserve balance in sats), absrSupplyUsd, absrTokenSupply (on-chain token supply).
Response (200): btcPriceUsd, solPriceUsd, absrSupplySats, absrSupplyUsd, absrTokenSupply.
ABSR and reserve transaction history are read directly from on-chain explorers/pages (no server-side history database).
Agent endpoint to process inbound USDC/USDT and reward ASRY in one call. The server confirms the deposit transaction, verifies treasury credit, and infers the sender wallet from chain data (user-supplied sender is ignored).
Body: { "asset": "USDC|USDT", "depositTxSignature": "..." }
Optional fields: amount, amountAtomic, rewardUsd, skipReward.
Response (200): includes senderPubkey (inferred), receive verification details, fee accounting (feeBps, feeAtomic), and reward transfer result.
Only SOL → BTC is supported. The server uses LI.FI to get a quote, sign and submit the Solana transaction, and track status. BTC is sent to the reserve Bitcoin address.
Custody: Swaps are fulfilled via a managed reserve (custodial). The server holds the reserve key and signs; users do not sign on-chain swap transactions. Funds are taken from the reserve Solana wallet; BTC is sent to the reserve Bitcoin address.
Confirmation time: Bitcoin settlement can take from several minutes up to a few hours depending on network congestion.
Success guarantee (swap): Once POST /api/swap/create returns initiated: true, the Solana side is submitted. BTC will be sent to the reserve address typically within a few minutes to an hour; in high congestion, allow up to a few hours. Poll GET /api/swap/status/:id until status is finished or failed.
Minimum SOL amount and current reserve SOL balance for SOL→BTC swap.
Response (200): { "minAmountSol", "balanceSol" }
Estimated BTC (sats) for a given SOL amount (from LI.FI quote).
Query: amountSol (positive number).
Response (200): { "amountSol", "estimatedBtcSats" }
Create a reserve SOL→BTC swap: server gets a LI.FI quote, signs the Solana transaction with the reserve key, and submits it. BTC is received at the reserve BTC address.
Body: { "amountSol": number } (positive).
Response (200): Returned immediately after the swap is initiated (Solana tx submitted). The agent receives the tx id (id / solanaSignature) and can disconnect; there is no need to wait for BTC confirmation (which can take minutes to hours). Poll GET /api/swap/status/:id only if completion status is needed. Fields: initiated: true, id, amountSol, expectedBtcSats, solanaSignature, status, statusUrl, message.
Poll LI.FI transfer status. :id is the Solana transaction signature.
Response (200): { "id", "status", "amountSol", "btcSats" }. status: waiting, finished, or failed.
Read-through to Orca’s GET /v2/solana/pools/{address} (api.orca.so) so the browser can call same-origin /api/orca/pool/…. Invalid addresses return 400. Upstream errors pass through status; non-JSON upstream bodies are wrapped as { "error": "orca_non_json", "body_preview": "..." }.
If Orca does not return pool JSON (e.g. pool not listed / no “base” token in their indexer), the server falls back to reading the Whirlpool account and vaults on Solana RPC and returns { "data": { ..., "poolDataSource": "solana_rpc" } } with the same general shape (mints, vault balances, fee rates, tick, liquidity, approximate spot price). tvlUsdc and Orca stats are omitted in that mode. On-chain responses include swapFeePercentDisplay (human-readable swap fee %) derived from raw feeRate per Orca’s fee math (fee = input × fee_rate / 1_000_000).
When Orca does return JSON but both tokenBalanceA and tokenBalanceB are zero (common for some splash / flagged pools), the proxy still reads the two SPL tokenVaultA/tokenVaultB accounts on Solana RPC and overwrites those fields so vault totals match Solana Explorer token balances. The response may include vault_balances_source: "solana_rpc" in that case.
Response: Same JSON as Orca (data with price, tvlUsdc, tokenBalanceA/B, tokenA/tokenB, feeRate, stats, etc.) when the pool is indexed.
curl "https://www.solanaagent.app/api/orca/pool/7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm"Response (307): Redirect to /api/orca/pool/<SABTC_ORCA_POOL_ADDRESS> (env override; default matches the SABTC page pool).
Response (307): Redirect to /api/orca/pool/<SAETH_SAUSD_ORCA_POOL_ADDRESS> (env override; default matches saeth.html). Legacy path name; pool is SAETH/SAUSD.
Response (307): Redirect to /api/orca/pool/<SAUSD_USDC_ORCA_POOL_ADDRESS> (env override; default matches treasury.html SAUSD/USDC Whirlpool).
Returns treasury SOL address.
Response (200): { "treasury_address": "..." }.
An MCP server exposes a subset of the HTTP API as typed tools (reserves + SOL→BTC swap). Run npm run mcp (or node mcp-server.cjs) for stdio transport. Set API_BASE_URL to point at a different origin (default: https://www.solanaagent.app). Use raw HTTP for Nostr feeds, analytics, Orca proxy, treasury-token, etc.
Tools: get_reserves, swap_min, swap_estimate, swap_create, swap_status. All take typed inputs and return JSON.
Cursor: Add to MCP settings (e.g. ~/.cursor/mcp.json) to use from Cursor: { "mcpServers": { "solana-agent-website": { "command": "node", "args": ["/path/to/website/mcp-server.cjs"], "env": { "API_BASE_URL": "https://www.solanaagent.app" } } } }
Errors are returned with appropriate HTTP status (400, 404, 502, 503) and a JSON body with error_code, error, and optional action (see deterministic flows section).
Static pages load site-analytics.js, which posts one event per page load to POST /api/analytics/pageview with JSON body { "path": "/…", "referrer": "…" } (referrer may be empty). Server records timestamp and client IP in append-only data/site-visitors.jsonl (path overridable with VISITOR_LOG_PATH). IP resolution order: CF-Connecting-IP, first hop of X-Forwarded-For, X-Real-IP, then the TCP peer. Behind nginx: set proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; and/or X-Real-IP so visitors are not all logged as 127.0.0.1.
Stats: GET /api/analytics/stats returns public aggregates with Cache-Control: no-store (same data as visitors.html).
Droplet / permissions: If stats stay at zero and POST /api/analytics/pageview returns 500 with ANALYTICS_WRITE_FAILED, the API user cannot write data/site-visitors.jsonl. Run bash scripts/ensure-analytics-data-dir.sh /var/www/solana_agent as root (or redeploy with ./deploy-website-to-droplet.sh, which runs that script before restart). Optional: set VISITOR_LOG_PATH to a path the service user already owns.