# stoka
> x402 v2 pay-per-request storage for encrypted private blobs on Stellar. Project home: stoka.space.

stoka is designed for autonomous software. Every JSON response is merged with `service: stoka`, `audience: agent`, and `api_family: stoka-x402-v1`. Paid routes return HTTP 402 with a machine-readable `accepts` array (scheme `exact`, network `stellar:testnet`, USDC asset contract, pay-to, maxAmountRequired). Wallet-signed routes use `Authorization: Stellar <pubkey>:<challenge_id>:<sig_hex>` over a single-use challenge.

## Resolve paths on this host (marketing + docs)
- /.well-known/stoka.json — service manifest: x402 config (facilitator URL, network, scheme, asset, pay_to), pricing formula, routes list. Legacy aliases: /.well-known/stoka, none.
- /docs/ — unified documentation: guides, x402 protocol walkthrough, HTTP API reference, and per-language client docs.
- /docs/guide/http-api — full HTTP API reference: x402 lifecycle, wallet-signed lifecycle, every route, headers, 402 body shape, error matrix.
- /docs/guide/x402 — the x402 protocol explained in one page.
- /docs/clients/python/ — stoka Python client package.
- /docs/clients/go/ — stoka Go client package (github.com/ajbeach2/stoka-go).
- /docs/clients/typescript/ — stoka TypeScript client package (Node + browser).
- / — human landing page with quickstart and pricing.
- /dashboard.html — wallet-signed GET /v1/me/usage charts (sessionStorage only).

## Paid routes (x402 v2, USDC on stellar:testnet)
1. `POST {api}/v1/store` — headers `X-Stoka-Key: <key>`, `Content-Type: application/octet-stream`, `Content-Length` required. Body is the raw encrypted blob. First call returns 402 with the exact price; retry with `X-PAYMENT: <base64(PaymentPayload)>`. 200 returns `{id, owner_pubkey, size_bytes, expires_at, ttl_seconds, charged_atomic}` plus an `X-PAYMENT-RESPONSE` header (base64 SettleResponse).
2. `GET {api}/v1/retrieve/{key}` — optional `X-Stoka-Owner: <pubkey>` header for an exact 402 quote. 200 returns raw octet-stream bytes plus `X-Stoka-Owner-Pubkey` and `X-Stoka-Expires-At` headers. 404 before 402 when the key does not exist for the verified payer.
3. `PUT {api}/v1/object/{key}` — raw octet-stream body replaces the existing blob. Same pricing and 404 semantics as store.

## Wallet-signed routes (free; Ed25519 over a single-use challenge)
1. `POST {api}/v1/auth/challenge` with JSON `{"audience": "object-delete" | "profile-bind" | "me-usage"}` → `{challenge_id, message}`. Sign `message` with your Stellar wallet.
2. `DELETE {api}/v1/object/{key}` with `Authorization: Stellar <pubkey>:<challenge_id>:<sig_hex>` (audience `object-delete`). 204 (idempotent).
3. `POST {api}/v1/profile` with JSON `{wallet, challenge_id, signature_hex, email?}` (audience `profile-bind`). Optional email bind/clear.
4. `GET {api}/v1/me/usage?days=1..90` with the same Authorization header (audience `me-usage`). Returns per-UTC-day atomic USDC counters.

## Typical agent bootstrap
1. Fetch `/.well-known/stoka.json` and read `x402.asset`, `x402.pay_to`, and the pricing formula.
2. `POST /v1/store` without `X-PAYMENT` — inspect the 402 body's `accepts[0].maxAmountRequired`.
3. Build a Soroban USDC `transfer` auth entry for that amount to `accepts[0].payTo`; sign with your Stellar wallet (auth-entry signing). Encode the full `PaymentPayload` as base64 and set `X-PAYMENT`.
4. Resend the request. On 200, parse the JSON response body (includes the new blob `id`) and the `X-PAYMENT-RESPONSE` header for the settlement receipt.
5. To retrieve, repeat with `X-Stoka-Owner: <your_pubkey>` for an exact quote; the verified payer must equal the stored owner pubkey.

## Notes
- Bodies are opaque to the server; encrypt client-side.
- Blobs expire 30 days after their last successful retrieval (`BLOB_TTL_SECONDS` on the operator side). Reading refreshes the TTL; `X-Stoka-Expires-At` on the 200 response reports the new expiry.
- Hard size cap is `MAX_OBJECT_BYTES` (default 350 000). Requests above it get 413 before any 402 challenge is issued.
- `Content-Length` is required on paid writes; chunked uploads get 411.

## Facilitator
Every 402 challenge advertises `extra.areFeesSponsored: true`, so the payer signs the Soroban authorization entry but doesn't pay network fees. The facilitator URL is published in `/.well-known/stoka.json → x402.facilitator_url`; clients just follow the x402 protocol, they don't need to know which facilitator is wired up.