OpenAI SDK | VeTrade AI

VeTrade now publishes a self-hosted Node integration for the official OpenAI Agents SDK at agents/openai-sdk/.

This path keeps the same safety boundary as the rest of VeTrade:

the public MCP server stays read-only
signing stays local through PRIVATE_KEY or privateKeyFile
live execution reuses the published localExecution.mjs helper instead of rebuilding VeChain submission logic in a second codepath

This rollout is self-hosted Node only. It does not target Agent Builder, hosted key custody, or a remote VeTrade signing service.

What this package gives you

buildVetradeAgent(config) for a reusable OpenAI agent entrypoint
OpenAI hosted MCP access to the public VeTrade read-only tools
local function tools for:

- execute_swap

- create_limit_order

- cancel_limit_order

- cancel_all_limit_orders

- list_limit_orders

- get_limit_order_status

hosted instant-on MCP tools for:

- swap

- create_limit_order

- cancel_limit_order

- list_limit_orders

- get_limit_order_status

typed execution policy checks before broadcast
compact execution results with signer, tx id, gas, fees, settlement or order status, warnings, runtimeSource, and timings

Package location

agents/openai-sdk/

Install

From agents/openai-sdk/:

npm install
npm run build

The agent run still uses OpenAI’s Responses API, so export OPENAI_API_KEY before running the examples.

For live execution, also provide signer material through one of these:

PRIVATE_KEY in the environment
privateKeyFile in the agent config
PRIVATE_KEY_FILE in the example scripts

Do not pass raw private keys in tool arguments.

The OpenAI SDK path reuses the same deterministic local execution cache as localExecution.mjs at $CODEX_HOME/state/vetrade-swap-planner/localExecutionState.json. If you intentionally want to rerun the exact same live demo and force a new submission, start with a fresh CODEX_HOME or clear that state file first.

Start here

Use this package when you want one self-hosted agent that can plan through the hosted MCP surface and sign locally.

Export OPENAI_API_KEY plus PRIVATE_KEY or PRIVATE_KEY_FILE.
Keep executionPolicy narrow so the agent only has the actions and token pairs you actually want.
Let the agent start with hosted swap, create_limit_order, cancel_limit_order, list_limit_orders, or get_limit_order_status; the local tools keep limit-order management one-shot while the hosted MCP surface remains the planning source of truth.
Use quote_swap, prepare_swap_bundle, or the inspect_*_readiness tools only when you explicitly want a lower-level or summary-first flow.

Minimal read-only agent

import { buildVetradeAgent } from '../src/index.js';

const { run } = buildVetradeAgent({
  executionPolicy: {
    allowedActions: [],
    recipientMode: 'signer_only'
  }
});

const result = await run(
  'List the supported VeTrade tokens and explain how to inspect swap readiness without signing anything.'
);

Minimal live-swap agent

import { buildVetradeAgent } from '../src/index.js';

const { run } = buildVetradeAgent({
  privateKeyFile: process.env.PRIVATE_KEY_FILE,
  executionPolicy: {
    allowedActions: ['execute_swap'],
    allowedTokenPairs: [{ input: 'VTHO', output: 'VET' }],
    maxInputPerSymbol: { VTHO: '5' },
    maxSlippageBps: 150,
    requireFreshQuote: true,
    allowStaleQuoteExecution: false,
    recipientMode: 'signer_only'
  }
});

const result = await run('Swap 1 VTHO to VET.');

Execution policy

The first package version supports:

allowedActions
allowedTokenPairs
maxInputPerSymbol
maxSlippageBps
requireFreshQuote
allowStaleQuoteExecution
recipientMode: 'signer_only'

The execution service validates the policy at startup, then re-checks signer, balances, freshness, and bundle validation immediately before broadcast. Economics remain advisory warning data in the returned preview and execution results instead of a local submit gate.

Local tool inputs

The local function tools intentionally use human-readable amounts:

execute_swap

- inputToken: symbol or address

- outputToken: symbol or address

- amount: decimal string such as "1.5"

- optional slippageBps, maxHops, maxSplits, outputMode

create_limit_order

- inputToken: symbol or address

- outputToken: symbol or address

- amount: decimal string

- exactly one of targetPrice or minAmountOut

- optional outputMode

cancel_limit_order

- orderId

- optional unwrapVvetOnCancel

- optional outputMode

cancel_all_limit_orders

- optional inputToken

- optional outputToken

list_limit_orders

- optional maker

- optional status, inputToken, outputToken, page, pageSize

get_limit_order_status

- orderId

The package now treats the hosted MCP executionPackage as the canonical planning artifact. For swaps, the local helper consumes the hosted swap package directly and derives the signer address from PRIVATE_KEY or privateKeyFile. For limit orders, the SDK consumes the hosted create_limit_order and cancel_limit_order packages directly instead of rebuilding clauses locally, and it adds typed one-shot management helpers for list, status, and cancel-all.

Inspect tools

The public MCP server also exposes compact readiness helpers and lower-level advanced tools for callers that intentionally need more control:

inspect_swap_readiness
inspect_limit_order_creation_readiness
inspect_limit_order_cancellation_readiness
quote_swap
prepare_swap_bundle
prepare_limit_order
prepare_limit_order_cancellation

Use these only when an agent needs a summary-first preflight answer or a lower-level bundle flow instead of the default hosted swap, create_limit_order, cancel_limit_order, list_limit_orders, or get_limit_order_status path.

Published examples

https://vetrade.vet/examples/ai/openai-sdk/readOnlyAgent.ts
https://vetrade.vet/examples/ai/openai-sdk/liveSwapAgent.ts
https://vetrade.vet/examples/ai/openai-sdk/limitOrdersAgent.ts
https://vetrade.vet/examples/ai/openai-sdk/README.md

Boundaries

VeTrade MCP stays read-only
signing stays local
live submission still revalidates signer, freshness, and validation before broadcast while reporting economics as advisory data
this package is a reference integration, not a hosted VeTrade execution service