Account and reader tasks

All paths use https://subnano.ai. 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.

An owner session can come from Nano, explicit Base SIWX, verified email or a server-verified USDC guest purchase. A private checkout credential is narrower: it recovers its original purchases and cannot operate the ordinary account.

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; 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 Base account and recover USDC

Request a fresh explicit SIWX login challenge, sign the exact message locally and claim the same linked owner. Save the renewable pair; new Profile/key creation is unnecessary for returning users. Owner linking is a separate verified action and never silently merges accounts.

For a new USDC purchase, persist the original quote, owner, request key and approved asset/network budget before signing. Persist the exact EIP-3009 proof before submission. After a timeout or 409 usdc-settlement-pending, read the original owned status URL and retry that saved operation; do not sign another transfer. A confirmed receipt grants content even if its creator payout lacks gas. Inspect tagged financial history to distinguish incoming payment, creator debt and outgoing confirmation.

For a previously purchased Post or ZIP, use owner Bearer or request siwx=read on that exact URI and sign its fresh resource-only challenge. This reads the existing entitlement without payment or login, including after withdrawal. Check every ZIP's saved SHA-256 and size. Payment and returning-read contract.

For a first USDC purchase without an owner session, use guest checkout. Save its private credential before the quote, prepare and save the original server guard, then sign only the payment authorization. Verified payment returns the normal owner session and retains the purchase on the wallet's account. Later wallet login in either the browser or API finds the same purchases.

Return to a Nano account

Authority: control of the linked wallet and a fresh explicit signature login challenge. Sign the exact purpose-bound login message locally; no funds, email or broadcast are required. Wallets without local signing can use transfer login: 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. Both flows also work when that account has verified email.

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

For a buyer task, find and assess a Post: use a lexical query and exact raw budget, inspect free preview, creation declarations and ready ZIPs, then validate the current quote at the original Post access URL. Its runnable example stops before spending and documents original-proof recovery.

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

For a research kit, first inspect the published ZIP manifest. The article's one entitlement covers all currently safety-eligible ready ZIPs. Creator upload/recovery and a runnable purchase-once/download example are in the attachment guide.

Authority: reader owner session 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.

Creator authority: a Publishing key with posts:publish. Read private GET /api/v1/tags to reuse your own names, including draft-only or unused names. Create a draft with optional tags: ["What works for Mads", "AI-værktøjer"]. For a published Post, GET its exact revision and PATCH only {"tags":["AI-værktøjer"]} with X-Post-Revision; {"tags":[]} clears and omission preserves assignments. The save is atomic and revision conflicts require readback. Tags preserve case, use NFC/Unicode White_Space normalization, permit 1–64 code points per canonical name and at most 10 raw names. Categories remain separate.

Public authority: none. Open the returned collectionUrl at /@<handle>/tags/<saved-slug>, use the legacy /tags/<tag UUID> entry, or anonymously GET /api/tags/<tag UUID>/posts?page=1&per_page=24. The creator's published matching Posts appear newest first with no drafts or protected paid bodies. Identical names from another creator are separate. The UUID URL survives handle changes; no eligible members means 404, while an empty later page returns 200 and its true total.

MCP: both editions expose subnano_tag_collection. Full local tools add subnano_list_tags and subnano_set_post_tags({post_id,revision,tags}). Published replacements require trusted-terminal grant tags and can later be revoked with revoke tags; --temporary-draft adds no published authority. Save operationId. For post-tags-update, inspect/resume performs readback only, never retries the write or adopts, and keeps currentRevision separate from an unknown original savedRevision. See exact HTTP examples and agent authority/recovery.

Publish and recover a ZIP research kit

Authority: existing Publishing key with posts:publish. Prepare a paid draft and save exact file intent/request key. Reserve JSON at /api/v1/posts/<postId>/attachments/uploads with current X-Post-Revision; reconcile/authorize each fixed part through the original operation's /transport, send only the private capability to the trusted exact Edge endpoint, then /complete. Up to three unequal files total 10 MiB; parts are serial and at most 5 MiB each. Modern 202 is not receipt. Recover the original key across interruption or same-owner key rotation, skip confirmed parts and never resend received bytes. Verify only ready plus currently eligible creator bytes. Stop on held/rejected/failed/cancelled results. Received queued/checking ZIPs may publish, while metadata/downloads await clearance. Existing legacy 3 MiB operations retain their bounded multipart adapter. Exact flow, quotas and example.

Upload and recover hosted images

Authority: active same-owner Publishing key. Save request key, target UUID/kind and inline node key before bytes; Post images also use the latest exact revision. Receive a private 202 and poll the returned status action, or recover by exact request identity after response loss/key rotation. No received bytes are retransferred. Cleared with a null public URL remains progress. Inline needs eligible plus URL and the still-current body save; OG/avatar/header also need current association. Keep the old confirmed image until replacement completes, and cancel superseded/removed selections. Honor current retry timing with a bounded poll budget, then explicitly resume the original operation. Image operation contract, Profile images.

Tip a Post or Comment

Authority: reader owner session 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. 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. 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.

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.