Docs · HTTP API

A small surface area.

Hvisk exposes a handful of endpoints. Everything else lives in client SDKs and on-chain programs. JSON only, no GraphQL, no surprises.

All endpoints are CSRF-safe, accept and return JSON unless noted, and require an Authorization: Bearer token in production. In development, every route runs unauthenticated.

Endpoints.

GET/api/health

Service health, including Solana RPC, Supabase, and Twilio.

Response

{
  "service": "hvisk",
  "version": "0.1.0",
  "cluster": "devnet",
  "checks": {
    "solana":   { "ok": true,  "detail": "slot 287123456" },
    "supabase": { "ok": false, "detail": "no env" },
    "twilio":   { "ok": false, "detail": "no env" }
  }
}

POST/api/x402/create

Mint a new payment-required invoice. Returns HTTP 402.

Request

{
  "amount": 0.05,
  "token": "USDC",
  "recipient": "9xQe…",
  "privacy": "full",
  "memo": "API call",
  "ttlSeconds": 600
}

Response

{
  "id": "pay_5b3a8e7c2d4f1",
  "amount": 0.05,
  "token": "USDC",
  "recipient": "9xQe…",
  "chain": "solana",
  "privacy": "full",
  "expiresAt": 1730000000000,
  "payment_url": "/api/x402/pay_5b3a8e7c2d4f1"
}

GET/api/x402/{id}

Fetch an invoice and its settlement state.

Response

{
  "id": "pay_…",
  "amount": 0.05,
  "settlement": {
    "id": "pay_…",
    "signature": "5abc…",
    "status": "settled",
    "settledAt": 1730000004210,
    "proofHash": "0x…"
  }
}

POST/api/x402/settle

Submit a Solana signature to mark an invoice settled.

Request

{
  "id": "pay_…",
  "signature": "5abc…",
  "proofHash": "0x…"
}

POST/api/sms/inbound

Twilio webhook. Accepts a signed SMS payload and queues it.

Request

Body=PAY @lena 25 USDC priv:full n:7a2c9b1f
From=+15555550100
X-Hvisk-Signature=<base58>
X-Hvisk-Pubkey=<base58>

POST/api/relayer/broadcast

Forward a fully-signed VersionedTransaction (base64) to Solana.

Request

{
  "tx": "AQABBQ…",
  "priorityFee": 5000
}

Response

{ "signature": "5abc…" }