ton-xstocks

xStocks on TON (buy / sell)

Backed xStocks are jettons on TON. Resolve the jetton master from the public xStocks API, then use the same quote → execute flow as ton-swap, with routing preferences learned from real Omniston behavior.

Critical: USDT is the only working swap pair.
Omniston consistently returns no quote for GRAM (ex. TON) → xStock and xStock → GRAM routes.
All xStock buys and sells must go through USDT. If the user lacks sufficient USDT, buy USDT with TON first (see §Pre-fund USDT below).

Key addresses

Token	Jetton master
USDT (TON)	EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

Resolve the TON jetton master for an xStock

1. By symbol (e.g. TSLAx): fetch via curl (not WebFetch — the xStocks API returns 403 for non-standard user-agents):

   curl -s "https://api.xstocks.fi/api/v2/public/assets/{symbol}"
   

   (production base: https://api.xstocks.fi/api/v2 — see xStocks API).

2. In the JSON, find deployments[] where network is "Ton". Use that object's address as the jetton master for MCP (fromToken / toToken).

3. Optional: curl -s "https://api.xstocks.fi/api/v2/public/assets" returns all assets with the same deployments shape.

4. Call get_jetton_info with --jettonAddress <jetton_master> to confirm name / symbol / decimals before swapping.

MCP tools

Action	Tools
Pre-fund USDT	get_jetton_balance (USDT) → get_swap_quote (GRAM (ex. TON) → USDT) → emulate_transaction → send_raw_transaction
Buy xStock	get_swap_quote (USDT → xStock) → emulate_transaction → send_raw_transaction
Sell xStock	get_jetton_balance (xStock) → get_swap_quote (xStock → USDT) → emulate_transaction → send_raw_transaction
Verify	get_jetton_info, get_transaction_status, get_jetton_balance

Amounts for get_swap_quote are human-readable strings (respect jetton decimals from get_jetton_info).

CLI argument names (exact)

Tool	Arg	CLI flag
get_jetton_info	jettonAddress	--jettonAddress
get_jetton_balance	jettonAddress	--jettonAddress
get_swap_quote	fromToken	--fromToken (use "TON" for native GRAM (ex. TON), jetton master address for tokens)
get_swap_quote	toToken	--toToken
get_swap_quote	amount	--amount (human-readable)
get_swap_quote	slippageBps	--slippageBps (default 100 = 1%)
emulate_transaction	messages	--messages (JSON array from quote's transaction.messages)
send_raw_transaction	messages	--messages (same JSON array)
get_transaction_status	normalizedHash	--normalizedHash

Pre-fund USDT (auto, when needed)

Before any xStock trade, check the user's USDT balance:

1. get_jetton_balance for the USDT master address — use the amount field for comparison.
2. If amount < required amount for the planned buy: a. Calculate the shortfall (include a small buffer for price movement). b. get_swap_quote with fromToken = "TON" (the literal string, not an address), toToken = USDT master, amount = shortfall. c. Confirm with the user: "You need ~X USDT but only have Y. Swap Z GRAM (ex. TON) → X USDT first?" d. On approval, send_raw_transaction → poll get_transaction_status until completed. e. Re-check USDT balance before proceeding to the xStock buy.

Buy workflow

1. Resolve the Ton jetton master for the xStock symbol (API above).
2. Check USDT balance — run Pre-fund USDT if insufficient.
3. get_swap_quote: fromToken = USDT master, toToken = xStock master, amount = USDT to spend, slippageBps = 100 (1 %).
4. emulate_transaction with the quote's transaction.messages — verify expected balance changes before sending.
5. Show the user: fromAmount, toAmount, minReceived, expiresAt, emulation results, and note the forward GRAM (ex. TON) on router messages (gas).
6. Confirm once, then send_raw_transaction with the returned transaction.messages.
7. Poll get_transaction_status on normalizedHash until completed or failed.

Do not attempt GRAM (ex. TON) → xStock directly. It will return no quote. Always route through USDT.

Sell workflow ("sell all" or fixed amount)

1. get_jetton_balance for the xStock master → use the returned amount field (already a human-readable decimal string, e.g. "12.5"). Use amountRaw only if a raw integer is needed elsewhere.
2. Pass amount directly as the amount parameter for get_swap_quote — no manual conversion needed.
3. get_swap_quote: fromToken = xStock master, toToken = USDT master.
4. emulate_transaction with the quote's transaction.messages — verify expected balance changes.
5. Show the user the quote details and emulation results, then confirm.
6. send_raw_transaction, then poll get_transaction_status until completed or failed.

Do not attempt xStock → GRAM (ex. TON) directly. Always sell into USDT.

Post-trade checks

• If balance reads 0 immediately after a buy, wait a few seconds and re-query; indexers can lag.
• After a sell, confirm USDT balance increased as expected.

Omniston quirks

• "No quote available" — no route at that size / time. Retry after a short wait, or adjust amount / slippage slightly. Do not switch to GRAM (ex. TON) pairing; it won't help.
• Occasional WebSocket errors (e.g. quote ack) — retry get_swap_quote.
• Quotes expire; if the user waited before confirming, fetch a fresh quote before executing.

Relations

• Execution and confirmation rules: ton-swap skill.
• Wallet funding and status polling: ton-balance skill.
• Issuance / redemption outside DEX: xStocks product docs / dashboard — not covered by MCP swap alone.