# Hostra API

Hostra is a payment settlement engine with a double-entry ledger, durable settlement intents, and exactly-once semantics. The flagship product is card_to_crypto: pay with a card via Stripe, receive USDT or USDC on-chain across Tron, Ethereum, Polygon, and BSC networks.

# Production base URL:
https://api.hostracore.com

# Public endpoints (no auth):
- GET /                        — service identity
- GET /health                  — health check (JSON)
- GET /ready                    — readiness probe
- GET /live                     — liveness probe
- GET /version                  — service, version, environment, build, timestamp
- GET /openapi.json             — aggregated OpenAPI 3.0 document for all bounded contexts
- GET /docs                     — Swagger UI (loads /openapi.json)
- GET /llms.txt                 — this file

# Authenticated business endpoints (Bearer api-key or session cookie):
- POST /v1/auth/register        — human signup (public)
- POST /v1/auth/login            — human login (public)
- POST /v1/auth/logout           — revoke session (@auth)
- GET  /v1/auth/me                — current user (@auth)
- PATCH /v1/auth/me               — update profile (@auth)
- POST /v1/auth/verify-email      — verify email (public)
- POST /v1/auth/verify-email/resend — resend verify email (@auth)
- POST /v1/auth/password-reset/request — request reset (public)
- POST /v1/auth/password-reset/confirm — confirm reset (public)
- POST /v1/auth/m2m/register     — self-service merchant + API key (public)

- POST /v1/quotes                — create server-side quote (quotes:write)
- GET  /v1/quotes/{id}            — fetch quote (quotes:read)

- POST /v1/transfers              — create card_to_crypto saga (transfers:write)
- GET  /v1/transfers                — list transfers (transfers:read)
- GET  /v1/transfers/{id}           — fetch transfer (transfers:read)

- POST /v1/settlements             — submit settlement (settlements:write)
- GET  /v1/settlements             — list settlements (settlements:read)
- GET  /v1/settlements/{id}        — fetch settlement (settlements:read)
- POST /v1/settlements/{id}/reverse — reverse settlement (settlements:reverse)

- PUT  /v1/webhooks/endpoint        — register webhook URL+secret (webhooks:write)
- GET  /v1/webhooks/endpoint        — read webhook config (webhooks:read)
- DELETE /v1/webhooks/endpoint      — delete webhook config (webhooks:write)
- POST /v1/webhooks/replay           — re-queue events (webhooks:write)
- POST /v1/webhooks/stripe           — inbound Stripe webhook (Stripe-Signature)

- POST /v1/devices                  — register Expo push token (devices:write)
- GET  /v1/devices                   — list devices (devices:read)
- DELETE /v1/devices/{id}            — revoke device (devices:write)

- POST /v1/notifications/dispatch    — push dispatch (HMAC X-Hostra-Signature)

- GET  /v1/audit/events              — list audit events (audit:read)
- GET  /v1/audit/verify               — verify audit hash-chain (audit:read)

# OpenAPI documents (per context, public):
- GET /v1/auth/openapi.json
- GET /v1/auth/m2m/openapi.json
- GET /v1/settlements/openapi.json
- GET /v1/quotes/openapi.json
- GET /v1/transfers/openapi.json
- GET /v1/webhooks/openapi.json

# What works today:
- Buy USDT and USDC with a card (Stripe)
- Disbursement to Tron, Ethereum, Polygon, BSC
- Server-side quotes with 60s TTL
- Settlement methods: card_charge, card_push, on_chain
- Multi-rail: Visa Direct (OCT), Stripe, crypto custodian
- Double-entry ledger as source of truth
- Tamper-evident audit hash-chain
- M2M API keys with RBAC (11 scopes)
- Outbound webhooks with HMAC-SHA256
- Push notifications via Expo (iOS, Android)
- ISO 8583 / ISO 20022 protocol layer

# In active development (architecture scaffolded):
- Wallet custody (hot/cold/HD)
- Card issuance & management
- Apple Pay / Google Pay
- KYC / KYB / AML
- Payment Links / Invoices / Checkout
- Recurring / Subscriptions
- Crypto-to-fiat (sell)
- Crypto-to-crypto swaps
- ACH / SEPA / SWIFT / Wire
- Mastercard Send
- BTC, Solana
- 2FA / biometrics
- Risk engine / fraud detection

# Architect:
Ildar Lykmanov (Ильдар Лукманов) — machine learning engineer & payment systems architect.

 https://hostracore.com/about

# Technologies:
Go 1.25, PostgreSQL 16, Redis 7, RabbitMQ 3, Docker, Kubernetes, OpenTelemetry, Prometheus, Grafana, Cloudflare

# Contact:
support@hostracore.com