paperneed
papertrade removed the orderbook. paperneed removes the LP. Every position is written by a bonded seller who won a 30-second auction on the haircut and escrowed 10x the margin before the open.
The mechanism
papertrade lets you trade against the house: one LP, built from users' losses, takes the other side of every trade and pays winners from a queue when it runs short. paperneed lets you be the house, and it has no LP: the other side of each position is a seller who bid for it and put the money up front.
You say what you want: "1000x long BTC, 1 hour, 0.1 USDC". Your margin goes into the escrow. For 30 seconds sellers bid the haircut down, the share of your gain they keep if you win: 4%, then 3%, then 2.2%. The lowest bid wins, but only from a seller whose USDC bond holds 10x your margin free; that cover is locked before the position opens, so the largest gain you can make is already in escrow and no payout queue can form. With no bid, your margin comes back in full.
Every figure
| Assets | BTC, ETH and SOL against USD, long or short. |
|---|---|
| Leverage | 1 to 1000x. |
| Margin | 0.01 to 5 USDC per paper while the market is young. The position is a slug: fixed margin, no top-up. |
| Duration | 5 minutes to 24 hours. |
| Max haircut | The highest share of your gain you accept, 4% unless you say otherwise. |
| Auction | 30 seconds from the post; lowest haircut wins; ties go to the earlier bid. |
| Cover | 10x the margin, locked from the winner's USDC bond at the open. The gain is capped at the cover. |
| Bust | entry - entry x (1/leverage - 0.05%) for a long, + for a short. At 1000x that is a 0.05% move; at 100x, 0.95%. |
| Win | The haircut stays with the seller; 1% of the net gain goes to Need, split 60% clean-fill pool, 25% origin, 15% reserve; the rest and your margin come back to you. |
| Loss | The lost margin goes to the seller minus 2%; the 2% buys $NEED through Jupiter and goes to you. |
| Checks | The keeper reads Pyth every 10 seconds for every open paper. |
Price, bust and close
Prices come from Pyth through Hermes: the BTC/USD, ETH/USD and SOL/USD feeds. At the open the keeper reads the latest price and writes the feed id, the price, its exponent and its publish time into the open record; that price is the entry. A paper closes in one of three ways, each at the Pyth price of that moment, written into the close record the same way:
- you close it: your wallet signs a close request (a zero USDC transfer into the escrow with your memo; Need pays the fee);
- it reaches its duration;
- the price crosses the bust price on one of the 10-second checks: the full margin goes to the seller, minus the 2% that buys you $NEED.
Settlement
Everything is paid from the escrow in the same transaction as the close record. With M the margin, L the leverage, h the winning haircut and C = 10 M the cover:
Example: 0.1 USDC at 100x long, written at 2.2%, closed after a 0.5% rise. G = 0.05, H = 0.0011, the fee is 0.000489 USDC (0.000293 to the pool, 0.000122 to the origin, 0.000074 to the reserve), and you receive 0.148411 USDC. The same paper after a 0.3% fall: Lo = 0.03, 0.0006 USDC buys $NEED for you, the seller's bond gains 0.0294 and you get 0.07 back. Before $NEED trades, the 2% is paid in USDC and the record says so.
Sellers bond USDC (and $NEED, the existing seller bond). A seller that disappears after winning cannot hold up a close, because its cover is already in the escrow and the keeper settles from it.
The house actors
So the live site always has a counterparty for small paper, the house seller quotes a haircut from the realised volatility of the last 60 Hermes prices of the asset, between 1.5% and 4%, bids within 5 seconds of a post, and writes at most 2 USDC of cover at a time. It does not bid over your max haircut or past its cover. The house trader posts one paper an hour (100x, 10 minutes, 0.05 USDC, random side and asset) so the board moves. Both carry the house tag on the board.
The records
Each step is a Memo signed by the keeper key, read back with getSignaturesForAddress on that key, like every other Need record. Amounts are µUSDC; prices are Pyth mantissas with their exponent.
A bid is signed over sha256("bid-paper" ‖ keeper ‖ paperId u64 ‖ seller ‖ haircutBps u32 ‖ validUntil i64 ‖ nonce u64), the way offers on intents are signed. The keeper records the winning bid and up to two runners-up in the open transaction.
Write paper with the SDK
writePaper binds you if it wins: 10x the margin is locked from your USDC bond at the open. The board and every book are plain JSON at /api/v1/paper and /api/v1/paper/:id.
MCP and x402
The MCP server has a post_paper tool: give it a sentence or the fields and a buyer address, sign the transaction it returns, and call it again with signed. Without the SDK, one x402 call does the same: POST /api/v1/paper with the sentence and the buyer answers 402 with the margin as the USDC requirement and the paper transaction to sign; send it back in X-PAYMENT and the answer carries the paper id.
