---
name: "vetrade-ai"
description: "Use when a user wants VeTrade quotes, local VeChain swap execution, limit-order creation or cancellation, limit-order status reads, or bundle validation through the MCP-backed VeTrade swap planner."
---

# VeTrade AI Skill

Use this skill when a user wants VeTrade quotes for swapping or trading on VeChain, local execution of prepared swap or limit-order bundles, limit-order status reads, or a validation pass before execution.

## Required behavior

1. Default to quote-only planning or read-only status/list flows unless the user explicitly asks to execute a swap or manage a limit order on-chain.
2. Start with `swap`, `create_limit_order`, `cancel_limit_order`, `list_limit_orders`, or `get_limit_order_status` when the user wants a direct planning or preflight result from human-friendly inputs. Use `resolve_supported_tokens` only when token lookup itself is the task or when an advanced flow genuinely needs explicit token metadata first. Use `list_supported_token_refs` only when you need the compact registry list first, call `get_token_details` only when richer token metadata is actually needed for one resolved token, and use `get_wallet_balances`, `get_token_allowances`, or `get_execution_readiness` only when you need a read-only preflight before execution.
2. Start with `transfer`, `swap_transfer_exact_in`, `swap_transfer_exact_out`, `swap`, `create_limit_order`, `cancel_limit_order`, `list_limit_orders`, or `get_limit_order_status` when the user wants a direct planning or preflight result from human-friendly inputs. Use `resolve_supported_tokens` only when token lookup itself is the task or when an advanced flow genuinely needs explicit token metadata first. Use `list_supported_token_refs` only when you need the compact registry list first, call `get_token_details` only when richer token metadata is actually needed for one resolved token, and use `get_wallet_balances`, `get_token_allowances`, or `get_execution_readiness` only when you need a read-only preflight before execution.
3. Use the MCP tools instead of embedding routing logic:
   - `transfer`
   - `swap_transfer_exact_in`
   - `swap_transfer_exact_out`
   - `swap`
   - `create_limit_order`
   - `cancel_limit_order`
   - `quote_swap`
   - `prepare_swap_bundle`
   - `validate_swap_bundle`
   - `prepare_limit_order`
   - `list_limit_orders`
   - `prepare_limit_order_cancellation`
   - `get_limit_order_status`
   - `list_supported_token_refs`
   - `get_token_details`
   - `resolve_supported_tokens`
   - `get_wallet_balances`
   - `get_token_allowances`
   - `get_execution_readiness`
   - `list_supported_tokens`
4. Before calling the hosted `swap` tool, gather:
   - `inputToken`
   - `outputToken`
   - `amount`
   - `recipient` when you are using the hosted MCP directly, or let the local helper derive the signer and bind `recipient` automatically
5. Before calling the hosted `create_limit_order` tool, gather:
   - `inputToken`
   - `outputToken`
   - `amount`
   - exactly one of `targetPrice` or `minAmountOut`
   - `maker` when you are using the hosted MCP directly, or let the local helper derive the signer and bind `maker` automatically
6. Interpret a request such as `500 VTHO to 500 VET` strictly as `amount = "500"` and `minAmountOut = "500"` unless the user explicitly provides `targetPrice` instead.
7. Before calling the hosted `cancel_limit_order` tool, gather:
   - `orderId`
8. When the user clearly asks to execute a transfer, swap, swap-transfer, or create/cancel a limit order:
   - use `PRIVATE_KEY` from the environment or a mounted signer file through `privateKeyFile`
   - optionally use `GAS_PAYER_PRIVATE_KEY`, `GAS_PAYER_PRIVATE_KEY_FILE`, or `gasPayerPrivateKeyFile` for local VIP-191 fee delegation
   - default gas payment stays `sender` unless `defaultGasPaymentMode` or per-call `gasPaymentMode` selects `gas_payer`
   - default the network to `mainnet` if the user did not specify one
   - derive the signer address locally through the VeChain SDK before preparing the bundle
   - use the derived signer address as the default `recipient` or `maker`
   - allow a different final `recipient` only for `transfer`, `swap-transfer-exact-in`, and `swap-transfer-exact-out`
   - if another signer-bound action supplies a different `recipient` or `maker`, stop with an instructive mismatch error that tells them to use the signer address or change `PRIVATE_KEY`
9. For local execution, prefer the packaged helper script at `~/.codex/skills/vetrade-ai/scripts/localExecution.mjs`:
   - use `signer` when you only need the signer address from `PRIVATE_KEY` or `privateKeyFile`
   - use `swap` as the primary live swap path when the user names tokens such as `VTHO` and `VET`
   - use `transfer`, `swap-transfer-exact-in`, and `swap-transfer-exact-out` as the primary live recipient-bearing execution paths
   - for both swap-transfer commands, prefer `amount` as the human-readable amount field; the helper also accepts `amountIn` for exact-in, `amountOut` for exact-out, and `inputSymbol` / `outputSymbol` as compatibility aliases
   - use `create-limit-order`, `cancel-limit-order`, `cancel-all-limit-orders`, and `list-limit-orders` as the primary managed limit-order paths
   - use `submit-atomic` only when you already have a prepared and validated payload and want one serial command that reads it from stdin or a file
   - use `submit` only when you already have the execution payload on disk and do not need the higher-level symbol-driven flow
   - set `outputMode: "compact"` when the agent only needs signer, tx, settlement, fees, timings, warnings, and economics
   - set `gasPaymentMode` to `inherit`, `sender`, or `gas_payer` only on live execution calls
   - use `preview` when the user explicitly wants a preflight-only answer or you need to diagnose a blocker
   - use `execute` only when you intentionally need the lower-level flow after an earlier preview decision
   - use `receipt` when you only need to re-check a known tx id
   - send the execution JSON through a file path or stdin instead of pasting raw JSON into the command line or using CLI flags for payload keys
   - in managed runtimes, keep the live path serial and prefer piping the JSON payload directly into `submit-atomic`
   - pass `privateKeyFile` when the signer lives at `/mnt/session/uploads/vetrade/private_key.txt` instead of exporting `PRIVATE_KEY`, and never read or print that mounted key file
   - pass `gasPayerPrivateKeyFile` only when a mounted sponsor key should pay gas, and never read or print that mounted key file
   - let the helper relaunch itself with `--use-env-proxy` when proxy environment variables are present and suppress the related experimental warning so the tool result stays compact
   - keep live-execution narration minimal until you hit a blocker or the final receipt
10. If the helper script is unavailable, fall back to the VeChain SDK path directly in this skill:
   - `ThorClient` against the explicit VeChain network URL
   - `VeChainProvider`
   - `VeChainPrivateKeySigner`
   - the returned `bundle.rawClauses` as the execution source of truth
   - one multi-clause transaction submission with receipt polling
11. After `swap`, `create_limit_order`, `cancel_limit_order`, `prepare_swap_bundle`, `prepare_limit_order`, or `prepare_limit_order_cancellation`, use the returned `executionInput` or bundle as the execution source of truth and run local preflight before submission.
12. Before local submission, always run preflight checks for:
   - signer and `recipient` or `maker` consistency
   - quote freshness or validity window when present
   - gas estimation with `thorClient.gas.estimateGas(clauses, sender, { gasPadding: 0.25 })`
   - input-token balance
   - VTHO balance for gas
13. When executing a swap:
   - prefer the helper `swap` command when the request is a straightforward symbol-driven swap such as `1 VTHO to VET`
   - skip a standalone `quote_swap` call unless the user explicitly asked for a quote-only answer first
   - prefer the hosted `swap` MCP tool over a manual `resolve_supported_tokens` plus `prepare_swap_bundle` chain
   - if you are not using `swap`, prepare a wallet-bound bundle with simulation enabled
   - if you are not using `swap`, validate the returned `rawClauses`
   - if you are not using `swap`, build one execution payload and submit it through the helper
   - if the managed session stalls before the first `bash` tool result, retry once with a fresh session instead of waiting indefinitely
   - wait for the receipt
   - report tx id, quote, route, bundle summary, gas used, fee paid, and actual settlement
14. When executing a direct transfer or swap-transfer:
   - prefer the helper `transfer`, `swap-transfer-exact-in`, or `swap-transfer-exact-out` command as the one-shot path
   - keep recipient `.vet` names in the request and let hosted planning resolve them
   - report tx id, resolved recipient, quote or route summary when present, gas used, fee paid, and actual settlement
15. When executing a limit-order creation:
   - prefer the helper `create-limit-order` command as the one-shot path
   - prefer the hosted `create_limit_order` MCP tool over a manual resolve-plus-prepare chain when you need the planning artifact directly
   - wait for the receipt
   - parse the `OrderCreated` event from receipt logs to resolve `orderId`
   - call `get_limit_order_status` for the created order and report the final on-chain status
16. When executing a limit-order cancellation:
   - prefer the helper `cancel-limit-order` command as the one-shot path
   - prefer the hosted `cancel_limit_order` MCP tool over a manual prepare-plus-validate chain when you need the planning artifact directly
   - wait for the receipt
   - call `get_limit_order_status` for the target order and report the final on-chain status
17. When the user wants active order management:
   - prefer `list-limit-orders` for the active order list
   - prefer `cancel-all-limit-orders` for best-effort batch cancellation of every active order
18. When filtering order lists by status, use uppercase enum values such as `ACTIVE`.
19. Always report:
   - quoted output and minimum output for swaps
   - route summary for swaps
   - limit-order summary, status, or pagination details when relevant
   - warnings
   - validation result when a bundle is returned
   - allowance requirements when a bundle is returned
   - tx id and receipt outcome when local execution happened
   - final settlement for swaps or final order status for limit-order create/cancel
   - when the swap is very small, whether gas cost makes the trade economically poor even if execution succeeded
20. Keep list and detail flows read-only. Do not sign or submit anything for those read paths.
21. Treat missing `PRIVATE_KEY`, insufficient balances, validation failure, and reverted or timed-out receipts as instructive stop conditions with clear recovery steps.
22. Treat quote expiry as a stop condition unless the helper confirms quote freshness is the only blocker and the live execution request explicitly enables `allowStaleQuoteExecution`.
23. Treat an execution as economically poor when the helper says estimated gas cost exceeds the VTHO side of the trade. Report that result clearly, but do not introduce a separate execution override for it.
24. Mention `vechain-core`, `vechain-kit`, or `vechain-react-native-dev` only as advanced references for non-default environments such as custom SDK flows, browser wallets, or React Native wallets.

## Local helper

Prefer these commands when the helper script is installed:

```bash
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs signer signer-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs swap swap-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs create-limit-order limit-order-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs cancel-limit-order cancel-order-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs cancel-all-limit-orders cancel-all-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs list-limit-orders list-orders-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs preview execution-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs submit-atomic execution-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs submit execution-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs execute execution-input.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs receipt receipt-input.json
```

If the current workspace does not expose the VeTrade dependencies, set `VETRADE_EXECUTION_MODULE_ROOT` to the VeTrade `website` directory before retrying the helper. When the environment exports `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY`, the CLI relaunches itself with `--use-env-proxy` and suppresses the related experimental warning. The helper still accepts stdin, but file-path invocation is the safer default in managed shells.
The helper now ships with a bundled pinned runtime next to `localExecution.mjs`, so cold starts do not need `npm install`. Set `VETRADE_EXECUTION_MODULE_ROOT` only when you intentionally want to override that packaged runtime with a custom workspace. In managed runtimes, prefer the one-shot commands `swap`, `create-limit-order`, `cancel-limit-order`, `cancel-all-limit-orders`, and `list-limit-orders` for default execution and order management. Keep `submit-atomic` for advanced cases where you already have a prepared and validated execution payload, and set `outputMode: "compact"` when the agent only needs the final execution summary.
In managed runtimes, derive the signer through `node ... signer` instead of writing ad-hoc Python, Node, or shell crypto snippets, and never read or print the mounted signer file contents.

Keep the `quote` block in the execution payload whenever it is available. The helper can fall back to quote metadata for swap intent and balance checks when a managed runtime trims `bundle.decodedCalls`.

When the helper flags the trade as economically poor, report that fee dominance clearly next to settlement so the operator can decide whether the outcome is acceptable. Managed sessions can also pass `privateKeyFile` so the helper reads the mounted signer file directly without exporting `PRIVATE_KEY`.

The helper output now includes `runtimeSource` plus `timings.bootstrapMs` and `timings.totalMs`. Submission paths also report `timings.submittedAt`.

## Output structure

- `Preview`: signer checks, quote freshness, gas estimate, balance checks, and readiness to submit
- `Quote`: amount in, amount out, minimum output, source, validity window
- `Route`: number of routes, hop count, instruction summary
- `Bundle`: only when wallet-bound, including clause count and allowance requirements
- `Limit Order`: action summary, price or min output resolution, order id or maker context
- `Order Status`: amount remaining, status, fill count, source, pagination when listing
- `Validation`: simulation result and any reverted clauses
- `Execution`: network, tx id, receipt outcome, gas used, fee paid, and settlement or final order status
- `Warnings`: non-fatal issues that the user should address before execution

For native VET outputs, the helper prefers the signer-facing receipt transfer when one is available and keeps `reportedRecipient` when the swap event points at an intermediate settlement address.

## Server boundary

- The public VeTrade MCP server remains quote, prepare, validate, and read only.
- This skill may sign and submit locally with `PRIVATE_KEY`, preferably through `scripts/localExecution.mjs`.
- Do not move signing or submission into the VeTrade MCP server contract or describe it as a remote MCP capability.

## Advanced references

- `vechain-core` for non-default SDK workflows, fee delegation, or custom execution tuning
- `vechain-kit` for web wallet flows
- `vechain-react-native-dev` for React Native wallet execution