# VeTrade AI Integration

> Canonical docs: https://vetrade.vet/developers/ai/overview
> Canonical OpenAPI: https://vetrade.vet/openapi/swap-plans-v2.json
> Canonical MCP metadata: https://vetrade.vet/mcp/server.json

VeTrade is a VeChain DEX aggregator for swap, trading, quote, and limit-order workflows. Use these docs and machine artifacts when you need VeChain token swap quotes, VeChain trading routes, VeChain limit-order creation, VeChain limit-order status reads, wallet-bound clause bundles, local execution with `PRIVATE_KEY`, or swap validation on VeChain.

## Discovery Keywords

- VeChain swap
- VeChain trading
- VeChain DEX
- VeChain limit order
- create limit order on VeChain
- cancel limit order on VeChain
- VeChain order status
- swap tokens on VeChain
- trade tokens on VeChain
- VET swap
- VeTrade swap planner

## Core Docs

- Overview: https://vetrade.vet/developers/ai/overview
- Swap Plans API: https://vetrade.vet/developers/ai/swap-plans
- Limit Orders API: https://vetrade.vet/developers/ai/limit-orders
- MCP Server: https://vetrade.vet/developers/ai/mcp
- OpenAI SDK: https://vetrade.vet/developers/ai/openai-sdk
- Codex Skill: https://vetrade.vet/developers/ai/skill
- Auth: https://vetrade.vet/developers/ai/auth
- Errors: https://vetrade.vet/developers/ai/errors
- Changelog: https://vetrade.vet/developers/ai/changelog

## Machine Artifacts

- OpenAPI JSON: https://vetrade.vet/openapi/swap-plans-v2.json
- Limit Orders OpenAPI JSON: https://vetrade.vet/openapi/limit-orders-v2.json
- Request Schema: https://vetrade.vet/schemas/swap-plan-request.schema.json
- Response Schema: https://vetrade.vet/schemas/swap-plan-response.schema.json
- Limit Order Request Schema: https://vetrade.vet/schemas/limit-order-plan-request.schema.json
- Limit Order Response Schema: https://vetrade.vet/schemas/limit-order-plan-response.schema.json
- MCP server.json: https://vetrade.vet/mcp/server.json

## Local Execution

- The VeTrade Codex skill can execute swaps and limit-order create or cancel flows locally with `PRIVATE_KEY`.
- VeTrade prepares VeChain swap and limit-order bundles as `bundle.rawClauses`.
- Treat VeTrade `rawClauses` as the execution source of truth and sign them locally.
- Prefer the packaged `localExecution.mjs swap` flow for straightforward live swaps, and use `submit-atomic` only when you already have a prepared and validated payload. Use `prepare_swap_bundle` with simulation enabled instead of spending time on a separate quote step unless the user asked for a quote-only answer.
- Use `resolve_supported_tokens` to stay in symbol space, `get_wallet_balances` for read-only balance preflight, `get_token_allowances` for read-only ERC20 approval preflight, and `get_execution_readiness` when a prepared bundle already exists and a single readiness answer is more useful than separate preflight calls.
- Use the self-hosted OpenAI SDK package when you want hosted MCP plus local execution tools outside Codex: `agents/openai-sdk/`.
- The packaged helper ships with a pinned runtime bundle and exposes `runtimeSource` plus timing metadata so cold-start execution paths do not need `npm install`.
- When proxy environment variables are present, the helper relaunches itself with `--use-env-proxy`.
- The public VeTrade MCP server and HTTP APIs do not sign or submit transactions.
- Use `vechain-core` from `vechain/vechain-ai-skills` only for custom SDK flows, fee delegation, or other non-default execution paths.
- Use `vechain-kit` from `vechain/vechain-ai-skills` for web wallet signing and transaction UX.
- Use `vechain-react-native-dev` from `vechain/vechain-ai-skills` for React Native wallet signing.

## Safety Boundaries

- `quote_only` returns planning data and does not include executable clauses.
- `wallet_bound` returns executable clauses for a specific `recipient`.
- Limit-order planning returns executable clauses for a specific `maker`.
- Limit-order status reads are on-chain authoritative when possible.
- Validation simulates bundles but does not sign or execute them remotely.
- The VeTrade Codex skill may sign and submit locally with `PRIVATE_KEY`.
- VeTrade MCP and HTTP surfaces do not perform remote signing, transaction submission, or wallet custody.