Account and reader tasks

All paths use https://subnano.me. Save request identities, resource IDs and private receipts before continuing. Every task below names its authority and readback. Exact fields, statuses and limits are in OpenAPI and the linked references. Start Here chooses the credential; creator quickstart gets to the first publication.

Return to an email account

Authority: authorized mailbox, then the returned owner session. POST /api/v1/auth/login with {email}; its generic 202 reveals no account existence. Read the mailbox code and POST /api/v1/auth/verify with {email,code}. Save the pair, GET /api/v1/me and confirm the original Profile ID. Existing identity and keys remain.

Refresh with POST /api/v1/auth/refresh and {refreshToken}. Serialize renewal and atomically replace both tokens. After a lost response, retry only under the provider's reuse policy; if renewal fails, ordinary mailbox login recovers that same account. It does not create an unknown account. POST /api/v1/auth/logout under the owner token revokes that session's renewal; another independent session remains usable. Session errors, CAPTCHA and limits.

Recover a lost Publishing key

Authority: owner session (Nano or verified email); mutations need its active account session. GET /api/v1/api-keys exposes metadata without secrets. Identify the key from the lost creation receipt, then deliberately POST /api/v1/api-keys/<keyId>/rotate with {}. Save the replacement key immediately. This replacement works even at the five-active-key cap and revokes the original atomically.

If rotation's response is lost, list metadata again before any further action: the old key is already inactive. The secret cannot be retrieved. For new key creation, persist Idempotency-Key and body; identical completed replay returns original metadata with 409 key-already-issued, not another secret. POST .../<keyId>/revoke affects only the selected owned key. Key management.

Return to a Nano account

Authority: control of the linked sending wallet and a fresh explicit Nano login challenge. Create with a saved requestSecret, send the small positive proof payment once, then claim with the saved loginSecret. Save the wallet pair and verify session.user.id and /api/v1/me match the original account. Existing Posts, purchases, follows and keys remain on that ID. This also works when that account has verified email; no mailbox access is required.

Refresh with /api/v1/auth/refresh and {refreshToken}; serialize requests and save replacements atomically. Wallet lost-response retry has a 10-second window and requires the replacement to still be current. Older-token replay revokes that family; prove the wallet again. Logout revokes that wallet family's access immediately and leaves another independent session usable. Email can be added optionally, without replacing Nano login or making it a prerequisite for publication.

Browse and read public discussion

Authority: public. GET /api/posts?q=<search>&access=all&author=all&page=1&per_page=12, choose a published Post UUID, then GET /api/posts/<postId>. Catalog pages return {data,total,page,perPage}; per_page permits 1–48. Traverse and deduplicate UUIDs. Empty out-of-range requests can return page 1, so stop using the actual pagination rather than blindly incrementing.

GET /api/posts/<postId>/comments?limit=20 reads the visible discussion without an account; use its returned continuation with the same Post/thread. Public Post and Comment reaction summaries use canonical reads. Authenticated caller context adds only that caller's reaction/relationship fields. An unpublished or hidden resource does not become public through discussion routes. Discussion pagination and credentials.

Buy a Post and recover an uncertain payment

Authority: reader owner session (Nano or verified email) and an authorized local wallet. Persist a request identity, then issue:

POST /api/v1/purchases/create
Authorization: Bearer <reader owner accessToken>
Idempotency-Key: <saved purchase request identity>
Content-Type: application/json

{"postId":"<published Post UUID>"}

Save purchase.id, the exact quote/expiry, ephemeral_address.ephemeral_address and statusUrl. Sign/send only the quoted amount from the local wallet under its spending authority. Poll the supplied status URL with the same owner credential; no second payment is justified by a missing response. An exact issuance replay recovers the original allocation; different intent under that identity returns 409.

On paid, GET /api/posts/<postId>/access and /api/assets/<assetId> with the reader owner token. Inspect actual content/file bytes. Creator payout may still be blocked; entitlement remains paid. POST /api/v1/purchases/<purchaseId>/claim returns the registered owner's receipt with session:null; it never switches identity. Cancel a pending session with /cancel; retain its quote and monitor context because a previously sent payment may arrive late. Payment statuses and cancellation.

For stateless x402, GET the protected Post access URL without credentials to receive 402 and PAYMENT-REQUIRED. Save the quote, resource and exact locally signed proof. Submit PAYMENT-SIGNATURE to that original resource. After confirmed settlement, replay the identical proof for that Post and its protected assets. A foreign resource or invalid signature/work is rejected. Preserve the original block/hash and reconcile the wallet frontier after uncertainty; do not sign a second transfer just because the HTTP response was lost. x402 quote, signing and replay.

Tip a Post or Comment

Authority: reader owner session (Nano or verified email) plus an authorized local wallet. Persist a new request identity and POST /api/v1/posts/<postId>/tips/session with the selected native tip body. A Comment tip uses /comments/<commentId>/tips/session and the actual Comment beneficiary. Save the returned session ID, quote and canonical status URL; send the quoted amount once, then poll.

An uncertain issue/claim response is recovered against that original source and exact request identity. Incoming receipt, platform receive and beneficiary outgoing send are separate. Do not infer delivery from a prepared hash. Desired amount, preset/custom rules and cancellation use the tip contract.

Reconcile money and eligible historical routing

Authority: owner session (Nano or verified email). GET /api/v1/transactions for owned outgoing receipts; /api/v1/earnings and /api/v1/payouts for creator obligations. Lists return {items,total,summary,pagination:{asOf,nextCursor}}. Retain filters and asOf, copy nextCursor verbatim until null, and deduplicate (source_kind,source_id). limit permits 1–50. A failed financial read is not zero earnings.

Use integer raw strings: gross = commission + net, 1 XNO = 10^30 raw. Unknown original amounts stay null. Inspect incoming, platform receive, creator and commission hashes independently. paid means confirmed creator outgoing send; wallet receive/spendability is a separate step.

If an original complete obligation has resolution_eligible:true, GET the saved payout address/revision and deliberately PUT /api/v1/payouts/<sourceKind>/<sourceId>/recipient with {payoutAddress,addressUpdatedAt} under an active owner session. Identical binding replays; stale/changed intent returns 409. Binding records routing and sends no Nano. An already attempted/bound leg cannot be redirected. Exact evidence, filters and routing.

Participate and configure your account

Authority: owner session (Nano or verified email). Append a Comment/reply with POST /api/v1/posts/<postId>/comments and a saved request identity; read the saved native Comment/thread. Desired-state PUT target /reactions sets or clears the selected supported reaction. DELETE /api/v1/comments/<commentId> permits owned deletion or allowed Post-author moderation. Bodies, reply depth, limits and conflict recovery.

PUT /api/v1/follows/<creatorId> sets the desired follow state; save the returned follow ID for partial alerts at /api/v1/follows/preferences/<followId>. Read public lists/counts and the owned preference result. GET/PUT /api/v1/notification-preferences saves global channels and privacy; device permission is separate. Poll /api/v1/notifications, deduplicate IDs, mark selected/context/all owned rows read and use per-Post mute routes. Saved preference fields and feed limits.

For email change, use the active owner session on /api/v1/account/email, read pending state, submit the actual mailbox code or confirmation URL to /verify, then read until verified. Save any returned renewable pair. A foreign mailbox code is not ownership proof for this account. Email confirmation and recovery.

Share a gift and withdraw or delete a Post

Authority: owner session for gift management; Publishing key for Post lifecycle. GET/POST /api/v1/posts/<postId>/gift-link reads or creates the eligible link; repeated creation reuses the active native link. Keep the secret private. Its recipient accesses only the allowed Post/assets with that active token and gains no permanent purchase. DELETE the gift link to disable it; test that protected reads now fail. Gift eligibility and consumption.

POST /api/v1/posts/<postId>/unpublish under the Publishing key withdraws the same Post; confirm owned/public readback. DELETE an eligible draft to remove it. Financially referenced or allocated Posts return 409 financial-history-retained; withdraw instead, retaining payment/media history. Deletion, withdrawal.

Choose the next action after a failure

401: recover the correct credential. 409: read the saved resource and reconcile the named conflict before another mutation. 429: honor Retry-After when supplied and use bounded backoff. For uncertain payments, keep the original quote/proof/source; inspect persisted receipt and the local wallet before signing again. Publication, key issuance and native payment routes have different replay rules. Error families and per-operation recovery.