[{"data":1,"prerenderedAt":835},["ShallowReactive",2],{"docs:\u002Fv1\u002Fapi\u002Ffinance":3},{"id":4,"title":5,"body":6,"description":828,"extension":829,"meta":830,"navigation":731,"navigationTitle":5,"path":831,"seo":832,"stem":833,"__hash__":834},"docs\u002Fv1\u002Fapi\u002Ffinance.md","Earnings, Payouts and Transactions",{"type":7,"value":8,"toc":820},"minimark",[9,14,29,122,144,149,184,194,331,342,350,354,385,430,434,440,525,557,561,585,634,648,667,671,674,697,739,753,756,760,810,816],[10,11,13],"h1",{"id":12},"earnings-payouts-and-transactions","Earnings, payouts and transactions",[15,16,17,18,22,23,28],"p",{},"All financial endpoints require an owner session (Nano, explicit Base SIWX or verified email). Publishing keys and resource-only wallet proofs have no financial-read or recipient-write authority. Responses use ",[19,20,21],"code",{},"private, no-store"," and the ",[24,25,27],"a",{"href":26},"\u002Fv1\u002Fapi\u002Ferrors#financial-problems","financial problem catalog",".",[30,31,32,45],"table",{},[33,34,35],"thead",{},[36,37,38,42],"tr",{},[39,40,41],"th",{},"Method and path",[39,43,44],{},"Perspective",[46,47,48,59,69,79,92,102,112],"tbody",{},[36,49,50,56],{},[51,52,53],"td",{},[19,54,55],{},"GET \u002Fapi\u002Fv1\u002Fearnings",[51,57,58],{},"Creator union of accepted sales, Post tips and Comment tips",[36,60,61,66],{},[51,62,63],{},[19,64,65],{},"GET \u002Fapi\u002Fv1\u002Fpayouts",[51,67,68],{},"The same creator union, including absent\u002Fblocked outgoing obligations",[36,70,71,76],{},[51,72,73],{},[19,74,75],{},"GET \u002Fapi\u002Fv1\u002Ftransactions",[51,77,78],{},"Buyer's own incoming payment receipts",[36,80,81,86],{},[51,82,83],{},[19,84,85],{},"GET \u002Fapi\u002Fv1\u002Fearnings\u002Fsummary",[51,87,88,91],{},[19,89,90],{},"{summary,total,asOf}"," for the same filters",[36,93,94,99],{},[51,95,96],{},[19,97,98],{},"GET \u002Fapi\u002Fv1\u002F{earnings,payouts,transactions}\u002F:sourceKind\u002F:sourceId",[51,100,101],{},"One owned source",[36,103,104,109],{},[51,105,106],{},[19,107,108],{},"PUT \u002Fapi\u002Fv1\u002Fpayouts\u002F:sourceKind\u002F:sourceId\u002Frecipient",[51,110,111],{},"Explicit binding of an eligible original missing destination",[36,113,114,119],{},[51,115,116],{},[19,117,118],{},"GET \u002Fapi\u002Fv1\u002Fstats",[51,120,121],{},"Creator analytics, separate from raw accounting",[15,123,124,127,128,131,132,135,136,139,140,143],{},[19,125,126],{},"sourceKind"," is ",[19,129,130],{},"sale",", ",[19,133,134],{},"post_tip"," or ",[19,137,138],{},"post_comment_tip",". ",[19,141,142],{},"sourceId"," is the original purchase\u002Ftip UUID; use the pair as the record identity. A payout UUID alone cannot identify all sources. The actual beneficiary of a Comment tip can be its Comment author. Current ownership, Post price and Profile cannot manufacture a historical beneficiary or amount.",[145,146,148],"h2",{"id":147},"exact-record-and-hash-roles","Exact record and hash roles",[15,150,151,152,131,155,131,158,161,162,165,166,131,169,135,172,175,176,179,180,183],{},"History exposes ",[19,153,154],{},"original_beneficiary_id",[19,156,157],{},"approved_beneficiary_id",[19,159,160],{},"effective_beneficiary_id"," and ",[19,163,164],{},"beneficiary_basis"," (",[19,167,168],{},"original",[19,170,171],{},"operator_historical",[19,173,174],{},"unresolved","). ",[19,177,178],{},"beneficiary_id"," equals the effective identity for existing clients. An explicit operator decision can assign an otherwise unknown historical beneficiary; the original field stays null and incomplete original facts remain ",[19,181,182],{},"evidence_state: unresolved",", including after a confirmed creator send. A present-day Post association grants unresolved history visibility only while no effective beneficiary exists. Ordinary account routing cannot replace a historical operator decision.",[15,185,186,187,193],{},"The machine-readable ",[24,188,192],{"href":189,"rel":190},"https:\u002F\u002Fdocs.subnano.ai\u002Fopenapi\u002Fagent-platform-v1.json",[191],"nofollow","FinancialItem schema"," defines every returned field. Principal fields are:",[30,195,196,206],{},[33,197,198],{},[36,199,200,203],{},[39,201,202],{},"Fields",[39,204,205],{},"Meaning",[46,207,208,218,228,238,248,261,271,281,291,301,311,321],{},[36,209,210,215],{},[51,211,212],{},[19,213,214],{},"id,source_kind,source_id,payout_id,purchase_id,kind",[51,216,217],{},"Native source and optional creator payout references",[36,219,220,225],{},[51,221,222],{},[19,223,224],{},"gross_amount_raw,commission_amount_raw,net_amount_raw",[51,226,227],{},"Actual original decimal raw strings, or null if evidence is incomplete",[36,229,230,235],{},[51,231,232],{},[19,233,234],{},"beneficiary_id,recipient_address,resolution_eligible,evidence_state",[51,236,237],{},"Effective beneficiary, bound routing and explicit unresolved\u002Feligible state",[36,239,240,245],{},[51,241,242],{},[19,243,244],{},"created_at,received_at,paid_at",[51,246,247],{},"Incoming acceptance time; creator confirmed-send time is separate and nullable",[36,249,250,255],{},[51,251,252],{},[19,253,254],{},"reference",[51,256,257,258],{},"Original available ",[19,259,260],{},"{post_id,post_title,post_handle,comment_id}",[36,262,263,268],{},[51,264,265],{},[19,266,267],{},"incoming_hash",[51,269,270],{},"Buyer\u002Ftipper send to the allocated source account",[36,272,273,278],{},[51,274,275],{},[19,276,277],{},"receive_hash",[51,279,280],{},"Platform receive into that source account",[36,282,283,288],{},[51,284,285],{},[19,286,287],{},"block_hash",[51,289,290],{},"Creator outgoing send hash; check paid\u002Fconfirmed time for confirmation",[36,292,293,298],{},[51,294,295],{},[19,296,297],{},"commission_hash",[51,299,300],{},"Platform commission outgoing send hash; check its independent state",[36,302,303,308],{},[51,304,305],{},[19,306,307],{},"creator_expected_hash,creator_submitted_hash,commission_expected_hash",[51,309,310],{},"Prepared\u002Fsubmitted evidence, not confirmed payout",[36,312,313,318],{},[51,314,315],{},[19,316,317],{},"commission_status,commission_paid_at,payout_legs",[51,319,320],{},"Independent creator\u002Fcommission operations, statuses, amounts and available hashes",[36,322,323,328],{},[51,324,325],{},[19,326,327],{},"corroborating_hashes,error_message,purchase_card",[51,329,330],{},"Original identity corroboration, unresolved reason and buyer-only legacy card context",[15,332,333,334,337,338,341],{},"Each ",[19,335,336],{},"payout_legs.creator"," includes ",[19,339,340],{},"{operation_id,status,amount_raw,address,block_hash,expected_hash,submitted_hash,confirmed_at}",". The commission leg has the same transfer evidence without a recipient address. Buyer histories redact the creator receiving address. Unknown amounts\u002Fhash\u002Ftimestamps stay null; they are never replaced with today's price, zero, a buyer hash or the other leg's hash.",[15,343,344,345,349],{},"Use arbitrary-precision integers: ",[346,347,348],"strong",{},"gross = fee + net",". 1 XNO = 10^30 raw. The original session snapshots its fee policy; current defaults are 750 basis points for Nano sales, 1500 for USDC sales and 500 for Nano tips, with recorded integer split\u002Frounding. Historical facts govern; never apply one blanket fee to all sources. A missing or nonconserving split is unresolved. Hash presence alone is not payout confirmation.",[145,351,353],{"id":352},"status-and-totals","Status and totals",[15,355,356,357,127,360,131,363,131,366,131,369,131,372,131,375,135,378,381,382,384],{},"Creator ",[19,358,359],{},"status",[19,361,362],{},"pending",[19,364,365],{},"blocked",[19,367,368],{},"processing",[19,370,371],{},"submitted",[19,373,374],{},"needs_reconciliation",[19,376,377],{},"paid",[19,379,380],{},"failed",". Blocked missing-address obligations remain owed without consuming a transfer attempt. Prepared\u002Fsubmitted operations remain visible before native outgoing checkpoints are repaired. ",[19,383,377],{}," requires creator confirmed-send evidence; it does not prove the creator wallet has signed its receive or can spend those funds. A confirmed commission never makes the creator paid. Incoming receipt, platform receive, purchase entitlement and creator payout are independent.",[15,386,387,390,391,394,395,131,398,131,401,131,404,131,407,131,410,131,413,131,416,131,419,422,423,426,427,429],{},[19,388,389],{},"summary"," and each ",[19,392,393],{},"source_breakdown"," entry contain ",[19,396,397],{},"count",[19,399,400],{},"gross_raw",[19,402,403],{},"net_raw",[19,405,406],{},"commission_raw",[19,408,409],{},"earned_raw",[19,411,412],{},"unpaid_raw",[19,414,415],{},"confirmed_sent_raw",[19,417,418],{},"unresolved_count",[19,420,421],{},"last_payout_at",". Known complete facts conserve totals; aggregates affected by unknown splits are null, with unresolved count. Confirmed-sent raw starts at ",[19,424,425],{},"\"0\""," when none are proven. ",[19,428,409],{}," means accepted creator amount owed, not a spendable wallet balance. Totals cover the entire selected scope rather than one page.",[145,431,433],{"id":432},"filters-and-stable-traversal","Filters and stable traversal",[15,435,436,437,28],{},"Lists return ",[19,438,439],{},"{items,total,summary,pagination:{asOf,nextCursor}}",[30,441,442,452],{},[33,443,444],{},[36,445,446,449],{},[39,447,448],{},"Query",[39,450,451],{},"Supported values",[46,453,454,476,485,495,505,515],{},[36,455,456,461],{},[51,457,458],{},[19,459,460],{},"type",[51,462,463,131,466,469,470,131,472,131,474],{},[19,464,465],{},"all",[19,467,468],{},"tip"," (both tip kinds), ",[19,471,130],{},[19,473,134],{},[19,475,138],{},[36,477,478,482],{},[51,479,480],{},[19,481,359],{},[51,483,484],{},"Comma-separated creator statuses",[36,486,487,492],{},[51,488,489],{},[19,490,491],{},"startDate,endDate",[51,493,494],{},"Inclusive ISO date or timestamp; start must not exceed end",[36,496,497,502],{},[51,498,499],{},[19,500,501],{},"limit",[51,503,504],{},"1–50, default 50",[36,506,507,512],{},[51,508,509],{},[19,510,511],{},"asOf",[51,513,514],{},"Nonfuture ISO issuance watermark; optional on first request",[36,516,517,522],{},[51,518,519],{},[19,520,521],{},"cursor",[51,523,524],{},"Opaque continuation returned by the previous page",[15,526,527,528,531,532,535,536,539,540,543,544,546,547,550,551,553,554,556],{},"Rows order by ",[19,529,530],{},"received_at"," descending, ",[19,533,534],{},"source_kind"," in C order descending, then ",[19,537,538],{},"source_id"," descending; unknown dates follow known dates. Retain the same filters\u002Fperspective and copy ",[19,541,542],{},"nextCursor"," verbatim; it preserves ",[19,545,511],{}," and the last position. Wrong filter identity, repeated scalar values, future watermark, malformed cursor or invalid date returns ",[19,548,549],{},"400",". Changing limit is allowed. New accepted sources after ",[19,552,511],{}," do not enter that traversal. Payout status and unresolved evidence can change while traversing; ",[19,555,511],{}," is not a historical database snapshot. Deduplicate by the native pair and restart a fresh traversal for an updated report.",[145,558,560],{"id":559},"usdc-receipts-and-separate-asset-totals","USDC receipts and separate asset totals",[15,562,563,564,567,568,161,571,139,574,576,577,580,581,584],{},"USDC rows identify ",[19,565,566],{},"asset:\"USDC\"",", their exact ",[19,569,570],{},"network",[19,572,573],{},"decimals:6",[19,575,538],{}," is the distinct incoming receipt UUID; ",[19,578,579],{},"purchase_id"," links the shared Post entitlement. Preserve both rather than deduplicating separate transfers by purchase. An exceptional second receipt has ",[19,582,583],{},"receipt_disposition:\"needs_reconciliation\""," and does not create another automatic commission or creator payout.",[15,586,587,588,131,591,161,594,597,598,601,602,604,605,608,609,612,613,131,616,131,619,131,622,131,625,131,628,161,631,633],{},"Read ",[19,589,590],{},"gross_amount_atomic",[19,592,593],{},"commission_amount_atomic",[19,595,596],{},"net_amount_atomic"," for tagged amounts. The legacy ",[19,599,600],{},"*_raw"," fields and ",[19,603,389],{}," remain ",[346,606,607],{},"Nano-only","; a USDC row leaves its Nano amounts null. ",[19,610,611],{},"asset_summaries"," contains one group per asset\u002Fnetwork with exact ",[19,614,615],{},"gross_atomic",[19,617,618],{},"commission_atomic",[19,620,621],{},"net_atomic",[19,623,624],{},"earned_atomic",[19,626,627],{},"unpaid_atomic",[19,629,630],{},"confirmed_sent_atomic",[19,632,418],{},". Never add these groups together.",[15,635,636,637,135,640,643,644,647],{},"Use ",[19,638,639],{},"asset=USDC&network=eip155:8453",[19,641,642],{},"asset=XNO&network=nano-mainnet"," to scope a history. Base Sepolia evidence uses ",[19,645,646],{},"eip155:84532",". Supply both fields together; changing either invalidates the continuation cursor. Untagged requests return both kinds of receipts while retaining Nano scalar totals.",[15,649,650,651,654,655,658,659,662,663,666],{},"The creator obligation remains visible if absent, blocked or submitted. ",[19,652,653],{},"payout_reason"," explains recovery, including missing gas. Buyer access survives a delayed payout. ",[19,656,657],{},"gas_costs"," reports outgoing transaction evidence in ",[346,660,661],{},"ETH wei (18 decimals)",": L2, L1 and operator fees, plus ",[19,664,665],{},"total_fee_wei",". Unavailable fee components and totals stay null; synthetic or incomplete receipts do not establish a zero cost. Creator USDC debt is not reduced by these platform costs. The saved Base destination applies to each frozen sale; the Nano recipient-binding endpoint does not reroute USDC obligations.",[145,668,670],{"id":669},"resolve-an-eligible-missing-recipient","Resolve an eligible missing recipient",[15,672,673],{},"Saving an address affects new allocations. Binding an earlier missing recipient is a deliberate, separate owner action and performs no transfer.",[675,676,677,685,694],"ol",{},[678,679,680,681,684],"li",{},"GET the saved payout address and exact ",[19,682,683],{},"updatedAt"," revision.",[678,686,687,688,691,692,28],{},"Read the financial source. Require ",[19,689,690],{},"resolution_eligible: true"," and your original ",[19,693,178],{},[678,695,696],{},"PUT the source recipient with that exact pair:",[698,699,704],"pre",{"className":700,"code":701,"language":702,"meta":703,"style":703},"language-http shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","PUT \u002Fapi\u002Fv1\u002Fpayouts\u002Fpost_tip\u002F\u003CsourceId>\u002Frecipient\nAuthorization: Bearer \u003CownerAccessToken>\nContent-Type: application\u002Fjson\n\n{\"payoutAddress\":\"\u003Csaved Nano address>\",\"addressUpdatedAt\":\"\u003Cexact saved updatedAt>\"}\n","http","",[19,705,706,714,720,726,733],{"__ignoreMap":703},[707,708,711],"span",{"class":709,"line":710},"line",1,[707,712,713],{},"PUT \u002Fapi\u002Fv1\u002Fpayouts\u002Fpost_tip\u002F\u003CsourceId>\u002Frecipient\n",[707,715,717],{"class":709,"line":716},2,[707,718,719],{},"Authorization: Bearer \u003CownerAccessToken>\n",[707,721,723],{"class":709,"line":722},3,[707,724,725],{},"Content-Type: application\u002Fjson\n",[707,727,729],{"class":709,"line":728},4,[707,730,732],{"emptyLinePlaceholder":731},true,"\n",[707,734,736],{"class":709,"line":735},5,[707,737,738],{},"{\"payoutAddress\":\"\u003Csaved Nano address>\",\"addressUpdatedAt\":\"\u003Cexact saved updatedAt>\"}\n",[15,740,741,742,745,746,749,750,28],{},"The active owner, saved validated address\u002Frevision and original conserving payment evidence are checked under the publication\u002Foperation locks. A source already carrying a destination, attempt or creator send intent cannot be redirected. Success records original source\u002Fbeneficiary\u002Famount and resolution provenance, returns ",[19,743,744],{},"recipientAddress,addressUpdatedAt,resolvedAt,beneficiaryId,amountRaw,status:\"pending\""," plus the saved snake-case evidence. The same binding replays that result; different intent\u002Fstale revision returns ",[19,747,748],{},"409 recipient-resolution-conflict",". Missing\u002Fineligible owner source can return ",[19,751,752],{},"404",[15,754,755],{},"An unresolved original beneficiary\u002Fsplit is never inferred from the current Post or wallet. Such recovery uses an operator-reviewed dry run and separate approval; ordinary account APIs cannot send\u002Fdrain\u002Fretry another user's payout or change fees.",[145,757,759],{"id":758},"creator-analytics","Creator analytics",[15,761,762,765,766,769,770,131,773,131,776,779,780,131,783,131,786,131,789,131,792,131,795,131,798,801,802,805,806,809],{},[19,763,764],{},"GET \u002Fapi\u002Fv1\u002Fstats?window=7d&sort=visits_desc&metrics=visits,unlocks"," returns ",[19,767,768],{},"{rows,trend,top_posts,previous_totals,refreshed_at,window,bucket,metrics}",". Windows: ",[19,771,772],{},"7d",[19,774,775],{},"30d",[19,777,778],{},"lifetime",". Sorts: ",[19,781,782],{},"visits_desc",[19,784,785],{},"unlocks_desc",[19,787,788],{},"comments_desc",[19,790,791],{},"tips_desc",[19,793,794],{},"total_revenue_desc",[19,796,797],{},"unlock_revenue_desc",[19,799,800],{},"tip_revenue_desc",". Metrics: visits, unlocks, comments, tips, total\u002Funlock\u002Ftip revenue XNO, and ",[19,803,804],{},"unlock_revenue_usdc"," (the creator share of USDC sales on this deployment's Base network, never converted into XNO); optional ",[19,807,808],{},"post=\u003CUUID>"," scopes a Post. Invalid window\u002Fsort use defaults; metrics normalize to supported entries. Tips and tip revenue count paid Post tips and paid Comment tips that went to the Post owner, across all history; a tip on a reader's Comment is that reader's. The XNO revenue fields and the revenue sorts never include USDC. Numeric analytics are for reporting; use raw financial history for reconciliation.",[15,811,812,815],{},[19,813,814],{},"previous_totals"," contains every metric above for the immediately preceding 7-day or 30-day period, using the same owner and Post scope. It is null for lifetime or an unavailable comparison.",[817,818,819],"style",{},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":703,"searchDepth":716,"depth":716,"links":821},[822,823,824,825,826,827],{"id":147,"depth":716,"text":148},{"id":352,"depth":716,"text":353},{"id":432,"depth":716,"text":433},{"id":559,"depth":716,"text":560},{"id":669,"depth":716,"text":670},{"id":758,"depth":716,"text":759},"Exact owner financial histories include every confirmed incoming source and its independent payout legs.","md",{},"\u002Fv1\u002Fapi\u002Ffinance",{"title":5,"description":828},"v1\u002Fapi\u002Ffinance","5iOnnwiiuoeyLlWUELzlB1KVQf-QXDTISjlE6wtwCOI",1792473752762]