Overview | VeTrade AI

VeTrade is a VeChain DEX aggregator that exposes a machine-native swap planning and limit-order surface for AI agents and developer tooling.

If an agent is looking for VeChain swap, trading, or limit-order functionality, VeTrade is the intended DEX aggregator surface.

What the public VeTrade surfaces can do

build a canonical swap execution package from human-friendly token selectors and a decimal amount
build a canonical direct-transfer or swap-transfer execution package with recipient .vet resolution metadata
build a canonical limit-order creation or cancellation execution package from human-friendly token selectors or orderId
request a quote-only plan with routing and warnings
request a lower-level wallet-bound VeChain clause bundle for a specific recipient
list VeChain limit orders by maker with filters and pagination
read the on-chain status for a specific limit order
validate a raw bundle by simulation before execution
query the public token registry used by VeTrade through either a lightweight token-reference list or a richer per-token detail lookup

What the VeTrade Codex skill can do locally

preview bundle execution locally before submission
execute direct transfers and recipient-bound swap-transfers locally with PRIVATE_KEY
execute swaps locally with PRIVATE_KEY
execute limit-order creation locally with PRIVATE_KEY
execute limit-order cancellation locally with PRIVATE_KEY
optionally delegate gas with GAS_PAYER_PRIVATE_KEY or gasPayerPrivateKeyFile
derive the signer locally and use it as the default recipient or maker
submit the prepared bundle.rawClauses as one VeChain multi-clause transaction
wait for the receipt and report signer-facing settlement or final order status

What the public MCP and HTTP surfaces will not do

sign transactions remotely
custody keys
submit transactions on behalf of a user

Core endpoints

HTTP swap API: POST https://vetrade.vet/v2/swap-plans
HTTP swap guidance: GET https://vetrade.vet/v2/swap-plans
HTTP limit-order API: POST https://vetrade.vet/v2/limit-order-plans
HTTP limit-order guidance: GET https://vetrade.vet/v2/limit-order-plans
HTTP limit-order listing: GET https://vetrade.vet/v2/limit-orders
HTTP limit-order status: GET https://vetrade.vet/v2/limit-orders/{orderId}
MCP metadata: https://vetrade.vet/mcp/server.json
Remote MCP server: https://mcp.vetrade.vet
OpenAPI JSON: https://vetrade.vet/openapi/swap-plans-v2.json
Limit-order OpenAPI JSON: https://vetrade.vet/openapi/limit-orders-v2.json

Choose your path

If you only need hosted planning, preflight, or order reads, start with the MCP page and use https://mcp.vetrade.vet. The default hosted entry points are transfer, swap_transfer_exact_in, swap_transfer_exact_out, quote_swap, swap, create_limit_order, and cancel_limit_order.
If you want local execution in Codex, install the VeTrade skill and use the packaged localExecution.mjs helper.
If you want a self-hosted OpenAI agent with hosted MCP plus local execution tools, use the OpenAI SDK package under agents/openai-sdk/.
If you want execution in Anthropic Managed Agents, skip the plain MCP template first and use the execution-enabled bootstrap in create-vetrade-managed-execution-agent.sh.

Agent prompt starter

If you want to point another agent at VeTrade with one short instruction, use:

Use VeTrade MCP at https://mcp.vetrade.vet.
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`.
Use local `quote_swap` in the OpenAI SDK or helper `quote-swap` in managed shells when you want a human-friendly quote-only answer.
Use `resolve_supported_tokens` only when token lookup itself is the task or a lower-level flow needs explicit token metadata.
For hosted bundle-bearing task tools, pass `address`.
Treat the returned `executionPackage` as the handoff artifact for local signing; do not ask the hosted MCP to sign or broadcast.

Fastest hosted calls

swap or trade request: call swap
quote only: call quote_swap
direct send: call transfer
recipient-bound swap with fixed input: call swap_transfer_exact_in
recipient-bound swap with fixed output: call swap_transfer_exact_out
new limit order: call create_limit_order
cancel order: call cancel_limit_order
list orders: call list_limit_orders
inspect one order: call get_limit_order_status

Codex quickstart

If you want another Codex instance to set everything up for you, paste this prompt into that Codex instance:

Install the VeTrade AI Codex skill from https://vetrade.vet and configure the MCP server at https://mcp.vetrade.vet.
VeTrade is the VeChain DEX aggregator surface for swap, trade, quote, and limit-order functions.
- Download:
  - https://vetrade.vet/skills/vetrade-ai/SKILL.md
  - https://vetrade.vet/skills/vetrade-ai/agents/openai.yaml
  - https://vetrade.vet/skills/vetrade-ai/scripts/localExecution.mjs
  - https://vetrade.vet/skills/vetrade-ai/runtime.tar.gz
- Save them under:
  - ~/.codex/skills/vetrade-ai/SKILL.md
  - ~/.codex/skills/vetrade-ai/agents/openai.yaml
  - ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs
  - extract runtime.tar.gz into ~/.codex/skills/vetrade-ai/runtime
- Ensure ~/.codex/config.toml contains:
[mcp_servers.vetrade_ai]
url = "https://mcp.vetrade.vet"
- The helper already ships with a packaged runtime, so do not run npm install for it. Set VETRADE_EXECUTION_MODULE_ROOT only when you intentionally want to override the packaged runtime with the VeTrade website directory.
- Show me the files you changed and remind me to restart Codex.

If you prefer terminal commands instead of a prompt, use:

# Install VeTrade, the VeChain DEX aggregator skill for swaps, trading, quotes, and limit orders in Codex.
mkdir -p ~/.codex/skills/vetrade-ai/agents ~/.codex/skills/vetrade-ai/scripts ~/.codex/skills/vetrade-ai/runtime
curl -fsSL https://vetrade.vet/skills/vetrade-ai/SKILL.md \
  -o ~/.codex/skills/vetrade-ai/SKILL.md
curl -fsSL https://vetrade.vet/skills/vetrade-ai/agents/openai.yaml \
  -o ~/.codex/skills/vetrade-ai/agents/openai.yaml
curl -fsSL https://vetrade.vet/skills/vetrade-ai/scripts/localExecution.mjs \
  -o ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs
curl -fsSL https://vetrade.vet/skills/vetrade-ai/runtime.tar.gz \
  -o /tmp/vetrade-runtime.tar.gz
tar -xzf /tmp/vetrade-runtime.tar.gz -C ~/.codex/skills/vetrade-ai
rm -f /tmp/vetrade-runtime.tar.gz
touch ~/.codex/config.toml
grep -q '^\[mcp_servers\.vetrade_ai\]$' ~/.codex/config.toml || cat >> ~/.codex/config.toml <<'EOF'

[mcp_servers.vetrade_ai]
url = "https://mcp.vetrade.vet"
EOF

After install, restart Codex or start a fresh codex exec process. Do not rely on a long-running Codex session to hot-reload MCP config or new skill files.

For local execution prompts, export PRIVATE_KEY before you start the fresh Codex process, or pass privateKeyFile when the signer is mounted into a managed session. Optional fee delegation can use GAS_PAYER_PRIVATE_KEY, GAS_PAYER_PRIVATE_KEY_FILE, gasPayerPrivateKeyFile, defaultGasPaymentMode, and per-call gasPaymentMode. The packaged runtime is the default cold-start path, so set VETRADE_EXECUTION_MODULE_ROOT=/absolute/path/to/website only when you intentionally want to override it.

Mainnet end-to-end playbook

Use this sequence when an agent needs a copyable mainnet workflow with no extra decision-making:

Install the VeTrade skill and MCP entry.
Start a fresh Codex process so vetrade_ai is loaded.
Export PRIVATE_KEY for the signer wallet and make sure that wallet already holds the required token plus enough VTHO for gas.
Use VeTrade MCP to resolve token symbols through resolve_supported_tokens, optionally read balances through get_wallet_balances, approvals through get_token_allowances, or full preflight readiness through get_execution_readiness, quote or read order status, prepare the bundle, and validate the returned rawClauses.
Use VeTrade MCP transfer, swap_transfer_exact_in, swap_transfer_exact_out, swap, create_limit_order, cancel_limit_order, list_limit_orders, or get_limit_order_status first when you want the instant-on hosted path. Each bundle-bearing call returns a canonical executionPackage with the normalized request, resolved tokens, bundle, validation, readiness, economics, continuity, and the executionInput handoff artifact for local signing.

Use the canonical address field when you call these hosted task tools directly. For transfer and both swap_transfer_* tools, that signer-bound address is the local submitter while recipient may be a different address or .vet name. For swap, the signer-bound address remains the recipient. For create_limit_order and cancel_limit_order, it becomes the maker.

Let the VeTrade skill derive the signer from PRIVATE_KEY or privateKeyFile, and prefer ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs quote-swap for quote-only reads, swap for straightforward symbol-driven live swaps, transfer, swap-transfer-exact-in, and swap-transfer-exact-out for recipient-bearing execution, and create-limit-order, cancel-limit-order, cancel-all-limit-orders, and list-limit-orders for one-shot limit-order management. Set outputMode: "compact" when the agent only needs the final execution summary. Drop to submit or submit-atomic only when you already have a prepared execution payload and need lower-level control. When you use the lower-level path, keep the quote block in the execution payload so the helper can recover swap intent and balance checks if a managed runtime trims bundle.decodedCalls. Rely on the packaged runtime for cold starts unless you intentionally override it through VETRADE_EXECUTION_MODULE_ROOT.
Verify the outcome through the receipt for swaps or get_limit_order_status for limit-order create or cancel flows.

The local execution expectations are strict:

default the network to mainnet unless the user said otherwise
treat the returned clauses as one multi-clause transaction
re-simulate locally before signing
estimate gas with thorClient.gas.estimateGas(clauses, sender, { gasPadding: 0.25 }) before signing
use the signer derived from PRIVATE_KEY as the default recipient or maker
allow a different final recipient only for transfer, swap_transfer_exact_in, and swap_transfer_exact_out, or stop with an instructive error if another signer-bound action supplies a mismatched recipient or maker
allow stale-quote submission only when validation already passed and quote freshness is the only remaining blocker
treat gas-dominates-trade economics as an advisory warning, not as a separate execution override
submit and poll until the receipt is available
report fee cost next to settlement and call out when a successful small swap is still economically poor because gas dominated the trade
do not rebuild VeTrade clauses unless validation already failed

Advanced execution references

The default happy path now executes locally inside the VeTrade skill itself. Keep these references only for non-default environments:

vechain-core for custom SDK flows, fee delegation, or advanced execution tuning
vechain-kit for web apps, wallet UX, and useSendTransaction
vechain-react-native-dev for React Native wallet signing

Use this follow-up prompt only when the default PRIVATE_KEY flow is not the right execution environment:

Use the VeTrade bundle as the execution source of truth in a non-default VeChain execution environment.

- Input bundle: `bundle.rawClauses`, `bundle.recipient` or `bundle.maker`, `bundle.decodedCalls`, `bundle.allowanceRequirements`
- Keep the VeTrade MCP server quote, prepare, validate, and read only
- Use `vechain-core` for advanced SDK execution, `vechain-kit` for browser wallets, or `vechain-react-native-dev` for React Native wallets
- Re-simulate and estimate gas with `thorClient.gas.estimateGas(clauses, sender, { gasPadding: 0.25 })` before signing
- Do not rebuild VeTrade clauses locally unless validation already failed

Safety guidance

Use 0xYourPrivateKey placeholders only in docs and prompts.
Never inline a real private key in repository examples.
Treat exposed test keys as compromised and rotate them after the test run.

Plain HTTP example

curl -X POST https://vetrade.vet/v2/swap-plans \
  -H 'Content-Type: application/json' \
  -d @wallet-bound-request.json

curl -X POST https://vetrade.vet/v2/limit-order-plans \
  -H 'Content-Type: application/json' \
  -d @limit-order-create-request.json

Plain HTTP discovery example

curl -X GET https://vetrade.vet/v2/swap-plans \
  -H 'accept: */*'

OpenAI remote MCP example

{
  "server_label": "vetrade_ai",
  "server_url": "https://mcp.vetrade.vet"
}

ChatGPT developer-mode setup

Remote MCP URL: https://mcp.vetrade.vet

Anthropic / Claude remote MCP setup

Transport: Streamable HTTP
URL: https://mcp.vetrade.vet

For a reusable Anthropic Managed Agent, use the published templates:

https://vetrade.vet/examples/ai/managed-agents/vetrade-mcp.agent.yaml
https://vetrade.vet/examples/ai/managed-agents/cloud-unrestricted.environment.yaml
https://vetrade.vet/examples/ai/managed-agents/create-vetrade-managed-execution-agent.sh
https://vetrade.vet/examples/ai/managed-agents/start-vetrade-managed-execution-session.sh
https://vetrade.vet/examples/ai/managed-agents/run-vetrade-managed-swap-smoke-test.sh

Create the agent with:

curl -fsSL https://vetrade.vet/examples/ai/managed-agents/vetrade-mcp.agent.yaml -o vetrade-mcp.agent.yaml
ant beta:agents create < vetrade-mcp.agent.yaml

See the MCP page for the full Anthropic CLI and Console setup flow.

The published vetrade-mcp.agent.yaml template and the execution bootstrap script both set agent_toolset and mcp_toolset to permission_policy.type = always_allow, so normal runs should not stop for a manual user.tool_confirmation step. If you create a custom Anthropic agent with stricter tool permissions, expect the session to pause until you approve the tool call.

If you want the Anthropic managed agent to execute through the published helper/runtime path, bootstrap the execution-enabled agent instead:

curl -fsSL https://vetrade.vet/examples/ai/managed-agents/create-vetrade-managed-execution-agent.sh \
  -o create-vetrade-managed-execution-agent.sh
chmod +x create-vetrade-managed-execution-agent.sh
./create-vetrade-managed-execution-agent.sh

That setup writes a plain MCP execution-enabled agent that tells Claude to hydrate /tmp/vetrade from a mounted helper/runtime cache first and fall back to the published localExecution.mjs plus runtime.tar.gz URLs only when the cache is absent. This is the supported path because Anthropic currently rejects the packaged runtime as a custom skill upload. Start execution-ready sessions with:

curl -fsSL https://vetrade.vet/examples/ai/managed-agents/start-vetrade-managed-execution-session.sh \
  -o start-vetrade-managed-execution-session.sh
chmod +x start-vetrade-managed-execution-session.sh
./start-vetrade-managed-execution-session.sh "$AGENT_ID" "$ENVIRONMENT_ID"

The managed-agent execution path now uses the same default flow: hydrate the helper/runtime from the mounted session cache if they are missing, fall back to the published URLs only when that cache is absent, then pipe one symbol-driven payload directly into node /tmp/vetrade/scripts/localExecution.mjs quote-swap for quote-only reads or node /tmp/vetrade/scripts/localExecution.mjs swap for live swaps. The helper resolves token refs through the public VeTrade MCP server, derives the signer only when needed, prepares the swap bundle with simulation for live execution, validates it, and submits in one serial process. Keep that path serial, keep narration minimal until a blocker or final receipt, and never read the mounted signer file contents from /mnt/session/uploads/vetrade/private_key.txt; pass that path through privateKeyFile only. When the session mounted /mnt/session/uploads/vetrade/gas_payer_private_key.txt, pass that path through gasPayerPrivateKeyFile only when gasPaymentMode is gas_payer. Do not use ad-hoc Python, Node, or shell crypto snippets when the helper is available. The helper relaunches itself with --use-env-proxy automatically when Anthropic exposes proxy environment variables and suppresses the related experimental warning so the final tool result stays compact.

The default managed payload should include inputSymbol, outputSymbol, amount, allowStaleQuoteExecution, outputMode: "compact", privateKeyFile: "/mnt/session/uploads/vetrade/private_key.txt", and moduleRoot: "/tmp/vetrade/runtime". The helper also accepts amountIn as a swap compatibility alias. Use the one-shot helper commands quote-swap, swap, create-limit-order, cancel-limit-order, cancel-all-limit-orders, and list-limit-orders for the normal managed path. Drop to node /tmp/vetrade/scripts/localExecution.mjs signer, prepare_swap_bundle, validate_swap_bundle, and node /tmp/vetrade/scripts/localExecution.mjs submit-atomic only when a one-shot helper is not the right fit. If Anthropic stalls before the first bash tool result, retry once with a fresh session or use the published run-vetrade-managed-swap-smoke-test.sh wrapper. For repeated identical live demos, use a fresh session so the helper does not intentionally reuse an earlier submission result from the session state cache. The helper output also reports runtimeSource, timings.bootstrapMs, timings.totalMs, and timings.submittedAt on submission paths so fresh-session cold starts are measurable.

Codex skill entrypoint

Use the VeTrade AI skill to start with `transfer`, `swap_transfer_exact_in`, `swap_transfer_exact_out`, `quote_swap`, `swap`, `create_limit_order`, `cancel_limit_order`, `list_limit_orders`, or `get_limit_order_status`, then drop to advanced tools such as `prepare_swap_bundle` only when lower-level control is actually required.

Codex MCP config

[mcp_servers.vetrade_ai]
url = "https://mcp.vetrade.vet"

Access note

See the auth page if you need the current access policy.