Transfer Plans

VeTrade now publishes one-shot transfer planning at /v2/transfer-plans and the hosted MCP tools transfer, swap_transfer_exact_in, and swap_transfer_exact_out.

These tools stay prepare-only:

• the hosted surface resolves tokens and .vet recipients
• the hosted surface builds the canonical executionPackage
• signing and broadcast still happen locally

Actions

• transfer
• swap_transfer_exact_in
• swap_transfer_exact_out

Recipient rules

• recipient accepts either:

- a VeChain hex address

- a .vet name

• signer-bound address stays hex-only
• .vet resolution is recipient-only in this rollout

Every response now includes recipient resolution metadata:

{
  "recipient": {
    "input": "friend.vet",
    "resolvedAddress": "0x1111111111111111111111111111111111111111",
    "inputType": "vet_domain",
    "reversePrimaryName": "friend.vet",
    "resolutionSource": "resolve_utils"
  }
}

Endpoint

POST /v2/transfer-plans
GET  /v2/transfer-plans

Smallest useful calls

Direct transfer:

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

Exact-input swap-transfer:

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

Exact-output swap-transfer:

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

Tool notes

• transfer builds:

- a native VET value transfer when token resolves to VET

- an ERC-20 transfer(recipient, amount) clause for supported tokens

• swap_transfer_exact_in sends a fixed input amount and settles output directly to the resolved recipient
• swap_transfer_exact_out guarantees the final output amount to the resolved recipient and returns the maximum input bound used for readiness checks and local execution
• swap_transfer_exact_out currently uses the legacy exact-output aggregator path, so maxHops and maxSplits are accepted but ignored

Local execution

The published helper now supports:

node ~/.codex/skills/vetrade-swap-planner/scripts/localExecution.mjs transfer transfer.json
node ~/.codex/skills/vetrade-swap-planner/scripts/localExecution.mjs swap-transfer-exact-in swap-transfer-in.json
node ~/.codex/skills/vetrade-swap-planner/scripts/localExecution.mjs swap-transfer-exact-out swap-transfer-out.json

The OpenAI SDK also exposes:

• execute_transfer
• execute_swap_transfer_exact_in
• execute_swap_transfer_exact_out

Use executionPolicy.recipientMode: 'recipient_optional' when those local execution tools must submit to a recipient that differs from the signer.