VeTrade VeTrade AI integration docs for VeChain trading AI / Agents
Machine-native surface

Limit Orders

Prepare, list, cancel, and inspect VeChain limit orders through the VeTrade AI surface.

Remote MCP server MCP manifest OpenAPI artifacts

VeTrade publishes a machine-native limit-order planning and read surface for VeChain.

Use this surface when an agent needs to:

  • prepare a limit-order creation bundle
  • list a maker address limit orders with filters and pagination
  • prepare a cancellation bundle
  • read on-chain order status

Endpoints

  • POST https://vetrade.vet/v2/limit-order-plans
  • GET https://vetrade.vet/v2/limit-order-plans
  • GET https://vetrade.vet/v2/limit-orders?maker=0x...&status=ACTIVE&page=1&pageSize=20
  • GET https://vetrade.vet/v2/limit-orders/{orderId}
  • OpenAPI JSON: https://vetrade.vet/openapi/limit-orders-v2.json

Create a limit order

Provide:

  • action
  • maker
  • inputToken
  • outputToken
  • amountIn
  • exactly one of targetPrice or minAmountOut

If inputToken is native VET, VeTrade prepares the wrap-to-vVET flow and sets the vvet:unwrap order option.

For a natural-language request such as 500 VTHO to 500 VET, the tested strict interpretation is:

  • amountIn = 500000000000000000000
  • choose exactly one of targetPrice or minAmountOut
  • prefer minAmountOut = 500000000000000000000
  • the resolved price is 1

prepare_limit_order returns rawClauses. Agents should run validate_swap_bundle on those returned clauses before local execution.

Cancel a limit order

Provide:

  • action
  • maker
  • orderId

unwrapVvetOnCancel is optional and defaults to true.

If the order was created with the vvet:unwrap option and the maker wallet still holds matching vVET, VeTrade prepends a local unwrap clause before the cancel clause.

prepare_limit_order_cancellation also returns rawClauses. Validation is a separate step and should be run before local execution.

List limit orders

Filters:

  • maker is required
  • status can be ACTIVE, OPEN, PARTIALLY_FILLED, FILLED, or CANCELLED
  • tokenFrom is optional
  • tokenTo is optional
  • page is 1-based
  • pageSize max is 100

Source selection:

  • active orders without pair filters prefer on-chain reads
  • filtered or historical reads use the indexed VeTrade API fallback

The response includes source so agents can tell whether the result came from on_chain or api.

In the tested flow, filtered listings returned source: api while a direct get_limit_order_status read for the same order returned source: on_chain. After execution, prefer get_limit_order_status for final confirmation.

Agent-oriented Codex examples

Use a fresh codex exec process for every example below.

Create and validate

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 orders

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 order

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 and validate

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.

Plain HTTP examples

curl -X POST https://vetrade.vet/v2/limit-order-plans \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "create",
    "maker": "0x1111111111111111111111111111111111111111",
    "inputToken": "0x0000000000000000000000000000000000000000",
    "outputToken": "0x5ef79995fe8a89e0812330e4378eb2660cede699",
    "amountIn": "1000000000000000000",
    "targetPrice": "1.25"
  }'

curl -X GET 'https://vetrade.vet/v2/limit-orders?maker=0x1111111111111111111111111111111111111111&status=ACTIVE&page=1&pageSize=20'

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

Codex skill usage

Use the VeTrade AI skill when you need VeChain swaps, VeChain trading routes, or VeChain limit-order preparation and status reads.

Safety boundary

  • The VeTrade limit-order API can prepare and read limit orders.
  • The VeTrade limit-order API does not sign or submit them.
  • If you want local execution from Codex, use the VeTrade skill with PRIVATE_KEY.
  • Keep vechain-core, vechain-kit, or vechain-react-native-dev only for non-default execution environments.