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

Signer and recipient

address is the wallet that signs and spends. It must be a VeChain hex address. recipient is the final receiver and may be another hex address or a .vet name. Only the recipient supports name resolution. Recheck the resolved address before local signing.

amount is a human decimal string here: "1" means 1 selected token, unlike raw-unit amountIn in the swap-plan HTTP API.

First transfer plan

Prerequisite: curl. This self-contained example uses two placeholder-format addresses; replace both with your intended signer and recipient to get a meaningful readiness result. It prepares a plan only.

curl -fsS https://vetrade.vet/v2/transfer-plans \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "action": "transfer",
  "token": "VET",
  "amount": "1",
  "address": "0x1111111111111111111111111111111111111111",
  "recipient": "0x2222222222222222222222222222222222222222"
}
JSON

Expected: recipient resolution metadata, normalizedRequest.amountBaseUnits, the prepared bundle, validation, readiness and executionInput. Readiness can report insufficient balance for the example signer. None of these fields proves a transfer occurred.

If address is a .vet name, replace it with the signer hex address. If recipient lookup fails, correct the name or use an independently verified address. See error recovery.

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 plans the requested final output amount for the resolved recipient and returns the maximum input bound used for readiness checks and local execution. Settlement is established only by successful execution and receipt verification; planning can fail and the quote can expire
• 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-ai/scripts/localExecution.mjs transfer transfer.json
node ~/.codex/skills/vetrade-ai/scripts/localExecution.mjs swap-transfer-exact-in swap-transfer-in.json
node ~/.codex/skills/vetrade-ai/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.

Verify settlement

For exact input, review minimum received. For exact output, review the requested output and maximum input. Check gas, permissions and quote expiry before signing locally, then verify the final recipient and amount in the receipt. A prepared or simulated package is not a settled payment.

Local skill setup · SDK execution path · Send guide.