MCP

VeTrade publishes a remote MCP server for agent tooling.

Use this MCP server when an agent needs VeChain transfer, swap, trading, or limit-order functions.

Endpoint

https://mcp.vetrade.vet

Metadata

https://vetrade.vet/mcp/server.json

The hosted MCP server is tools-first. For generic client compatibility it returns empty arrays for resources/list and resources/templates/list, and it returns a not-found error for resources/read because VeTrade does not currently publish MCP resources.

Tools

Default instant-on tools:

• transfer
• swap_transfer_exact_in
• swap_transfer_exact_out
• quote_swap
• swap
• create_limit_order
• cancel_limit_order
• list_limit_orders
• get_limit_order_status

Advanced tools:

• quote_swap
• prepare_swap_bundle
• inspect_swap_readiness
• validate_swap_bundle
• prepare_limit_order
• inspect_limit_order_creation_readiness
• prepare_limit_order_cancellation
• inspect_limit_order_cancellation_readiness
• list_supported_tokens
• list_supported_token_refs
• get_token_details
• resolve_supported_tokens
• get_wallet_balances
• get_token_allowances
• get_execution_readiness

First-run story

For new clients, add https://mcp.vetrade.vet, then call one of these first:

• transfer for a direct token or VET transfer package from human-friendly token selectors, decimal amount, and a recipient address or .vet name
• swap_transfer_exact_in for a signer-bound swap-transfer package that spends a fixed input amount and settles to a recipient address or .vet name
• swap_transfer_exact_out for a signer-bound swap-transfer package that guarantees the final output amount to a recipient address or .vet name
• quote_swap for a quote-only route and warning summary from raw base-unit inputs
• swap for a swap execution package from human-friendly token selectors and a decimal amount
• create_limit_order for a limit-order execution package from human-friendly token selectors and a decimal amount
• cancel_limit_order for a cancellation execution package from orderId

These task-oriented tools return the canonical VeTrade executionPackage, including the normalized request, resolved token metadata, bundle, validation, readiness, economics, continuity, warnings, and the executionInput artifact for local signing. For all signer-bound task tools, address is the canonical required wallet field on the hosted MCP surface.

Live-capable wrappers such as the VeTrade OpenAI SDK and the published helper keep signing local and should execute through their local execute_* or one-shot helper commands. Use the hosted task tools here as the planning handoff artifact, not as the broadcast path.

Agent starting point

If an agent only gets this MCP URL or page, it should:

• call transfer first for direct send requests such as send 1 VET to friend.vet
• call swap_transfer_exact_in first for recipient-bound swap requests where input amount is fixed
• call swap_transfer_exact_out first for recipient-bound swap requests where final output amount is fixed
• call quote_swap first for raw hosted quote-only requests
• call swap first for swap or trade requests such as swap 1 VTHO to VET
• call create_limit_order first for a new limit-order request
• call cancel_limit_order first for a cancellation request
• call list_limit_orders or get_limit_order_status for order reads
• use resolve_supported_tokens only when token lookup itself is the task or a lower-level flow truly needs explicit token metadata first
• treat the returned executionPackage as the handoff artifact for local signing and submission; do not ask the hosted MCP to sign or broadcast

Smallest useful calls

Hosted transfer planning and preflight:

{
  "token": "VET",
  "amount": "1",
  "address": "0xYourSignerAddress",
  "recipient": "friend.vet"
}

Hosted exact-input swap-transfer planning and preflight:

{
  "inputToken": "VTHO",
  "outputToken": "VET",
  "amount": "10",
  "address": "0xYourSignerAddress",
  "recipient": "friend.vet",
  "slippageBps": 100
}

Hosted exact-output swap-transfer planning and preflight:

{
  "inputToken": "VTHO",
  "outputToken": "VET",
  "amount": "1",
  "address": "0xYourSignerAddress",
  "recipient": "friend.vet",
  "slippageBps": 100
}

Hosted swap planning and preflight:

{
  "inputToken": "VTHO",
  "outputToken": "VET",
  "amount": "1",
  "address": "0xYourSignerAddress"
}

Hosted limit-order creation planning and preflight:

{
  "inputToken": "VET",
  "outputToken": "B3TR",
  "amount": "1",
  "address": "0xYourSignerAddress",
  "targetPrice": "1.25"
}

Hosted limit-order cancellation planning and preflight:

{
  "orderId": "42",
  "address": "0xYourSignerAddress"
}

Hosted order reads:

{
  "maker": "0xYourSignerAddress",
  "status": "ACTIVE"
}

{
  "orderId": "42"
}

Boundary

The hosted MCP stays read-only and non-custodial:

• it does not sign
• it does not custody keys
• it does not submit transactions

Signing remains local. When you are using the published helper or the OpenAI SDK integration, the local runtime derives the signer address from PRIVATE_KEY or privateKeyFile and passes that signer-bound address automatically. Optional VIP-191 fee delegation also stays local through GAS_PAYER_PRIVATE_KEY, GAS_PAYER_PRIVATE_KEY_FILE, or gasPayerPrivateKeyFile, with defaultGasPaymentMode and per-call gasPaymentMode deciding whether the signer or sponsor pays gas. Generic hosted-MCP clients still need to supply the signer-bound address field when they want a bundle-bearing execution package.

Validation errors now include the first field-level issue summary in the JSON-RPC error message and in error.data.issues, so agent clients can show the exact bad argument without parsing the whole structured payload first.

The remote MCP server intentionally publishes a conservative JSON Schema subset for tool inputs so remote clients can ingest the tool list reliably. VeTrade still enforces the stricter runtime rules server-side, including the requirement that create_limit_order receives exactly one of targetPrice or minAmountOut.

For token discovery, prefer resolve_supported_tokens when a prompt already names tokens such as VTHO and VET. It now accepts either singular selectors such as symbol or address, or plural selectors such as symbols and addresses. Use the lighter list_supported_token_refs call when you want the compact registry view first, then call get_token_details only for the token you need more context on. list_supported_tokens remains available as the richer compatibility list.

For read-only execution preflight, use get_wallet_balances to confirm VET, VTHO, and optional supported-token balances for one wallet address, use get_token_allowances to confirm ERC20 approval state for a known owner and spender, and use get_execution_readiness when you already have a prepared bundle and want one read-only answer about gas cost, quote freshness, allowance shortfalls, and whether the wallet looks ready for local submission. When an agent only needs a compact summary instead of the full bundle payload, use inspect_swap_readiness, inspect_limit_order_creation_readiness, or inspect_limit_order_cancellation_readiness. Native VET and VTHO do not use ERC20 allowances, so the allowance tool reports them as skipped instead of failing the whole request.

Troubleshooting

If a host reports errors such as symbols/0: must be object or claims that symbols or addresses are required when you omitted them, the issue is usually stale or corrupted host-side tool metadata rather than the VeTrade endpoint itself. Start a fresh session, force a new tools/list, and compare the cached schema against the live MCP metadata. For example, these are valid current shapes:

{ "symbols": ["VTHO", "VET"] }

{ "address": "0xYourWalletAddress", "includeNative": true }

OpenAI remote MCP example

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

ChatGPT developer-mode setup

URL: https://mcp.vetrade.vet

Anthropic / Claude setup

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

If you are new to the Anthropic setup, choose one path first:

• Planning and read-only MCP access: use vetrade-mcp.agent.yaml
• Live execution through the published helper/runtime: use create-vetrade-managed-execution-agent.sh

Anthropic Managed Agent templates

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

Use these files when you want a reusable Anthropic Managed Agent instead of adding the MCP server manually for each test.

Anthropic Console quickstart

In Anthropic Console:

1. Create an agent.
2. Add the remote MCP server with name vetrade and URL https://mcp.vetrade.vet.
3. Enable the standard agent toolset and the MCP toolset for vetrade.
4. Create or reuse a cloud environment with unrestricted networking.
5. Start a session and prompt the agent with a VeTrade read or planning task.

Anthropic CLI quickstart for planning and read-only MCP access

Install the CLI and export your Anthropic API key:

brew install anthropics/tap/ant
export ANTHROPIC_API_KEY=your_key_here

Download the published templates:

curl -fsSL https://vetrade.vet/examples/ai/managed-agents/vetrade-mcp.agent.yaml -o vetrade-mcp.agent.yaml
curl -fsSL https://vetrade.vet/examples/ai/managed-agents/cloud-unrestricted.environment.yaml -o cloud-unrestricted.environment.yaml

Create the agent, create the environment, start a session, and send a smoke test:

AGENT_ID=$(
  ant beta:agents create \
    --transform id \
    --format yaml \
    < vetrade-mcp.agent.yaml
)

ENVIRONMENT_ID=$(
  ant beta:environments create \
    --transform id \
    --format yaml \
    < cloud-unrestricted.environment.yaml
)

SESSION_ID=$(
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID" \
    --title "VeTrade MCP test" \
    --transform id \
    --format yaml
)

ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event '{type: user.message, content: [{type: text, text: "List the supported tokens available in VeTrade."}]}'

ant beta:sessions:events stream --session-id "$SESSION_ID"

If the CLI returns an authentication error, export ANTHROPIC_API_KEY in your shell and rerun the same commands.

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.

Anthropic execution-enabled setup

The raw MCP template above is still planning and read focused. If you want the managed agent to execute through the published helper/runtime path, start here 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 script writes vetrade-managed-execution.agent.yaml with an execution-aware system prompt, embeds the published helper https://vetrade.vet/skills/vetrade-ai/scripts/localExecution.mjs and runtime archive https://vetrade.vet/skills/vetrade-ai/runtime.tar.gz as fallback sources, and creates a new plain MCP-backed agent unless you set CREATE_AGENT=0.

The older custom-skill upload path is currently unsupported because the packaged runtime pushes the Anthropic skill archive above the current uncompressed size limit.

For repeated identical live demos, use a fresh session. The helper keeps deterministic execution state in the session environment, so the same payload can intentionally reuse the earlier submission result instead of broadcasting twice.

To start a session that also exposes signer material, export PRIVATE_KEY locally and use:

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"

This uploads the signer key as a mounted session file at /mnt/session/uploads/vetrade/private_key.txt, uploads the helper plus runtime archive, mounts them at /mnt/session/uploads/vetrade/localExecution.mjs and /mnt/session/uploads/vetrade/runtime.tar.gz, and prints the mounted session-resource file ids so cleanup can delete the right uploaded files later. The managed agent hydrates /tmp/vetrade from that mounted cache before it falls back to the published URLs, so you no longer need a first-run helper download or a session-side npm install. The helper can read the mounted signer file directly through privateKeyFile. Never read, cat, echo, or print that mounted file contents during execution. Pass the file path through privateKeyFile only.

The default managed-agent execution path is short on purpose: hydrate the helper/runtime from the mounted session cache if they are still missing, then pipe one symbol-driven payload directly into node /tmp/vetrade/scripts/localExecution.mjs quote-swap or swap. The helper resolves tokens through the VeTrade MCP server, derives the signer only when needed, prepares the bundle with simulation for live execution, validates it, and submits in one serial process. Keep that live path serial. Do not parallelize token resolution, helper download, signer derivation, prepare, validate, or submit work for a live swap, and keep narration minimal until you hit a blocker or a final receipt. Treat cache hydration as part of that same serial path. Never read, cat, echo, or print the mounted signer file contents. Do not use ad-hoc Python, Node, or shell crypto snippets when the helper is available. Use preview only when you need a preflight-only answer or blocker diagnosis. The helper relaunches itself with --use-env-proxy automatically when Anthropic exposes proxy environment variables and suppresses the related experimental warning so tool output stays compact. It can read the mounted signer file directly through privateKeyFile, it can read a sponsor key through gasPayerPrivateKeyFile, and it supports defaultGasPaymentMode plus per-call gasPaymentMode to decide whether gas comes from the signer or sponsor. It allows allowStaleQuoteExecution: true only when quote freshness is the last remaining blocker after validation. When estimated gas cost exceeds the VTHO side of the trade, treat that result as an economics warning to report clearly rather than a separate submit override. Submission results now report runtimeSource, timings.bootstrapMs, timings.totalMs, and timings.submittedAt. Set outputMode: "compact" when the agent should return only signer, route summary, tx, settlement, fees, timings, warnings, and economics instead of the full token metadata and receipt body.

The MCP swap-plan response now also carries quote.validityWindowSeconds, quote.economicsHint, and routePlan.summary with routeLabel, symbolExecutionPath, and addressExecutionPath, so agents can narrate the route in symbols while still keeping the raw address path available for debugging.

Use this one-shot managed swap pattern as the default execution path:

cat <<'JSON' | node /tmp/vetrade/scripts/localExecution.mjs swap
{
  "inputSymbol": "VTHO",
  "outputSymbol": "VET",
  "amount": "1",
  "outputMode": "compact",
  "allowStaleQuoteExecution": false,
  "privateKeyFile": "/mnt/session/uploads/vetrade/private_key.txt",
  "moduleRoot": "/tmp/vetrade/runtime"
}
JSON

When fee delegation should pay gas, add gasPaymentMode: "gas_payer" plus gasPayerPrivateKeyFile: "/mnt/session/uploads/vetrade/gas_payer_private_key.txt" to the live managed payload. The helper still accepts amountIn as a swap compatibility alias.

Use this one-shot managed quote pattern as the default quote-only path:

cat <<'JSON' | node /tmp/vetrade/scripts/localExecution.mjs quote-swap
{
  "inputSymbol": "VTHO",
  "outputSymbol": "VET",
  "amountIn": "1",
  "outputMode": "compact",
  "moduleRoot": "/tmp/vetrade/runtime"
}
JSON

Use this helper call to resolve the signer without touching the key contents when you need the lower-level flow:

cat <<'JSON' | node /tmp/vetrade/scripts/localExecution.mjs signer
{
  "privateKeyFile": "/mnt/session/uploads/vetrade/private_key.txt",
  "moduleRoot": "/tmp/vetrade/runtime"
}
JSON

If Anthropic stalls before the first bash tool result, use the published retry-once smoke-test wrapper instead of resending prompts manually:

curl -fsSL https://vetrade.vet/examples/ai/managed-agents/run-vetrade-managed-swap-smoke-test.sh \
  -o run-vetrade-managed-swap-smoke-test.sh
chmod +x run-vetrade-managed-swap-smoke-test.sh
./run-vetrade-managed-swap-smoke-test.sh "$AGENT_ID" "$ENVIRONMENT_ID" 1 VTHO VET

Use this exact payload shape so the agent does not inspect helper source to infer required keys:

{
  "bundle": { "...": "prepared bundle from MCP" },
  "quote": { "...": "quote block from prepare_swap_bundle" },
  "validation": { "success": true, "status": 200, "statusText": "OK", "errors": [] },
  "simulation": { "success": true, "status": 200, "statusText": "OK" },
  "expectedSigner": "0xSignerAddress",
  "allowStaleQuoteExecution": false,
  "privateKeyFile": "/mnt/session/uploads/vetrade/private_key.txt",
  "moduleRoot": "/tmp/vetrade/runtime",
  "outputMode": "compact"
}

Keep the economics explicit when you document live execution. A technically successful tiny swap can still be a bad trade if the VTHO gas cost dominates the amount received. Keep submit-atomic as the lower-level escape hatch when you already have a prepared and validated payload or need a debugging trace.

The canonical managed-agent submission pattern is:

cat <<'JSON' | node /tmp/vetrade/scripts/localExecution.mjs submit-atomic
{
  "bundle": { "...": "prepared bundle from MCP" },
  "quote": { "...": "quote block from prepare_swap_bundle" },
  "validation": { "success": true, "status": 200, "statusText": "OK", "errors": [] },
  "simulation": { "success": true, "status": 200, "statusText": "OK" },
  "expectedSigner": "0xSignerAddress",
  "allowStaleQuoteExecution": false,
  "privateKeyFile": "/mnt/session/uploads/vetrade/private_key.txt",
  "moduleRoot": "/tmp/vetrade/runtime",
  "outputMode": "compact"
}
JSON

Codex config

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

Fresh process rule

Every Codex CLI example below starts a fresh codex exec process.

Do not rely on a long-running Codex session to hot-reload ~/.codex/config.toml or newly installed skills. After adding the MCP entry, restart Codex or run a new codex exec command.

Tested Codex CLI workflows

Each example below is decision-complete for the tested mainnet flow.

These examples describe the MCP server itself. For local swap or limit-order execution with PRIVATE_KEY, use the VeTrade skill page instead of treating the MCP server as a signing surface.

Quote only

codex exec --ephemeral --skip-git-repo-check --sandbox read-only -C /absolute/path/to/repo \
  "Use the vetrade-ai skill and MCP only. Resolve VTHO and VET through resolve_supported_tokens first. Call get_token_details only if you need richer token metadata for one resolved token. On VeChain mainnet, quote swapping 1 VTHO to VET. Report Quote, Route, Warnings, and say clearly if MCP is unavailable in this fresh process."

Prepare a wallet-bound swap bundle and validate it

Replace the recipient with your VeChain wallet address.

codex exec --ephemeral --skip-git-repo-check --sandbox read-only -C /absolute/path/to/repo \
  "Use the vetrade-ai skill and MCP only. Resolve VTHO and VET through resolve_supported_tokens first. Call get_token_details only if you need richer token metadata for one resolved token. On VeChain mainnet, prepare a wallet-bound swap bundle for swapping 1 VTHO to VET for recipient 0xYourWalletAddress. Then validate the returned rawClauses with validate_swap_bundle. Report Quote, Route, Bundle, Validation, Warnings, and do not sign or submit."

Prepare a limit order and validate it

This is the tested strict interpretation of a request like 500 VTHO to 500 VET:

• amountIn = 500000000000000000000
• minAmountOut = 500000000000000000000
• resolved price is 1
• choose minAmountOut and do not also send targetPrice

codex exec --ephemeral --skip-git-repo-check --sandbox read-only -C /absolute/path/to/repo \
  "Use the vetrade-ai skill and MCP only. Resolve VTHO and VET through resolve_supported_tokens first. Call get_token_details only if you need richer token metadata for one resolved token. On VeChain mainnet, prepare a limit order for maker 0xYourWalletAddress that sells 500 VTHO for 500 VET using amountIn 500000000000000000000 and minAmountOut 500000000000000000000. Then validate the returned rawClauses with validate_swap_bundle. Report Limit Order, Bundle, Validation, Warnings, and do not sign or submit."

List active limit orders

status must be uppercase.

codex exec --ephemeral --skip-git-repo-check --sandbox read-only -C /absolute/path/to/repo \
  "Use the vetrade-ai skill and MCP only. On VeChain mainnet, list limit orders for maker 0xYourWalletAddress with status ACTIVE, page 1, pageSize 20. Report Order Status, Pagination, Source, and Warnings."

Read a single limit-order status

codex exec --ephemeral --skip-git-repo-check --sandbox read-only -C /absolute/path/to/repo \
  "Use the vetrade-ai skill and MCP only. On VeChain mainnet, read the status for limit order 14978. Report Order Status, amount remaining, fill count, source, and warnings."

Prepare a cancellation bundle and validate it

codex exec --ephemeral --skip-git-repo-check --sandbox read-only -C /absolute/path/to/repo \
  "Use the vetrade-ai skill and MCP only. On VeChain mainnet, prepare a cancellation bundle for maker 0xYourWalletAddress and order 14978. Then validate the returned rawClauses with validate_swap_bundle. Report Limit Order, Bundle, Validation, Warnings, and do not sign or submit."

Tested MCP gotchas

• Resolve user-provided token symbols through resolve_supported_tokens before calling swap or limit-order planning tools.
• Use list_supported_token_refs when you want the compact registry list instead of resolving a known symbol set.
• Call get_token_details only when you need icon URLs or richer metadata for one resolved token.
• Use get_wallet_balances when you want a read-only balance preflight for VET, VTHO, or supported ERC20 tokens before local execution.
• Use get_token_allowances when you want a read-only ERC20 allowance preflight for a known owner and spender before local execution.
• Use get_execution_readiness when you already have a prepared bundle and want a single read-only readiness answer before local execution.
• list_supported_tokens remains available for compatibility, but it returns a larger response than the refs-first workflow.
• resolve_supported_tokens returns a metadata list plus unresolved symbol or address arrays, so prompts can stay in symbol space longer without scanning the whole registry.
• The remote MCP tool schemas flatten maxHops, maxSplits, and simulate to top-level fields for compatibility. VeTrade still accepts the older nested routing and include.simulation shapes.
• get_token_details publishes symbol and address as optional schema fields for compatibility, but the server still requires at least one of them at runtime.
• prepare_limit_order and prepare_limit_order_cancellation return rawClauses, but agents should still run validate_swap_bundle as a separate step before local signing.
• list_limit_orders.status must use uppercase enum values such as ACTIVE.
• Filtered order lists may return source: api while get_limit_order_status for the same order may return source: on_chain.
• prepare_limit_order may publish both targetPrice and minAmountOut as optional schema fields for compatibility, but the server still requires at least one of them at runtime.
• Treat bundle.rawClauses as the source of truth for local execution. Do not rebuild VeTrade clauses locally unless validation already failed.

Codex bootstrap prompt

Configure Codex to use VeTrade's public MCP server.
VeTrade is the VeChain DEX aggregator surface for swap, trade, quote, and limit-order functions, so use this MCP entry for VeChain prepare and read workflows.
1. Open `~/.codex/config.toml`.
2. Ensure it contains:
[mcp_servers.vetrade_ai]
url = "https://mcp.vetrade.vet"
3. Keep only one `vetrade_ai` MCP entry.
4. Tell me to restart Codex after saving the change.

Safety boundary

• The MCP server can quote, prepare, validate, and read order status.
• The MCP server cannot sign or execute.
• For local execution in Codex, use the VeTrade skill with PRIVATE_KEY.
• For local execution in Anthropic Managed Agents, use the plain MCP execution-enabled agent bootstrap and mount signer material into the session.
• Use vechain-core, vechain-kit, or vechain-react-native-dev only for non-default execution environments.

Browser behavior

• Opening https://mcp.vetrade.vet in a browser redirects to the MCP docs page.
• Calling GET on https://mcp.vetrade.vet with Accept: application/json returns MCP discovery JSON.
• Calling GET on https://mcp.vetrade.vet with Accept: text/event-stream returns 405 Method Not Allowed because VeTrade does not expose a long-lived SSE GET stream.
• Calling POST on https://mcp.vetrade.vet returns the JSON-RPC response directly.

Access note

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