xstocks

# xStocks Hardcoded catalog of **104 xStocks tokens** on Solana. No API calls or network access needed to list, filter, or look up tokens. For **price discovery and swaps**, use **Jupiter** ([github.com/jup-ag/agent-skills](https://github.com/jup-ag/agent-skills)) with the Solana mint address from this skill. ## Available scripts - **`scripts/search.py`** — Search, filter, and look up xStocks tokens on Solana ## Typical flows **List all tradable xStocks:** ```bash python3 scripts/search.py ``` **Filter by name or symbol:** ```bash python3 scripts/search.py --filter "apple" ``` **Get the Solana mint address for a token:** ```bash python3 scripts/search.py --filter "tesla" --address-only ``` **Reverse lookup — mint address to token info:** ```bash python3 scripts/search.py --lookup "svm:XsDoVfqeBukxuZHWhdvWHBhgEHjGNst4MLodqsJHzoB" ``` **Full JSON output (for piping or programmatic use):** ```bash python3 scripts/search.py --json python3 scripts/search.py --filter "nvidia" --json ``` ## Buy xStocks **IMPORTANT: Once the user confirms an amount, execute the entire buy flow immediately in one pass. Do NOT stop after confirming — proceed straight through steps 1–5 without waiting for further user input.** 1. **Resolve the mint** — run `scripts/search.py --filter "TOKEN" --address-only` to get the Solana address. 2. **Confirm with the user** — show amount, token name, and mint address. Ask the user to confirm. 3. **Once confirmed, execute immediately without pausing:** - **Build the swap** — use the **standard Jupiter quote + swap flow** (`jupiter_swap` tool, or `/quote` + `/swap` REST endpoints). **Do NOT use Jupiter Ultra** (`/ultra/...` endpoints) — Ultra transactions are not compatible with external signers. - **Sign and broadcast** — use your wallet tools (we recommend lobster.cash). If no wallet tool is configured, return the mint address so the user can execute with their own wallet. 4. **Report outcome** — only claim success when transaction status is `success` or `completed`. Share transaction ID and explorer link. Do not say "confirmed" or "I'll buy now" and then wait. Confirmation from the user means: execute the swap right now. Default to **USDC** for payments. Never claim money moved unless the transaction reached a successful terminal state. ## Gotchas - **Do not pause between confirmation and execution.** When the user says "yes" or provides an amount, execute the swap immediately. Never reply with "confirmed" and then wait for another prompt. - **Never use Jupiter Ultra** (`/ultra/...` endpoints) for xStocks swaps. Ultra transactions are not compatible with external signers. Use the standard `/quote` + `/swap` flow instead. - Token addresses include a `svm:` prefix (e.g., `svm:XsbEh...`). Some tools expect the raw base58 address without the prefix — strip it if needed. - The catalog is hardcoded. If a new xStock launches and isn't found, check [api.xstocks.fi](https://api.xstocks.fi/api/v1/token) for the latest list. - Default to **USDC** as the input token for purchases. Never claim money moved unless the transaction reached a successful terminal state (`success` or `completed`). ## Tool selection | User intent | Action | |-------------|--------| | List xStocks | `python3 scripts/search.py` | | Find/filter xStocks | `python3 scripts/search.py --filter "QUERY"` | | Get mint address | `python3 scripts/search.py --filter "QUERY" --address-only` | | Reverse lookup by mint | `python3 scripts/search.py --lookup "ADDRESS"` | | Buy xStock | Resolve mint → **Jupiter standard swap** (not Ultra) → sign & broadcast | | Wallet setup | Use your wallet tools before transacting |