ton-org/kit

ton-xstocks

Buy or sell Backed xStocks (tokenized equities, e.g.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/ton-org/kit --skill ton-xstocks

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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

TokenJetton 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):
bash
   curl -s "https://api.xstocks.fi/api/v2/public/assets/{symbol}"

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

  1. In the JSON, find deployments[] where `network` is `"Ton"`. Use that object's `address` as the jetton master for MCP (fromToken / toToken).
  1. Optional: curl -s "https://api.xstocks.fi/api/v2/public/assets" returns all assets with the same deployments shape.
  1. Call get_jetton_info with --jettonAddress <jetton_master> to confirm name / symbol / decimals before swapping.

MCP tools

ActionTools
Pre-fund USDTget_jetton_balance (USDT) → get_swap_quote (GRAM (ex. TON) → USDT) → emulate_transaction → send_raw_transaction
Buy xStockget_swap_quote (USDT → xStock) → emulate_transaction → send_raw_transaction
Sell xStockget_jetton_balance (xStock) → get_swap_quote (xStock → USDT) → emulate_transaction → send_raw_transaction
Verifyget_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)

ToolArgCLI flag
get_jetton_infojettonAddress--jettonAddress
get_jetton_balancejettonAddress--jettonAddress
get_swap_quotefromToken--fromToken (use "TON" for native GRAM (ex. TON), jetton master address for tokens)
get_swap_quotetoToken--toToken
get_swap_quoteamount--amount (human-readable)
get_swap_quoteslippageBps--slippageBps (default 100 = 1%)
emulate_transactionmessages--messages (JSON array from quote's transaction.messages)
send_raw_transactionmessages--messages (same JSON array)
get_transaction_statusnormalizedHash--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.
du même dépôt

Autres Skills

Tous les Skills