xstocks-beta

Search, list, and resolve xStocks tokens on Solana mainnet, and list wallet holdings; use with Jupiter for price and trading functionality.

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) 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:

python3 scripts/search.py

Filter by name or symbol:

python3 scripts/search.py --filter "apple"

Get the Solana mint address for a token:

python3 scripts/search.py --filter "tesla" --address-only

Reverse lookup — mint address to token info:

python3 scripts/search.py --lookup "svm:XsDoVfqeBukxuZHWhdvWHBhgEHjGNst4MLodqsJHzoB"

Full JSON output (for piping or programmatic use):

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 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