@oracle-agent/oracle 0.1.0

package/skills/oracle-meme-token-sniper/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: oracle-meme-token-sniper
+description: Scan and prepare guarded meme-token launch/sniping trades across configured chains; fail-closed, user-signed, sell-sim first.
+---
+
+# Oracle meme-token sniper
+
+Use when a user asks Oracle to find, monitor, or prepare buys for meme tokens,
+new launches, liquidity adds, bonding curves, or "snipe" opportunities on any
+supported chain.
+
+## Scope
+
+Oracle may scan every configured venue/chain for meme-token launch signals:
+
+- EVM factory/pair/pool creation logs across configured chains.
+- Liquidity additions, first swaps, tax/owner-risk changes, holder distribution.
+- Solana SPL/token-launch feeds and Jupiter-route availability when configured.
+- Chain-specific launchpads/bonding curves only after the venue is verified.
+- Smart-wallet early-entry overlap and repeat deployer history.
+
+Unsupported chain/venue means `UNAVAILABLE`, not fake coverage. A chain with no
+verified executable route can still be analyzed, but cannot be prepared for buy.
+
+## Required gate before any prepared buy
+
+1. Resolve exact chain, token mint/contract, pool, quote asset, router/venue.
+2. Verify token identity from live chain data, not only a ticker/social link.
+3. Check deployer/owner controls, mint/freeze/blacklist/tax/proxy risks where
+   the chain exposes them.
+4. Confirm liquidity exists and is not only a fake/self pool.
+5. Run sellability / reverse-route simulation when the chain/venue supports it.
+6. Quote fresh, net of gas, and bind slippage/deadline to the prepared artifact.
+7. Enforce user caps: per-trade spend, chain, venue, token, max fee, and TTL.
+8. Return unsigned/user-signable transaction only. No model-authored calldata
+   bypass, no raw user calldata, no backend custody by default.
+
+## Autonomous mode
+
+Autonomous meme sniping is allowed only as a capped local-user signer loop:
+
+- separate burner/session key, never main wallet
+- explicit user opt-in and scope
+- max spend per token and per day
+- denylist/allowlist support
+- retry ceiling and kill switch
+- first-run paper/shadow mode
+- receipt/balance reconciliation after every fill
+
+Default public posture is advisory/prepare-only. "Snipe" in UI copy means fast
+scan + prepared ticket; it does not mean blind broadcast.
+
+## Output contract
+
+For every candidate, return:
+
+- `chain`, `token`, `pool`, `venue`
+- `signal`: launch/liquidity/smart-wallet/social/etc.
+- `risk`: PASS/WARN/BLOCK/UNKNOWN with evidence
+- `sellability`: PASS/FAIL/UNKNOWN/UNAVAILABLE
+- `route`: quote source and freshness
+- `prepared`: true only if a guarded unsigned artifact exists
+- `whyBlocked` when not prepared
+
+## Pitfalls
+
+- Treating ticker match as identity.
+- Buying before sell-sim/reverse-route proof.
+- Using scanner membership as an execution allowlist.
+- Calling a launchpool real when reserves are virtual/stale.
+- Ignoring gas: on small meme trades, gas can dominate edge.
+- Letting "every chain" become "every venue is executable". Coverage must be
+  capability-labeled per chain.

package/skills/oracle-nft-gacha-launch/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: oracle-nft-gacha-launch
+description: Use when designing or preparing NFT collections, mint pages, reveal mechanics, and gacha-style pack/loot drops.
+---
+
+# NFT and gacha launch builder
+
+Use this when a user wants to launch an NFT collection, pack opening, loot box,
+claim pass, or randomized reveal product.
+
+## Product shape first
+
+State the launch mechanics before code:
+
+- asset standard: ERC-721, ERC-1155, Ordinals collection, SPL/NFT, or hybrid
+- supply, per-wallet caps, allowlist/public phases, price, treasury, royalties
+- reveal style: instant, delayed, commit-reveal, VRF-backed, or fully deterministic
+- pack/gacha odds and whether duplicates are possible
+- admin powers: owner, pauser, metadata updater, withdrawer, upgrader
+
+## Safety rails
+
+- User signs every deploy/mint/admin transaction; Oracle prepares and simulates.
+- Randomness must be honest. Do not use miner/block timestamp as gacha randomness.
+- Publish odds for gacha/loot mechanics and keep them deterministic/auditable.
+- No hidden mint, owner reroll, metadata rug, or unbounded treasury withdrawal.
+- Per-wallet caps and phase windows are enforced on-chain when material.
+- Marketplaces are secondary: floor price is not a guaranteed bid.
+- Public mint bots enforce gas-war limits across chains: total gas cap, optional
+  per-unit fee cap, and optional priority-fee cap before returning unsigned
+  mint calldata. Missing caps fail closed.
+
+## Build checklist
+
+1. Choose the boring audited base contract unless novelty is required.
+2. Write the authority model in plain language.
+3. Add tests for mint limits, payment/refund, reveal, withdraw, and admin changes.
+4. Simulate deploy and first mint before returning unsigned transactions.
+5. Produce metadata schema, asset pipeline, and provenance hash/manifest.
+6. Prepare marketplace setup only after contract addresses and metadata are stable.
+
+## Gacha-specific checks
+
+- Show odds table and expected value in user terms.
+- Cap max spend per wallet/session.
+- Separate entertainment mechanics from investment claims.
+- If jurisdictional gambling risk is plausible, flag it and keep the launch
+  non-custodial/transparent rather than pretending it is just an NFT mint.

package/skills/oracle-nft-mint-gas-war/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: oracle-nft-mint-gas-war
+description: Guard public NFT mint bots with chain-wide gas-war caps before any wallet-signed mint transaction is returned.
+---
+
+# Oracle NFT mint gas-war guard
+
+Use when a public Oracle lane prepares NFT mint transactions or runs a mint bot
+across configured chains.
+
+## Rule
+
+A mint bot may move fast, but it must not bid uncapped gas.
+
+Every prepared mint transaction must carry a gas envelope that fits the user's
+explicit grant or bot policy:
+
+- `maxTotalGasWei` / grant `maxGasWei`: total gas spend cap (`gasLimit * maxFeePerGas` or `gasLimit * gasPrice`)
+- optional `maxFeePerGasWei`: per-unit fee cap
+- optional `maxPriorityFeePerGasWei`: tip cap for gas wars
+- chain id: required and bound to the prepared transaction
+
+Missing caps fail closed. A mint returning calldata without gas caps is not
+public-safe.
+
+## Implementation hook
+
+Use `validateNftMintGasWar()` or `assertNftMintGasWar()` from the public package
+before returning a wallet-signable NFT mint transaction.
+
+```js
+import { assertNftMintGasWar } from "oracle-agent";
+
+assertNftMintGasWar({
+  chainId,
+  tx: { gasLimit, maxFeePerGas, maxPriorityFeePerGas },
+  policy: {
+    grant, // may provide maxGasWei
+    maxFeePerGasWei,
+    maxPriorityFeePerGasWei,
+  },
+});
+```
+
+## Public behavior
+
+- PASS: return the unsigned mint transaction with the gas verdict fields.
+- BLOCK: show the cap breached and ask the user to raise the cap or skip.
+- Never silently widen gas during a gas war.
+- Never treat mint price cap as gas cap; mint value and gas spend are separate.
+- Never backend-sign public mints. User wallet or explicit self-hosted session
+grant signs.
+
+## Verification
+
+Run:
+
+```bash
+node --test test/nft-gas-war-guard.test.mjs test/package-surface.test.mjs
+```
+
+Full public release gate still requires `npm test`, package dry-run, and secret
+scan before publishing.

package/skills/oracle-polymarket/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: oracle-polymarket
+description: Use for Polymarket prediction markets — event pricing, books, and resolution risk via the public CLOB and Gamma APIs.
+---
+
+# Polymarket
+
+Read through Oracle's data plane (`poly-public` provider: CLOB + Gamma REST, no
+key). Settles on Polygon (137).
+
+## Ops
+
+| Need | Op |
+|---|---|
+| market list | `markets` |
+| events | `events` |
+| order book | `book` |
+| midpoint | `midpoint` |
+| spread | `spread` |
+| last price | `price` |
+
+## A price is not a probability
+
+0.62 means the last trader transacted there — net of fees, liquidity constraints,
+and whoever is hedging an off-platform position. Before treating it as a forecast:
+
+- **depth** — 0.62 on $40 of size carries no information
+- **spread** — wide means nobody defends an opinion
+- **time to resolution** — a 3-day market and a 3-month market at the same price
+  are not saying the same thing
+- **fee drag** — round-trip costs eat thin edges
+
+## Resolution text is the real risk
+
+The most expensive mistake here is not mispricing probability. It is being *right*
+about the world and *wrong* about the resolution criteria.
+
+Read the rules before discussing edge. Flag:
+
+- ambiguous wording that could settle against the consensus reading
+- who resolves it and on what source
+- what happens on an edge case, a delay, or a cancelled event
+- whether the market can resolve early
+
+If the rules could plausibly settle the "obviously right" side as a loss, that is
+the headline, not a footnote.
+
+## Correlated markets
+
+Related markets often disagree. A set of outcome prices summing well past 1.00 is
+either a fee/liquidity artifact or a genuine inconsistency. Check the sum before
+calling something mispriced.
+
+## Hard rules
+
+1. Read the resolution criteria before discussing edge.
+2. Never present a market price as your own forecast without saying which you mean.
+3. Quote depth alongside price.
+4. You prepare; the user's wallet signs.
+5. Receipts or it didn't happen.

package/skills/oracle-protocol-builder/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: oracle-protocol-builder
+description: Use when the user wants Oracle to act as a builder: scaffold contracts/apps, prepare unsigned deploys, and create launch runbooks.
+---
+
+# Protocol builder
+
+Oracle can be a builder, not only a trader/analyzer. The boundary stays the same:
+it writes and prepares; the user signs and deploys.
+
+## Builder modes
+
+- scaffold contracts and tests
+- scaffold mint/gacha/claim pages
+- build DEX/pool/router integrations
+- write deploy and verify scripts
+- produce unsigned deploy or admin transactions
+- create launch runbooks and monitoring dashboards
+- audit authority, upgradeability, fees, and emergency controls
+
+## Required order
+
+1. Authority model: owner, admin, upgrader, pauser, treasury, withdrawer.
+2. Threat model: what can go wrong and who can rug or halt.
+3. Tests: caps, payments, roles, upgrades, withdrawals, randomness, routing.
+4. Simulation: deploy, initialize, and first user action.
+5. Prepare: unsigned artifact only, bound to chain and destination.
+6. Receipt: deployed address, source verification, event logs, and state readback.
+
+## Refusal line
+
+Refuse hidden drains, honeypots, wash-trading systems, undisclosed tax switches,
+fake TVL, or any contract whose main purpose is deceiving buyers.
+
+## Output standard
+
+Lead with the authority model and irreversible choices. Then the file plan or
+artifact. End with the exact tests/simulations run and what remains unverified.

package/skills/oracle-protocol-security/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: oracle-protocol-security
+description: Use before preparing any contract deploy or reviewing protocol code. Authority model first, then the vulnerability checklist.
+---
+
+# Protocol security
+
+Deploys are permanent. This skill runs **before** code is written, not after.
+
+## Authority model comes first
+
+Before reviewing a single line of logic, answer these in plain language:
+
+1. **Who owns it** after deployment — owner, admin, upgrader, pauser, treasury
+2. **What is upgradeable**, and who can upgrade
+3. **What is immutable** once live
+4. **What breaks if the deployer key is lost** — or is stolen
+5. **What an attacker gains** from each privileged function
+
+If a contract mints privileged roles to an address, **name that address** and make
+the user confirm it is the intended one. A deploy that hands ownership to the wrong
+key is unrecoverable.
+
+## Review checklist
+
+| Area | What to actually check |
+|---|---|
+| access control | every privileged fn gated; no missing modifier |
+| initialization | can `initialize` be front-run or called twice? |
+| reentrancy | state written *before* external calls |
+| external calls | return values checked; no blind `call` |
+| integer handling | unchecked blocks justified individually |
+| approvals | exact amount, never unlimited by default |
+| upgrade path | storage layout compatible; gap reserved |
+| emergency stop | exists, and someone can actually reach it |
+| oracle use | manipulation cost vs the value it secures |
+| withdrawal | can funds ever be stranded? |
+
+## Prefer boring
+
+A fork of an audited contract with a small, reviewed diff beats elegant clean-room
+code. If you propose something novel, justify why the boring option fails.
+
+## Verify, never assume
+
+- Explorer contract **names are not verification**. Clones share names.
+- Confirm bytecode exists: `eth_getCode` returning `0x` means nothing is deployed
+  there. Codesize 2 is an empty stub.
+- Confirm constructor-bound addresses (factory, WETH, router) match what you
+  expect — read them back from the deployed contract.
+- Verify a router or venue from the protocol's **own API or docs**, per chain, and
+  record how and when you verified it.
+
+## Deploy discipline
+
+Review → simulate → prepare **unsigned** → user signs. Never house-sign. The
+destination allowlist applies to deploy targets like any other destination.
+
+Decode constructor arguments and read them back to the user in plain language
+before they sign. "Trust the calldata" is not consent.

package/skills/oracle-public-product/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: oracle-public-product
+description: Use for Oracle public product UX/copy: non-custodial, prepare-first, graph/evidence-led, no operator framing.
+---
+
+# Oracle public product
+
+Use this when writing Oracle public docs, console copy, landing pages, launch notes,
+or capability-pack language.
+
+## Positioning
+
+Oracle is a public multichain crypto agent interface:
+
+- trader: quote, route, simulate, prepare, and verify receipts
+- builder: scaffold contracts/apps and prepare unsigned deploy/admin txs
+- analyzer: token, contract, venue, wallet, and market research
+- scanner: chain scanners and smart-wallet boards
+- non-EVM lanes: Solana and Bitcoin/Ordinals where supported
+
+The product voice is user-facing. Do not describe internal operator plumbing,
+private wallets, VPS paths, hot-wallet ops, or house execution.
+
+## Custody copy
+
+Always state the invariant clearly:
+
+- Oracle prepares; the user's wallet signs.
+- Broadcast needs explicit user/grant authority.
+- Prepare is not sign. Sign is not broadcast.
+- Server API keys are scoped agent keys, not wallet keys.
+
+## Forbidden public framing
+
+- no autonomous custody promises
+- no hidden operator signer references
+- no guaranteed-profit or floor-guarantee claims
+- no "we execute for you" without the grant/user-wallet boundary
+- no references to private infrastructure, hostnames, paths, or internal agents
+
+## Output standard
+
+Lead with what the user can do. Then name the guardrail. Keep it concrete and
+short: capability, boundary, evidence.

package/skills/oracle-receipts/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: oracle-receipts
+description: Use whenever reporting the outcome of any on-chain action. Enforces that a claim of success carries a hash, a receipt, and a balance delta.
+---
+
+# Receipts or it didn't happen
+
+The failure mode this prevents: an agent says "done, swapped 0.5 ETH for USDC" when
+the transaction reverted, was never broadcast, or landed with a different output
+than promised. The user then acts on a false balance.
+
+## The rule
+
+A money-moving action is **complete** only when you can show:
+
+1. **transaction hash** — the real one, from the broadcast response
+2. **receipt status** — `1`. A receipt with status `0` is a *failed* transaction
+   that still consumed gas; that is not success
+3. **balance delta** — the output token balance actually changed, read back after
+   the receipt
+4. **the log** proving the intended event fired (`Swap`, `Transfer` to the right
+   recipient, `OrderFilled`)
+
+Missing any of the four → report what you have and call it incomplete.
+
+## Language discipline
+
+| Don't say | Say |
+|---|---|
+| "swapped" (before receipt) | "prepared" / "broadcast, awaiting receipt" |
+| "done" | "receipt 1, balance +NNN USDC, hash 0x..." |
+| "it should have gone through" | "unknown — no receipt yet" |
+| "approved and swapped" | name each transaction separately |
+
+**Preparing is not signing. Signing is not broadcasting. Broadcasting is not
+confirmation.** Four distinct states; never collapse them in a report.
+
+## Multi-step actions
+
+An ERC-20 swap is at minimum two transactions: `approve` then the swap. Report each
+separately with its own hash. If the approve landed and the swap reverted, the
+honest report is "allowance set, swap failed" — not "swap failed" (the user now has
+a live allowance they should know about).
+
+For a raw-pair or multi-leg route: funding a pool is **not** a buy. Until the swap
+call itself has a receipt, the tokens are sitting somewhere they can be taken.
+
+## When it fails
+
+Say what failed, the revert reason if you have it, and what you tried. Never
+substitute a plausible-looking result for one you could not obtain. A reported
+blocker is useful; an invented success is a loss.

package/skills/oracle-rfq-tokenized-assets/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: oracle-rfq-tokenized-assets
+description: RFQ/intent routing across supported chains and guarded buys for tokenized Robinhood assets when user keys/routes are configured.
+---
+
+# Oracle RFQ + tokenized asset routing
+
+Use when a user asks for RFQ, solver/intent quotes, request-for-quote execution,
+or buying tokenized Robinhood-style assets/stocks on supported chains.
+
+## RFQ scope
+
+Oracle should treat RFQ as another best-execution source, not a bypass:
+
+- Query RFQ/intent venues where the chain and token pair are supported and the
+  user has configured any required API keys.
+- Compare RFQ quotes against AMM/aggregator routes on net received after gas,
+  fees, solver spread, and settlement assumptions.
+- Return `artifactKind` precisely: signed typed-data order vs unsigned tx vs
+  wallet-provider action.
+- Re-quote immediately before prepare/signing. RFQ expiry/nonce is short-lived.
+- Do not fabricate RFQ support for a chain without a configured venue.
+
+## Every-chain rule
+
+"Across all chains" means every configured chain is attempted and capability-labeled:
+
+- `RFQ_READY`: venue configured, quote live, prepare path verified.
+- `QUOTE_ONLY`: quote available, but no reviewed prepare path.
+- `UNCONFIGURED`: needs user API key or venue credentials.
+- `UNAVAILABLE`: no RFQ venue for that chain/token pair.
+- `BLOCKED`: policy, unsupported asset, compliance, or route guard rejected.
+
+Unsupported is an honest result, not a failure to hide.
+
+## Tokenized Robinhood assets
+
+Treat tokenized Robinhood assets as normal on-chain assets plus extra identity/risk
+checks:
+
+1. Resolve the exact chain and contract/mint from the official issuer/venue or a
+   user-provided contract. Never infer from ticker alone.
+2. Check asset metadata, decimals, supply, issuer/proxy/admin controls, transfer
+   restrictions, and redeemability/custody disclosures when public.
+3. Verify the venue/router can quote and prepare the asset on that chain.
+4. For buys, run the same route and slippage guard as any ERC-20/SPL swap.
+5. For sells, run sellability/reverse route first; tokenized assets may trade like
+   wrappers and can have restricted-transfer or allowlist rules.
+6. User signs; Oracle does not custody or guarantee redemption.
+
+## Output contract
+
+Return a table per chain/venue:
+
+- chain / venue / asset id
+- RFQ status and expiry
+- gross quote, estimated gas/fees, net output
+- artifact kind and signing path
+- policy blockers
+- confidence and data timestamp
+
+## Pitfalls
+
+- Calling a solver/RFQ quote "gasless" when the cost is hidden in spread.
+- Using an RFQ quote after expiry.
+- Treating a tokenized stock ticker as identity without contract provenance.
+- Ignoring transfer restrictions that make buys possible but exits blocked.
+- Routing tokenized Robinhood assets through DEMI/RH private executor by default;
+  public users must use their own wallet/key/API setup.

package/skills/oracle-smart-wallet-scanner/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: oracle-smart-wallet-scanner
+description: Use when finding, scoring, or monitoring smart wallets from on-chain behavior across tokens, NFTs, and venues.
+---
+
+# Smart-wallet scanner
+
+Use this for on-chain wallet intelligence: early buyers, profitable exits, repeat
+edge, copy-radar, cabal detection candidates, and wallet boards.
+
+## Smart wallet definition
+
+A wallet is not smart because it bought one winner. Require repeatable evidence:
+
+- early across multiple unrelated assets
+- profitable realized exits, not just mark-to-market bags
+- enough trade count and not only one ticker
+- entry before broad social consensus
+- exits before liquidity drain or sell imbalance
+- behavior survives fees, gas, and failed trades
+
+## Scan pattern
+
+1. Start from live events: pair creates, swaps, mint transfers, order fills,
+   marketplace sales, bridge inflows.
+2. Normalize wallet, chain, token/NFT, time, size, and realized PnL.
+3. Cluster funding and common recipients separately; do not call it a bundle
+   without launch-block clustering and common-funder evidence.
+4. Score wallets by multi-asset repeatability and drawdown, not raw largest win.
+5. Track holds vs exits. A smart buyer becoming a smart seller changes the signal.
+6. Emit confidence and evidence window with every wallet label.
+
+## Output standard
+
+For each wallet surface:
+
+- address and chain
+- sample wins/losses
+- realized PnL basis and limitations
+- first-seen timing vs launch/volume
+- current holdings/exit state if known
+- confidence: high / moderate / low / unknown
+
+## Hard rules
+
+- Never expose a private operator wallet as a public smart-wallet seed.
+- Never use one-token PnL as a primary smart label.
+- Cabal candidates are seeds for deeper analysis, not proof of manipulation.
+- If sell data is unavailable, label PnL `UNKNOWN`, not profitable.

package/skills/oracle-solana/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: oracle-solana
+description: Use for Solana research and swap preparation — Jupiter routes, SPL accounts, simulation, blockhash expiry.
+---
+
+# Solana
+
+Read and prepare through Oracle's data plane (`solana-rpc`, `jupiter`). No key
+required. Signing happens in the user's wallet; Oracle returns unsigned
+transactions.
+
+## Ops
+
+| Need | Op |
+|---|---|
+| SOL balance | `getBalance` |
+| SPL accounts | `tokenAccounts` |
+| fresh blockhash | `latestBlockhash` |
+| dry run | `simulate` |
+| route price | `jupiter.quote` |
+| unsigned swap tx | `jupiter.prepare` |
+
+## Blockhash expiry is the trap
+
+A Solana transaction carries a recent blockhash and dies in roughly 60–90 seconds.
+
+Consequences that catch people:
+
+- a transaction prepared two minutes ago is **dead** — re-prepare, don't retry
+- do not prepare, go do other tool work, then hand it over
+- if the user takes a while to approve, prepare again
+
+An expired transaction fails with a confusing error that looks like a routing bug.
+It isn't.
+
+## Simulate every time
+
+`simulateTransaction` is cheap and tells you the actual failure before the user
+signs. There is no reason to skip it. Check:
+
+- does it succeed at all
+- compute units consumed (near the limit → it will fail under load)
+- logs for the real revert reason
+
+## Account creation costs rent
+
+Swapping into a token the wallet has never held requires creating an associated
+token account, which costs SOL rent. Budget it, and say so — a wallet with exactly
+enough SOL for the swap will fail on the account creation.
+
+## Decimals are not standard
+
+Nine is common, six is common, others exist. Read the mint. Assuming decimals is how
+an amount ends up 1000x off.
+
+## Hard rules
+
+1. **Simulate before returning any transaction for signature.**
+2. **Never relay a caller-supplied RPC** — a hostile endpoint can lie about
+   simulation.
+3. **Return unsigned only.** Never a fully-signed transaction.
+4. **Solana authority is separate from EVM authority.** No EVM key satisfies a
+   Solana grant.
+5. Name the **mint address**, not just the ticker.
+6. Receipts or it didn't happen — confirmed signature or it failed.

package/skills/oracle-solana-nft/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: oracle-solana-nft
+description: Research Solana NFT collections and prepare unsigned Magic Eden buy, list, and mint transactions.
+---
+
+# Solana NFT lane (Magic Eden)
+
+Use when someone asks Oracle to check a Solana NFT collection's floor, find
+listings, buy an NFT, list one they hold, or mint from a launchpad drop.
+
+## Tiers
+
+| Op | Key needed | What it returns |
+|---|---|---|
+| `stats` | none | floor in SOL, listed count, 24h volume |
+| `listings` | none | mint, seller, auctionHouse, tokenATA, price |
+| `tokenListings` | none | listings for one specific mint |
+| `prepareBuy` | `MAGICEDEN_API_KEY` | unsigned base64 transaction |
+| `prepareList` | `MAGICEDEN_API_KEY` | unsigned base64 transaction |
+| `prepareMint` | `MAGICEDEN_API_KEY` | unsigned base64 transaction |
+
+Reads are keyless. Instruction builders need the user's own Magic Eden key. If
+the key is missing, say so plainly and stop; do not fake a ticket.
+
+## Flow for a buy
+
+1. `desk.solana.nftStats({ symbol })` - confirm the collection is real and get
+   the floor.
+2. `desk.solana.nftListings({ symbol, limit })` - pull live listings. The
+   cheapest listing is the first one when sorted by price.
+3. Set `maxPriceSol` from the user's stated ceiling, not from the floor. The cap
+   is checked before any network call, so a listing that moved above the ceiling
+   is rejected without touching the API.
+4. `desk.solana.nftPrepareBuy({ buyer, seller, auctionHouse, tokenMint, tokenATA, priceSol, maxPriceSol })`.
+5. Simulate the returned base64 through `desk.solana.simulate` before handing it
+   over. A prepared transaction that fails simulation is a prepared loss.
+6. Hand the user the unsigned transaction. Their wallet signs and sends.
+
+## Rules
+
+- Floor price is not a bid. Buying fills at the listing price, which can move
+  between the read and the signature.
+- Always pass `maxPriceSol`. Without it there is no ceiling on a mint or buy.
+- Collection symbols are validated as slugs. `../` and empty strings are
+  rejected, not encoded into a URL.
+- Every prepare returns `signingReady: false` and `broadcastReady: false`. Oracle
+  never signs a Solana transaction and never sends one.
+- Solana lamports are integers. `priceSol` is decimal SOL; the module converts.
+
+## Verification
+
+`npm run e2e:solana-bitcoin` hits live Magic Eden reads, a live Jupiter quote,
+a live prepared swap, and a live simulation, then asserts the prepare posture
+held.