docs › Paper trading and the safety model

Paper trading and the safety model

The PAPER ticket, the simulated wallet, the confirm gate, and the invariants real trading will have to keep.

Trading in dexterm today is PAPER only: a simulated wallet priced from live, keyless Jupiter quotes. Nothing is signed, no key is held, no transaction is sent, and the paper code imports no wallet or signing library of any kind. Every ticket and positions frame says so in a banner that is never hidden.

The ticket#

B or S on a token opens a buy or sell ticket. It shows the side, the size (SOL or % of balance when buying; % of the position when selling), slippage in bps, and a rolling Jupiter quote refreshed every 5 s while you edit: what you pay, what you receive, price in SOL and USD, price impact, the simulated fee, the route and the minimum received. Keys: digits type, tab switches field, ←/→ flips the side, u toggles the unit, ⏎ reviews, esc cancels.

The confirm gate is on by default. ⏎ arms the order; y (or ⏎ again) confirms. For a notional above 1 SOL you must type the size back digit for digit before the confirm counts. Any other key during the confirm step cancels the arm: a stray key can never confirm, and q or a screen number cannot navigate out from under an armed order. The fill is computed from a fresh quote at confirm time, never from the quote on screen, and is booked into the paper wallet in one SQLite transaction. If Jupiter rate-limits during the confirm the ticket says so, retries for up to 8 s, then lands in an error state you can retry or cancel; it never hangs.

The wallet#

• starts at 10 SOL (configurable), persisted in the same SQLite file as the cache and watchlist (--db; :memory: for a throwaway session);
• books every fill append-only with the simulated fee (5 000 lamports per fill, labelled as a simulation);
• marks positions from DexScreener's USD price over the live SOL price every 10 s on the positions screen;
• shows a ◈ POSITION · PAPER row under the chart on any token you hold, and the same row plus entry line and fill markers in the chart popup.

The analyst can open a PAPER ticket for you (open_ticket, pre-filled, editing phase) when you ask it to buy or sell. It cannot size it past what you typed, arm it or confirm it; it tells you to confirm yourself.

What a real trade will have to keep#

Real non-custodial execution is designed and partly built in a branch, and not live. These are the invariants from the spec that any live path must hold before it ships; they are listed here so you can hold us to them:

1. Non-custodial. You hold the keys. dexterm builds, simulates and hands off; your wallet signs. The Phantom bridge design stores only your public key.
2. Keypress gate on by default. Models and voice create proposals; arming needs a physical keypress or a wallet approval. Opting out, if ever offered, needs an explicit "this is less safe" confirmation, is local, logged and reversible, and the signer caps still apply.
3. Caps live in the signer, not the UI. The signer re-simulates and re-checks every transaction (per-trade and daily USD caps, price-impact ceiling, a positive description of what a Jupiter swap looks like: exactly one route instruction, no token transfers, burns or approvals to anyone) and refuses out of policy even if the UI, the model or a popup is compromised.
4. The AI has no interface to the signer. No build, sign or send tool exists for the model; its only write-shaped tool opens a PAPER ticket.

Until all of that is verified end to end, the PAPER ticket is the only trade path in the app and the features page says so.