@ton/mcp 0.1.15-alpha.2 → 0.1.15-alpha.21

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@ton/mcp",
-  "version": "0.1.15-alpha.2",
+  "version": "0.1.15-alpha.21",
   "description": "TON MCP Server - Model Context Protocol server for TON blockchain wallet operations",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "bin": "./bin/mcp.js",
   "exports": {
     ".": {
       "import": {
@@ -38,6 +37,7 @@
     "dist",
     "skills",
     "llms.txt",
+    "USAGE_EXAMPLES.md",
     "README.md"
   ],
   "keywords": [
@@ -50,29 +50,36 @@
   "author": "TON Tech",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ton-connect/kit"
+    "url": "https://github.com/ton-org/kit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@ston-fi/omniston-sdk": "^0.7.9",
+    "@ton/core": "^0.63.1",
+    "@ton/crypto": "^3.3.0",
+    "https-proxy-agent": "^9.0.0",
+    "undici": "8.0.2",
+    "ws": "^8.20.0",
     "zod": "^3.25.76",
-    "@ton/walletkit": "0.0.10"
+    "@ton/walletkit": "1.0.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1"
   },
   "devDependencies": {
-    "@types/node": "^22.15.29",
-    "@vitest/coverage-v8": "^4.0.17",
-    "rimraf": "^6.1.0",
-    "rolldown": "1.0.0-rc.2",
-    "typescript": "~5.9.3",
-    "vitest": "^4.0.17"
+    "@types/node": "^25.6.0",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.1.7",
+    "rimraf": "6.1.3",
+    "rolldown": "1.0.2",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.4"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "pnpm build:clean && rolldown -c && pnpm build:types && pnpm build:chmod",
+    "build": "pnpm build:clean && rolldown -c && pnpm build:types",
     "build:clean": "rimraf dist",
     "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
     "build:chmod": "chmod +x dist/cli.js",
@@ -82,6 +89,10 @@
     "lint": "eslint src --max-warnings 0",
     "lint:fix": "eslint src --max-warnings 0 --fix",
     "test": "vitest run",
+    "clean": "git clean -xdf dist node_modules .turbo",
     "typecheck": "tsc --noEmit"
+  },
+  "bin": {
+    "mcp": "./bin/mcp.js"
   }
 }

package/skills/ton-balance/SKILL.md

@@ -15,11 +15,11 @@ Read-only queries for wallet balances, token holdings, and transaction history o
 | ---- | -------- | -------- |
 | `get_wallet` | — | `walletSelector` |
 | `get_balance` | — | `walletSelector` |
-| `get_balance_by_address` | `address` | — |
+| `get_balance_by_address` | `address` | `walletSelector` |
 | `get_jetton_balance` | `jettonAddress` | `walletSelector` |
 | `get_jettons` | — | `walletSelector` |
-| `get_jettons_by_address` | `address` | — |
-| `get_jetton_info` | `address` | — |
+| `get_jettons_by_address` | `address` | `limit`, `offset`, `walletSelector` |
+| `get_jetton_info` | `jettonAddress` | `walletSelector` |
 | `get_known_jettons` | — | — |
 | `get_transactions` | — | `limit`, `walletSelector` |
 | `get_transaction_status` | `normalizedHash` | `walletSelector` |
@@ -45,4 +45,4 @@ Read-only queries for wallet balances, token holdings, and transaction history o
 
 - All tools are read-only — no confirmation needed
 - In registry mode, pass `walletSelector` to query a specific wallet instead of the active one
-- Amounts are returned in human-readable format (e.g., "1.5" = 1.5 TON)
+- All balance responses include both `amountRaw` (raw integer string) and `amount` (human-readable decimal string, e.g. `"1.5"` for 1.5 TON). Use `amount` for display; use `amountRaw` only when a raw integer is required.

package/skills/ton-cli/SKILL.md

@@ -18,6 +18,8 @@ Run any TON wallet MCP tool directly from the command line. The binary invokes t
 | `npx @ton/mcp@alpha --http [port]` | HTTP MCP server |
 | `npx @ton/mcp@alpha <tool_name> [--arg value ...]` | **Raw CLI: call one tool and exit** |
 
+Use exactly one mode for a given workflow: either MCP server mode (`stdio`/`--http`) or raw CLI. Do not combine them in the same task/session.
+
 ## Raw CLI Usage
 
 ```bash
@@ -31,6 +33,7 @@ npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQAbc...
 # All values are passed as plain strings; JSON objects/arrays are also accepted
 npx @ton/mcp@alpha get_transactions --limit 10
 npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.1 --comment "hi"
+npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm
 ```
 
 Arguments are passed as `--key value` pairs. Objects/arrays (`{...}` / `[...]`) are JSON-parsed; everything else is kept as a plain string.
@@ -68,11 +71,11 @@ Without `MNEMONIC` or `PRIVATE_KEY`, the CLI uses the local config registry at `
 | ---- | ------------- | ------------- |
 | `get_wallet` | — | `--walletSelector` |
 | `get_balance` | — | `--walletSelector` |
-| `get_balance_by_address` | `--address` | — |
+| `get_balance_by_address` | `--address` | `--walletSelector` |
 | `get_jetton_balance` | `--jettonAddress` | `--walletSelector` |
 | `get_jettons` | — | `--walletSelector` |
-| `get_jettons_by_address` | `--address` | — |
-| `get_jetton_info` | `--jettonAddress` | — |
+| `get_jettons_by_address` | `--address` | `--limit`, `--offset`, `--walletSelector` |
+| `get_jetton_info` | `--jettonAddress` | `--walletSelector` |
 | `get_transactions` | — | `--limit`, `--walletSelector` |
 | `get_transaction_status` | `--normalizedHash` | `--walletSelector` |
 | `get_known_jettons` | — | — |
@@ -93,28 +96,35 @@ Without `MNEMONIC` or `PRIVATE_KEY`, the CLI uses the local config registry at `
 | `send_ton` | `--toAddress`, `--amount` | `--comment`, `--walletSelector` |
 | `send_jetton` | `--toAddress`, `--jettonAddress`, `--amount` | `--comment`, `--walletSelector` |
 | `send_nft` | `--nftAddress`, `--toAddress` | `--comment`, `--walletSelector` |
-| `send_raw_transaction` | `--messages` | `--walletSelector` |
+| `send_raw_transaction` | `--messages` | `--validUntil`, `--fromAddress`, `--walletSelector` |
+| `emulate_transaction` | `--messages` | `--validUntil`, `--walletSelector` |
 
 ### Swaps
 
 | Tool | Required args | Optional args |
 | ---- | ------------- | ------------- |
-| `get_swap_quote` | `--fromToken`, `--toToken`, `--amount` | `--walletSelector` |
+| `get_swap_quote` | `--fromToken`, `--toToken`, `--amount` | `--slippageBps`, `--walletSelector` |
 
 ### NFTs
 
 | Tool | Required args | Optional args |
 | ---- | ------------- | ------------- |
 | `get_nfts` | — | `--limit`, `--offset`, `--walletSelector` |
-| `get_nfts_by_address` | `--address` | `--limit`, `--offset` |
-| `get_nft` | `--nftAddress` | — |
+| `get_nfts_by_address` | `--address` | `--limit`, `--offset`, `--walletSelector` |
+| `get_nft` | `--nftAddress` | `--walletSelector` |
 
 ### DNS
 
-| Tool | Required args |
-| ---- | ------------- |
-| `resolve_dns` | `--domain` |
-| `back_resolve_dns` | `--address` |
+| Tool | Required args | Optional args |
+| ---- | ------------- | ------------- |
+| `resolve_dns` | `--domain` | `--walletSelector` |
+| `back_resolve_dns` | `--address` | `--walletSelector` |
+
+### Authentication
+
+| Tool | Required args | Optional args |
+| ---- | ------------- | ------------- |
+| `generate_ton_proof` | `--domain`, `--payload` | `--walletSelector` |
 
 ## Example Session
 
@@ -132,7 +142,7 @@ npx @ton/mcp@alpha get_jettons
 npx @ton/mcp@alpha get_transactions --limit 10
 
 # Get balance of a specific jetton
-npx @ton/mcp@alpha get_jetton_balance --address EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
+npx @ton/mcp@alpha get_jetton_balance --jettonAddress EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
 
 # Resolve a .ton domain
 npx @ton/mcp@alpha resolve_dns --domain foundation.ton
@@ -148,10 +158,17 @@ npx @ton/mcp@alpha send_ton --toAddress UQA... --amount 0.5 --comment "payment"
 
 # Swap quote
 npx @ton/mcp@alpha get_swap_quote --fromToken TON --toToken EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs --amount 1
+
+# Generate a TonProof for a service challenge
+npx @ton/mcp@alpha generate_ton_proof --domain getgems.io --payload getgems-llm
 ```
 
 ## Notes
 
-- Always confirm with the user before running `send_ton`, `send_jetton`, `send_nft`, or `send_raw_transaction`.
+- Use `emulate_transaction` to dry-run any transaction before sending — it returns expected balance changes, fees, and high-level actions
+- Use `generate_ton_proof` only with the exact domain and payload supplied by the user or verifying service; do not alter the payload before signing
+- `generate_ton_proof` requires signing access even though it does not broadcast a transaction
+- Always confirm with the user before running `send_ton`, `send_jetton`, `send_nft`, or `send_raw_transaction`;
+- For confirmations and small option sets, prefer the host client's structured confirmation/choice UI when available; otherwise use a short natural-language yes/no prompt and never require an exact magic word;
 - After sending, poll `get_transaction_status --normalizedHash <hash>` until status is `completed` or `failed` (unless the user asks to skip).
 - In registry mode the active wallet from `~/.config/ton/config.json` is used by default.

package/skills/ton-create-wallet/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: false
 
 # Create TON Agentic Wallet
 
-Deploy an on-chain agentic wallet on TON. The agent generates operator keys, the user deploys the wallet contract from the dashboard, then provides the wallet address to complete setup.
+Deploy an on-chain agentic wallet on TON. The agent generates operator keys, opens the dashboard when local browser/shell tools are available, and uses callback-based completion only in long-lived stdio/HTTP MCP server sessions.
 
 ## MCP Tools
 
@@ -30,18 +30,19 @@ Deploy an on-chain agentic wallet on TON. The agent generates operator keys, the
 
 ## Workflow
 
-1. Call `agentic_start_root_wallet_setup` — this generates an operator key pair and returns a `setupId` and `dashboardUrl`
-2. Show the `dashboardUrl` to the user and tell them to open it, deploy the wallet from their TON wallet, and then come back with the deployed wallet address
-3. **Ask the user for the wallet address** — in CLI/stdio mode there is no callback, so the agent must ask the user to paste the wallet address after they finish deployment on the dashboard
-4. Call `agentic_complete_root_wallet_setup` with the `setupId` and the `walletAddress` provided by the user
-5. Confirm the wallet is active with `get_current_wallet` or `list_wallets` (see `ton-manage-wallets` skill)
+1. Call `agentic_start_root_wallet_setup` — this generates an operator key pair and returns a `setupId`, `dashboardUrl`, and `callbackUrl`
+2. If the environment exposes local browser or shell tools, open `dashboardUrl` yourself with the platform opener (`open`, `xdg-open`, `start`) or browser automation; only paste the link to the user if automatic opening is unavailable or fails
+3. Tell the user only to approve wallet deployment from their main TON wallet; do not ask them to retype the URL or copy intermediate data
+4. In long-lived stdio/HTTP MCP server sessions, poll `agentic_get_root_wallet_setup` or `agentic_list_pending_root_wallet_setups` and wait for `status: "callback_received"` when callback flow is available; then call `agentic_complete_root_wallet_setup` with `setupId`;
+5. In raw one-shot CLI usage, skip callback polling and ask for `walletAddress` after the user deploys the wallet; then call `agentic_complete_root_wallet_setup` with `walletAddress` 
+6. Confirm the wallet is active with `get_current_wallet` or `list_wallets` (see `ton-manage-wallets` skill)
 
 ## How It Works
 
 - The agent keeps the **operator private key** — it can sign transactions autonomously
 - The user keeps the **owner key** — they can withdraw funds or revoke access at any time
 - The wallet is an on-chain smart contract (NFT-based), not a custodial service
-- The dashboard is at `agentic-wallets-dashboard.vercel.app`
+- The dashboard is at `agents.ton.org`
 
 ## Environment Variables
 
@@ -53,6 +54,7 @@ Deploy an on-chain agentic wallet on TON. The agent generates operator keys, the
 
 ## Notes
 
-- In CLI/stdio mode there is no callback — always ask the user for the wallet address after showing the dashboard URL
-- Do **not** poll for callback status in CLI mode; just wait for the user to provide the address
+- Callback-driven completion is for long-lived stdio/HTTP MCP server sessions; raw CLI should use manual `walletAddress` completion
+- If automatic dashboard opening is supported in the current environment, do it instead of asking the user to open the URL manually
+- In raw CLI mode, ask for the wallet address after deployment because the callback server is not available long enough to complete the flow
 - After wallet creation, fund the wallet with TON before using transfer or swap skills

package/skills/ton-manage-wallets/SKILL.md

@@ -44,13 +44,16 @@ Manage the local wallet registry and perform advanced agentic wallet operations
 
 ### Rotate Operator Key
 1. Call `agentic_rotate_operator_key` — generates a new key pair and returns a dashboard URL for the user to apply the change on-chain
-2. Tell the user to open the dashboard link and confirm the key change
-3. Call `agentic_complete_rotate_operator_key` with the `rotationId` once the on-chain change is confirmed
+2. If local browser or shell tools are available, open the dashboard URL yourself; only send the raw link when automatic opening is unavailable or fails
+3. Ask the user only to approve the on-chain key change in their wallet; do not require them to re-paste the URL or type a fixed confirmation phrase
+4. Call `agentic_complete_rotate_operator_key` with the `rotationId`; if the chain state has not updated yet, wait briefly and retry instead of forcing extra user input
 
 ## Notes
 
 - `walletSelector` accepts wallet id, name, or address
 - For one-off queries, pass `walletSelector` directly to wallet-scoped tools instead of changing the active wallet
+- Use available shell/browser tools to open dashboard URLs for the user whenever possible
+- For confirmations and small option sets, prefer the host client's structured confirmation/choice UI when available; otherwise use a short natural-language yes/no prompt and never require an exact magic word
 - Registry data is stored in `~/.config/ton/config.json` (or `TON_CONFIG_PATH`)
 - Read tools work with imported agentic wallets that don't yet have an `operator_private_key`; write tools require it
 - Management tool responses never expose private keys, mnemonics, or API keys

package/skills/ton-nfts/SKILL.md

@@ -17,6 +17,7 @@ View and transfer NFTs on the TON blockchain.
 | `get_nfts_by_address` | `address` | `limit`, `offset` |
 | `get_nft` | `nftAddress` | — |
 | `send_nft` | `nftAddress`, `toAddress` | `comment`, `walletSelector` |
+| `emulate_transaction` | `messages` | `validUntil` |
 
 ## Workflows
 
@@ -29,11 +30,12 @@ View and transfer NFTs on the TON blockchain.
 
 ### Send an NFT
 1. Call `get_nfts` to find the NFT address if the user doesn't have it
-2. Confirm the transfer with the user
+2. Ask one short yes/no confirmation before transferring the NFT
 3. Call `send_nft` with `nftAddress` and `toAddress`
 4. Poll `get_transaction_status` with the returned `normalizedHash` until status is `completed` or `failed` (see `ton-balance` skill)
 
 ## Notes
 
-- Always confirm with the user before transferring an NFT
+- Use `emulate_transaction` to dry-run any transaction before sending — it returns expected balance changes, fees, and high-level actions so you can verify the outcome
+- Always confirm with the user before transferring an NFT; prefer the host client's structured confirmation UI when available, otherwise accept natural-language yes/no and do not require a fixed confirmation phrase
 - If no wallet is configured, use the `ton-create-wallet` skill first

package/skills/ton-proof/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ton-proof
+description: Generate TonConnect TonProof signatures for third-party authentication. Use when the user wants to log in with a TON wallet, prove wallet ownership, authenticate to an API such as GetGems, or generate a TonProof for a domain and challenge payload.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# TON Proof Authentication
+
+Generate a signed TonConnect proof-of-ownership payload for a domain and challenge string. This proves control of the active wallet without sending a transaction.
+
+## MCP Tools
+
+| Tool | Required | Optional |
+| ---- | -------- | -------- |
+| `generate_ton_proof` | `domain`, `payload` | `walletSelector` |
+| `get_wallet` | — | `walletSelector` |
+
+## Workflow
+
+1. Get the exact `domain` and `payload` from the user or the verifying service
+2. Do not edit, normalize, decode, or invent the payload; it is part of the signed proof
+3. Ask one short yes/no confirmation before sending; If there are tools for dialogs/confirmation available, use them instead of a free-text prompt.
+4. Call `generate_ton_proof` with the domain and payload
+5. Return the proof JSON to the user, or submit it to the service only when the user explicitly asked for that integration step
+
+## Output
+
+The proof includes:
+
+- `address`: active wallet address in raw format
+- `chain`: TON Connect chain id (`-239` for mainnet, `-3` for testnet)
+- `walletStateInit`: wallet state init in base64
+- `publicKey`: wallet public key
+- `timestamp`: Unix timestamp used in the proof
+- `domainLengthBytes` and `domainValue`: signed domain metadata
+- `signature`: base64 TonProof signature
+- `payload`: original challenge payload
+
+## Notes
+
+- TonProof is for authentication and proof of wallet ownership; it does not transfer funds
+- TonProof still requires signing access. Imported read-only agentic wallets need operator key rotation completed before this tool can generate a proof
+- Only generate a proof for domains and payloads the user intentionally provided or that came directly from the verifying service
+- If multiple wallets are configured, pass `walletSelector` instead of changing the active wallet for a one-off proof
+- If no wallet is configured, use the `ton-create-wallet` skill first

package/skills/ton-send/SKILL.md

@@ -15,6 +15,7 @@ Transfer TON or jettons to any address. Supports TON DNS resolution for `.ton` a
 | ---- | -------- | -------- |
 | `send_ton` | `toAddress`, `amount` | `comment`, `walletSelector` |
 | `send_jetton` | `toAddress`, `jettonAddress`, `amount` | `comment`, `walletSelector` |
+| `emulate_transaction` | `messages` | `validUntil` |
 | `resolve_dns` | `domain` | — |
 | `back_resolve_dns` | `address` | — |
 
@@ -22,20 +23,21 @@ Transfer TON or jettons to any address. Supports TON DNS resolution for `.ton` a
 
 ### Send TON
 1. If the user provides a DNS name (e.g., `foundation.ton`, `user.t.me`) instead of a raw address, call `resolve_dns` first
-2. Confirm the amount and recipient with the user
+2. Ask one short yes/no confirmation that restates the amount and recipient
 3. Call `send_ton` with address and amount
 4. Poll `get_transaction_status` with the returned `normalizedHash` until status is `completed` or `failed` (see `ton-balance` skill). User can ask to skip polling.
 
 ### Send Jetton (Token)
 1. If user mentions a token by name, call `get_known_jettons` (see `ton-balance` skill) to find the `jettonAddress`
 2. Call `get_jetton_balance` to verify sufficient balance
-3. Confirm with the user
+3. Ask one short yes/no confirmation before sending
 4. Call `send_jetton` with the `jettonAddress`, `toAddress`, and `amount`
 5. Poll `get_transaction_status` until completed or failed
 
 ## Notes
 
 - Amounts are human-readable (e.g., `"1.5"` = 1.5 TON, `"100"` = 100 tokens)
-- Always confirm with the user before executing a transfer
+- Use `emulate_transaction` to dry-run any transaction before sending — it returns expected balance changes (TON and jetton), fees, and high-level actions so you can verify the outcome
+- Always confirm with the user before executing a transfer; prefer the host client's structured confirmation UI when available, otherwise accept natural-language yes/no and do not require a fixed confirmation phrase
 - After sending, poll `get_transaction_status` by default. User can specify whether to check status.
 - If no wallet is configured, use the `ton-create-wallet` skill first

package/skills/ton-swap/SKILL.md

@@ -14,6 +14,7 @@ Swap tokens on TON via DEX aggregator. Two-step flow: get a quote, confirm with
 | Tool | Required | Optional |
 | ---- | -------- | -------- |
 | `get_swap_quote` | `fromToken`, `toToken`, `amount` | `walletSelector` |
+| `emulate_transaction` | `messages` | `validUntil` |
 | `send_raw_transaction` | `messages` | `walletSelector` |
 | `get_known_jettons` | — | — |
 
@@ -23,13 +24,14 @@ Swap tokens on TON via DEX aggregator. Two-step flow: get a quote, confirm with
 2. Call `get_swap_quote` with `fromToken`, `toToken`, and `amount`
    - Use `"TON"` for native TON, or the jetton master contract address for tokens
    - Amount is human-readable (e.g., `"1.5"` = 1.5 TON)
-3. Show the quote details to the user and ask for confirmation
-4. Call `send_raw_transaction` with the transaction params returned by the quote
-5. Poll `get_transaction_status` with the returned `normalizedHash` until status is `completed` or `failed` (see `ton-balance` skill). User can ask to skip polling.
+3. Call `emulate_transaction` with the quote's `transaction.messages` to dry-run the swap — verify the expected money flow (TON/jetton balance changes) before sending
+4. Show the quote details and emulation results to the user and ask one short yes/no confirmation
+5. Call `send_raw_transaction` with the transaction params returned by the quote
+6. Poll `get_transaction_status` with the returned `normalizedHash` until status is `completed` or `failed` (see `ton-balance` skill). User can ask to skip polling.
 
 ## Notes
 
-- Always confirm the swap with the user before executing
+- Always confirm the swap with the user before executing; prefer the host client's structured confirmation UI when available, otherwise accept natural-language yes/no and do not require a fixed confirmation phrase
 - The quote returns transaction messages ready for `send_raw_transaction`
 - After execution, poll `get_transaction_status` by default. User can specify whether to check status.
 - If no wallet is configured, use the `ton-create-wallet` skill first

package/skills/ton-xstocks/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ton-xstocks
+description: Buy or sell Backed xStocks (tokenized equities, e.g. TSLAx) on TON using jetton addresses from the xStocks API and TON MCP swap tools. Use when the user asks for xStocks, xStock, TSLAx, stock tokens on TON, or buying/selling equity jettons via Omniston.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# 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 TON → xStock and xStock → TON 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):
+   ```bash
+   curl -s "https://api.xstocks.fi/api/v2/public/assets/{symbol}"
+   ```
+   (production base: `https://api.xstocks.fi/api/v2` — see [xStocks API](https://docs.xstocks.fi/apis/openapi)).
+
+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` (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 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 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 **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 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 → 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 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.