---
title: Account and reader tasks
description: Choose the credential, execute a bounded task, inspect saved state and recover without duplicate effects.
navigationTitle: Task workflows
---

# 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](https://docs.subnano.ai/openapi/agent-platform-v1.json) and the linked references. [Start Here](https://docs.subnano.ai/v1/api/overview) chooses the credential; [creator quickstart](https://docs.subnano.ai/v1/api/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](https://docs.subnano.ai/v1/api/authentication).

## 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](https://docs.subnano.ai/v1/api/authentication#manage-publishing-keys).

## Return to a Base account and recover USDC

Request a fresh [explicit SIWX login challenge](https://docs.subnano.ai/v1/api/wallet-signatures#base-siwx-login-and-wallet-linking), 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](https://docs.subnano.ai/v1/api/finance#usdc-receipts-and-separate-asset-totals) 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](https://docs.subnano.ai/v1/api/payments#returning-owner-and-siwx-reads).

For a first USDC purchase without an owner session, use [guest checkout](https://docs.subnano.ai/v1/api/payments#guest-usdc-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](https://docs.subnano.ai/v1/api/wallet-signatures). Sign the exact purpose-bound login message locally; no funds, email or broadcast are required. Wallets without local signing can use [transfer login](https://docs.subnano.ai/v1/api/authentication#nano-login-without-email): 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](https://docs.subnano.ai/v1/api/account#change-and-confirm-email), 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](https://docs.subnano.ai/v1/api/buyer-discovery): 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](https://docs.subnano.ai/v1/api/engagement).

## Buy a Post and recover an uncertain payment

For a research kit, first inspect the published [ZIP manifest](https://docs.subnano.ai/v1/api/attachments#inspect-first-purchase-once-download-every-file). 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](https://docs.subnano.ai/v1/api/attachments).

**Authority:** reader owner session and an authorized local wallet. Persist a request identity, then issue:

```http
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](https://docs.subnano.ai/v1/api/payments#native-purchase-sessions).

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](https://docs.subnano.ai/v1/api/payments#x402-protected-reads-and-assets).

## Organize related Posts and share a collection

**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](https://docs.subnano.ai/v1/api/posts#creator-owned-tags)
and [agent authority/recovery](https://docs.subnano.ai/v1/api/mcp#organize-posts-with-tags).

## 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](https://docs.subnano.ai/v1/api/attachments).

## 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](https://docs.subnano.ai/v1/api/images), [Profile images](https://docs.subnano.ai/v1/api/profile).

## 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](https://docs.subnano.ai/v1/api/payments#post-and-comment-tips).

## 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](https://docs.subnano.ai/v1/api/finance).

## 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](https://docs.subnano.ai/v1/api/engagement#comments-replies-and-reports).

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](https://docs.subnano.ai/v1/api/engagement).

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](https://docs.subnano.ai/v1/api/account#change-and-confirm-email).

## 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](https://docs.subnano.ai/v1/api/payments#author-gift-links).

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](https://docs.subnano.ai/v1/api/posts#delete-post), [withdrawal](https://docs.subnano.ai/v1/api/publish#unpublish-post).

## 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](https://docs.subnano.ai/v1/api/errors).