Start · Selling a file
Selling a file
A file is encrypted on your machine before it goes anywhere. Its terms (price, recipients and their shares, and a commitment to the encrypted file) are registered on the Annon contract on NEAR. The encrypted file can then sit on any host.
There are two ways to sell:
| Hosted, with a shop | Self-hosted | |
|---|---|---|
| Command | annon share, MCP annon_share |
annon sell, MCP annon_sell |
| Who stores the encrypted file | The shop's host | You |
| What you get | A purchase URL | A .pay2 file to put on your own server |
Set up the CLI first: install, configuration, backup secret and wallet, as in quickstart.md.
Hosted: annon share
annon shop add https://shop.example --id SHOP_ID
annon share report.pdf --price 1.00 --shop SHOP_ID --title "Q3 report" --description "40 pages"
--shop names a shop from your local configuration; without it the CLI uses defaultShop. Adding a
shop grants no trust. Before the first share, give that shop a deployment profile in your
configuration (network, contract, RPCs, relayer and host) that matches the deployment you use:
without one the CLI stops with trust_required, and a mismatch stops it with config_conflict
(CLI.md).
What happens, in order:
- The CLI encrypts the file locally and works out the final terms and split without sending anything.
- It shows the final terms and asks you to type
yes: seller, host, contract, price, the split with the relayer's fee share, and for a NEAR seller the listing storage and purchase storage it will pay. Nothing is saved or signed before you approve. - It saves an encrypted record of the sale and a backup of it before any signature or transaction. Keep the backup secret and the original file: resuming needs both.
- You sign the upload. The encrypted file goes to the shop's host, which checks it and reserves a place for it.
- For an EVM seller, the shop's host creates the file's split contract on Base at its own gas cost.
- The terms are registered on NEAR. EVM and Solana sellers sign once and the shop's relayer submits and pays. NEAR sellers send the transactions from their own wallet and pay the storage.
- The host publishes the file. The result is
fileId, the purchaseurl, theheaderURL andexpiresAt, when the shop stops hosting the file (Unix seconds, ornullwhen the shop plans no expiry). The lifetime is the shop's policy; the SDK sets no maximum.
Each shop sets its own upload and listing limits and file lifetime. annon shops shows the rules a
shop publishes in its manifest, and annon share prints them again with the result. The demo's
open pool allows up to 10 upload admissions and 2 sponsored listings per wallet and per IP bucket per
UTC day. Listed sellers have a separate allowance of 20 per wallet per day. Hosted files normally
expire seven days after publication; keep your own copy. Limits and refusal codes:
shops-and-limits.md.
The whole price goes to you, minus the relayer's fee share on a sponsored listing. share takes no
--split; for several recipients, use annon sell.
A NEAR seller pays two amounts in NEAR: listing storage (--listing-storage, default 0.01) and the
file's purchase storage (--storage-budget, default 0.2, enough for about 19 sales). With
--json, give both flags or set listingStorage and storageBudget in the configuration. Agents always use the configured values.
If a step stops, resume the saved sale with the same file; never start a second one for the same file:
annon share report.pdf --resume 0xFILE_ID --shop SHOP_ID
Resume keeps the original terms and checks the chain before it repeats any step, so a transaction whose outcome is unknown is never sent twice blindly.
An unfinished verified upload is kept for 24 hours from body verification. After that, requests
return upload_expired. The host permits restaging unfinished uploads, but this does not guarantee
that every saved CLI checkpoint can resume automatically. Keep the original file and saved seller
state; if resumption cannot finish, serve the same registered ciphertext from another host. A file
that was published and later expired cannot be republished on that host under the same file ID.
With --json and in agent mode there is no prompt. A relayer fee above your maxProtocolFee then
stops the share with protocol_fee_above_max before anything is saved or signed.
For web pages, the browser SDK runs the same sale: createBrowserSeller from
@defdone/annon/browser quotes without signing, saves the backup first, and resumes after a closed
tab. Selling from the browser in the demo shop is pending release. We open it once the acceptance tests
pass with NEAR, EVM and Solana wallets.
Self-hosted: annon sell
sell encrypts a file into a .pay2 file and registers its terms. You put the .pay2 file behind a
server that answers with the 402 offer and serves the file to proven buyers.
apps/demo-host is a complete one; serveFile from the SDK is the building block.
With a NEAR account
You send the transactions and pay the storage yourself. No protocol fee is added.
annon sell report.pdf --wallet near --price 1.00 --split near:YOUR_ACCOUNT.near:10000 --storage-budget 0.05 --output report.pay2
annon budget 0xFILE_ID
Prepay contract storage with storage_deposit first, as in
quickstart.md. --storage-budget gives the file NEAR
for the storage each purchase needs. Check it with annon budget before you share the URL, and add
more with annon fund 0xFILE_ID 0.05 --wallet near. Costs and the reasons behind them:
near-accounts.md.
With an EVM or Solana wallet
An EVM or Solana seller signs the registration, and a relayer submits it and pays the NEAR. The relayer adds its fee share to the split and the CLI shows the final split before it registers.
annon sell report.pdf --wallet evm --price 1.00 --split evm:0xYOUR_ADDRESS:10000 --output report.pay2
A relayer decides which registrations it sponsors. defdone's relayer sponsors files that its shop
hosts, which is what annon share uses, and the sellers it lists. For a self-hosted file with an
EVM or Solana wallet, run your own relayer (apps/relayer) or use the hosted path.
Otherwise registration stops with not_sponsored before anything is sent.
Which routes your buyers get
| Seller | Routes | Base payments |
|---|---|---|
EVM wallet, all recipients EVM, with Base terms (share, or sell --base) |
near, base, 1click |
Go to the file's split contract on Base, which pays the same shares |
| EVM wallet without Base terms | near, 1click |
Buyers with USDC on Base use 1click with Base as the source chain |
| NEAR account | near, 1click |
None. Buyers with USDC on Base pay through 1click with Base as the source chain |
| Solana wallet | near, 1click |
As for NEAR |
Payments on NEAR wait in the contract until anyone calls settle, which credits each recipient's
NEAR Intents account. From there a recipient can withdraw to other chains.
With annon sell, --base adds Base terms. It needs a local EVM key, all-EVM recipients and a little
ETH on Base, because your wallet creates the split contract. With annon share, the shop's host
creates it, and NEAR and Solana sellers get no Base terms.
Splits and fees
- Recipients are
kind:id:bps, for exampleevm:0x1111111111111111111111111111111111111111:7000,near:alice.near:3000. Shares are basis points and total 10000. Up to 8 recipients. The first recipient gets the rounding remainder. - A sponsored listing adds the relayer's treasury share: on defdone's relayer 0.03 USDC plus 1% of
the price. The other shares are scaled down to make room. The config field
maxProtocolFeecaps what you accept. - The terms of a listed file never change. To change the price or the split, stop sales and list again.
Fees in general: shops-and-limits.md.
After listing
annon stop 0xFILE_IDstops new sales for good. Earlier buyers keep their access.- A moderator, if you name one with
--moderator account.near, can stop new key releases for the file. Buyers must accept that moderator before they pay. - Keep your own copy of the original file. A hosted file expires when the shop's file lifetime ends.
- Previews:
sellcan build a PAY2 file with a preview, but clients do not verify previews for buyers in this release. Do not present a preview as checked.