714d4ebcd4
README, .env.example, and docs/architecture/non-custodial-split.md updated for the family-1 keyless migration (build_* tools, no mnemonic parameters): custody notice rewritten to describe the keyless boundary precisely, tool tables synced to the 23-tool surface (4 renames, 4 changed in place, 2 removed), self-hosting and testing copy updated, .env.example spend-limit scope annotated, and the architecture doc's PR-sequence table marks family 1 as landed. docs/VECTOR.md (flagged by Task 4 as referencing stale tool names) is also updated: renamed/removed tool sections corrected, keyless changeAddress params added, and the Safety Controls / Error Handling sections stop claiming server-side spend limits and mnemonic requirements that no longer apply to the tools this page documents. Edits confined to tool names and custody claims - no restructuring, no wholesale ADA to AP3X pass beyond the sections touched.
150 lines
6.8 KiB
Markdown
150 lines
6.8 KiB
Markdown
# Vector MCP Server — Tool Reference
|
|
|
|
## Overview
|
|
|
|
The Vector MCP Server exposes blockchain tools that AI agents can use to interact with the Vector network. All tools use the `vector_` prefix and communicate with Vector via Ogmios (chain queries) and the submit API (transaction submission).
|
|
|
|
## Prerequisites
|
|
|
|
1. A Vector wallet address (source of funds) — the tools below are keyless and take no mnemonic; signing happens separately via your local signer
|
|
2. Access to Vector network endpoints (Ogmios, submit API, Koios)
|
|
3. Node.js >= 14.0.0
|
|
|
|
## Tools
|
|
|
|
### vector_get_balance
|
|
|
|
Get ADA and token balances for any Vector address.
|
|
|
|
**Parameters:**
|
|
- `address` (string, required) — Vector address to check (addr1...)
|
|
|
|
**Example prompt:** "What's the balance of addr1qx..."
|
|
|
|
### vector_get_utxos
|
|
|
|
List unspent transaction outputs for an address.
|
|
|
|
**Parameters:**
|
|
- `address` (string, required) — Address to query (addr1...)
|
|
|
|
**Example prompt:** "Show me the UTxOs at addr1qx..."
|
|
|
|
### vector_build_send_apex
|
|
|
|
Build an unsigned transaction sending AP3X to a recipient (keyless — takes no key material). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required) — Your wallet address; source of funds and change (addr1...)
|
|
- `recipientAddress` (string, required) — Recipient address (addr1...)
|
|
- `amount` (number, required) — Amount of AP3X to send (minimum 1)
|
|
- `metadata` (string, optional) — Transaction metadata in JSON format
|
|
|
|
**Example prompt:** "Send 5 AP3X to addr1qy..."
|
|
|
|
### vector_build_send_tokens
|
|
|
|
Build an unsigned transaction sending Vector native tokens (keyless — takes no key material). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required) — Your wallet address; source of funds and change (addr1...)
|
|
- `recipientAddress` (string, required) — Recipient address (addr1...)
|
|
- `policyId` (string, required) — Token policy ID
|
|
- `assetName` (string, required) — Asset name (can be empty)
|
|
- `amount` (string, required) — Amount of tokens to send
|
|
- `adaAmount` (number, optional) — AP3X to include with tokens
|
|
|
|
**Example prompt:** "Send 100 of token with policy abc123... to addr1qy..."
|
|
|
|
### vector_build_transaction
|
|
|
|
Build an unsigned multi-output transaction with metadata (keyless, never submits). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required) — Your wallet address; source of funds and change (addr1...)
|
|
- `outputs` (array, required) — Array of `{ address, lovelace, assets? }` objects
|
|
- `metadata` (string, optional) — JSON metadata (attached under label 674)
|
|
|
|
**Example prompt:** "Build a transaction sending 5 AP3X to addr1qx... and 3 AP3X to addr1qy..."
|
|
|
|
### vector_dry_run
|
|
|
|
Simulate a transaction without submitting — returns fee estimate and validation (keyless).
|
|
|
|
**Parameters:**
|
|
- `txCbor` (string, optional) — Hex CBOR of a built transaction to evaluate
|
|
- `outputs` (array, optional) — If no txCbor, build a TX from these outputs and evaluate
|
|
- `changeAddress` (string, optional) — Your wallet address; required when building from outputs
|
|
- `metadata` (string, optional) — JSON metadata when building from outputs
|
|
|
|
**Example prompt:** "How much would it cost to send 10 AP3X to addr1qx...?"
|
|
|
|
### vector_get_transaction_history
|
|
|
|
Get transaction history for an address via Koios indexed queries.
|
|
|
|
**Parameters:**
|
|
- `address` (string, required) — Address to query (addr1...)
|
|
- `limit` (number, optional) — Number of transactions (default: 20, max: 50)
|
|
- `offset` (number, optional) — Pagination offset (default: 0)
|
|
|
|
**Example prompt:** "Show me recent transactions for addr1qx..."
|
|
|
|
### vector_build_deploy_contract
|
|
|
|
Build an unsigned transaction deploying a Plutus/Aiken smart contract by locking funds at its script address (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required) — Your wallet address; source of funds and change (addr1...)
|
|
- `scriptCbor` (string, required) — Compiled script CBOR hex
|
|
- `scriptType` (string, required) — "PlutusV1", "PlutusV2", or "PlutusV3"
|
|
- `initialDatum` (string, optional) — Datum CBOR hex (default: void `d87980`)
|
|
- `lovelaceAmount` (number, optional) — AP3X to lock in lovelace (default: 2 AP3X)
|
|
|
|
**Example prompt:** "Deploy this smart contract with 5 AP3X locked"
|
|
|
|
### vector_build_interact_contract
|
|
|
|
Build an unsigned transaction interacting with a deployed smart contract — lock funds or spend from it (keyless). Sign the returned CBOR with your local signer, then broadcast with `vector_submit_transaction`.
|
|
|
|
**Parameters:**
|
|
- `changeAddress` (string, required) — Your wallet address; source of funds, change, and the required signer for spends (addr1...)
|
|
- `scriptCbor` (string, required) — Compiled script CBOR hex
|
|
- `scriptType` (string, required) — "PlutusV1", "PlutusV2", or "PlutusV3"
|
|
- `action` (string, required) — "spend" or "lock"
|
|
- `redeemer` (string, optional) — Redeemer CBOR hex (for spend, default: void)
|
|
- `datum` (string, optional) — Datum CBOR hex (for lock, default: void)
|
|
- `lovelaceAmount` (number, optional) — Lovelace to lock (for lock)
|
|
- `utxoRef` (object, optional) — `{ txHash, outputIndex }` for specific UTxO (for spend)
|
|
- `assets` (object, optional) — Native assets for lock: `{ "unit": "quantity" }`
|
|
|
|
**Example prompt:** "Collect funds from the escrow contract at addr1..."
|
|
|
|
## Safety Controls
|
|
|
|
The tools above are keyless and take no key material, so the server no longer enforces
|
|
spend limits on them. Spend policy is enforced by your **local signer** when it signs the
|
|
CBOR these tools return — see the security notice in the repo [README](../README.md) and
|
|
[docs/architecture/non-custodial-split.md](architecture/non-custodial-split.md).
|
|
|
|
`VECTOR_SPEND_LIMIT_PER_TX` / `VECTOR_SPEND_LIMIT_DAILY` / `VECTOR_AUDIT_LOG_PATH` still
|
|
govern the server's remaining custodial tool families (agent registry, self-improvement)
|
|
until their own keyless migration lands.
|
|
|
|
## Network Endpoints
|
|
|
|
| Service | URL | Protocol |
|
|
|---------|-----|----------|
|
|
| Ogmios | ogmios.vector.testnet.apexfusion.org | HTTP JSON-RPC + WebSocket |
|
|
| Submit API | submit.vector.testnet.apexfusion.org/api/submit/tx | HTTP POST (CBOR) |
|
|
| Koios | koios.vector.testnet.apexfusion.org | REST API |
|
|
| Explorer | vector.testnet.apexscan.org | Web UI |
|
|
|
|
## Error Handling
|
|
|
|
All tools return helpful error messages with troubleshooting tips. Common issues:
|
|
|
|
- **Insufficient balance** — Ensure the wallet at `changeAddress` has enough AP3X for the transaction + fees
|
|
- **Connection failed** — Verify Ogmios endpoint is reachable
|
|
- **Invalid address** — Vector addresses start with `addr1`
|