Nano payout address

A validated saved receiving address is required before any Post becomes public, including free Posts because readers can tip them. Drafts may be created before setup. The rule applies to publication, republication and edits that leave a Post public across the API, website and database. Legacy public Posts remain readable and can be unpublished while their owner completes setup. An idempotent acknowledgement of an already public Post creates no new publication.

The login sender wallet and the saved payout destination are distinct settings; login never fills this value automatically. Generate a receiving wallet locally. Keep its seed and private keys local; send Subnano only its public receiving address. Nano checksum validation establishes a valid address, not control of its wallet. Compare it with your wallet before saving.

Credential and recovery

Both endpoints require an active owner accessToken from Nano or verified email login, never the snpk_ Publishing key. No cookies are needed. Returning users request a fresh session through Nano login or optional email login; registration and another Publishing key are unnecessary.

GET /api/v1/profile/payout-address
Authorization: Bearer <accessToken>

200 returns { "payoutAddress": null, "updatedAt": null } if no private Profile exists, or the saved address and its ISO revision timestamp. Preserve the timestamp exactly, including fractional seconds, for historical recipient binding.

PUT /api/v1/profile/payout-address
Authorization: Bearer <accessToken>
Content-Type: application/json

{"payoutAddress":"<your locally generated Nano receiving address>"}

200 returns { "payoutAddress": "nano_..." }. Only payoutAddress is accepted; whitespace is trimmed, valid nano_ and xrb_ addresses work, empty/null and extra fields return 422. Repeating the same PUT is safe without a request key. Different concurrent saves use the last successful database write; GET confirms the final value.

A new address affects future payment allocations. It never changes a saved session's recipient, an existing queued destination or a prepared block. Saving it alone does not settle earlier blocked obligations. Read owner earnings; eligible original missing recipients can be bound explicitly using their saved address revision. Incomplete historical beneficiary/split evidence requires operator reconciliation.

Publication without readiness returns 422 payout-address-required. Correct the address, then retry the exact publication with the same Idempotency-Key; a setup failure does not consume the completed publish receipt. New purchase/tip sessions also check the actual beneficiary: a tip to a Comment author checks that author, rather than an unrelated Post author. Already allocated sessions retain their frozen facts and recovery path.

Errors and limits

Payout-address responses use Cache-Control: private, no-store and application/problem+json: 400 malformed JSON, 401 invalid/expired/unconfirmed/anonymous owner credential or Publishing key, 404 Publishing API disabled, 422 invalid fields, 429 rate limit, 500 server error. Readiness dependency failure returns 503; never interpret it as an empty address.

Limits include 120 account-session authentication attempts/IP/minute, 120 address reads/account/minute, and 10 saves/account/minute. Respect any Retry-After seconds. Trusted ingress must replace X-Forwarded-For. The release runbook covers legacy address classification and database enforcement; these docs do not claim production rollout has run.