Chat Agent API

Overview

The Chat Agent provides a conversational interface for users to interact with the MetaVault. It handles deposits, withdrawals, balance checks, and provides public vault information while maintaining strict security boundaries.

Security Model

The Chat Agent can ONLY access data for the requesting user’s wallet address. It cannot view other users’ balances or execute admin functions.

Allowed Operations

Check user’s own balance and shares
Get wallet LINK balance
View public vault information (TVL, APY, prices)
Prepare unsigned deposit/withdrawal transactions
Check and approve token allowances

Restricted Operations

Admin functions (rebalance, harvest, parameter updates)
Strategy internals (leverage ratios, debt positions)
Other users’ private data
Risk calculations and liquidation data

Agent Tools

The Chat Agent has access to the following tools, which are invoked automatically based on user requests:

User Account Tools

get_my_balance

Gets the current user’s vault share balance and withdrawable LINK amount.

userAddress

string

required

The user’s wallet address

raw.shares

string

Raw share balance (18 decimals)

raw.withdrawable

string

Raw withdrawable LINK amount (18 decimals)

human.shares

string

Human-readable share balance

human.withdrawable

string

Human-readable withdrawable LINK amount

{
  "raw": {
    "shares": "95230000000000000000",
    "withdrawable": "100500000000000000000"
  },
  "human": {
    "shares": "95.23",
    "withdrawable": "100.50"
  }
}

get_link_balance

Returns the user’s LINK balance in their wallet.

wallet

string

required

The user’s wallet address

wallet

string

Wallet address queried

rawBalance

string

Raw LINK balance (18 decimals)

balance

string

Human-readable LINK balance

symbol

string

Token symbol (“LINK”)

message

string

Formatted message with balance

{
  "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "rawBalance": "500000000000000000000",
  "balance": "500.00",
  "symbol": "LINK",
  "message": "The wallet 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb has 500.00 LINK."
}

user_deposit

Prepares an unsigned LINK deposit transaction for the user to sign.

amount

string

required

Amount of LINK to deposit (human-readable format)

success

boolean

Always true if transaction is prepared successfully

unsignedTx

object

Unsigned transaction object

Show properties

string

Vault contract address

data

string

Encoded deposit function call

value

string

ETH value (always “0” for ERC20 deposits)

message

string

User-friendly message about the transaction

{
  "success": true,
  "unsignedTx": {
    "to": "0xVAULT_ADDRESS",
    "data": "0xb6b55f25000000000000000000000000000000000000000000000000002386f26fc10000",
    "value": "0"
  },
  "message": "Please sign this deposit transaction for 10.00 LINK."
}

user_withdraw

Prepares an unsigned withdrawal transaction for the user to sign.

string

required

Number of shares to withdraw (human-readable format)

success

boolean

Always true if transaction is prepared successfully

unsignedTx

object

Unsigned transaction object (same structure as deposit)

message

string

User-friendly message about the transaction

{
  "success": true,
  "unsignedTx": {
    "to": "0xVAULT_ADDRESS",
    "data": "0x2e1a7d4d000000000000000000000000000000000000000000000000002386f26fc10000",
    "value": "0"
  },
  "message": "Please sign this withdraw transaction for 10.00 LINK."
}

Approval Tools

check_allowance

Checks if user’s LINK token allowance is sufficient for a deposit.

wallet

string

required

User’s wallet address

amount

string

required

Desired deposit amount (human-readable)

allowance

string

Current allowance (raw 18 decimal format)

enough

boolean

Whether allowance is sufficient

needed

string

Required allowance (raw 18 decimal format)

wallet

string

Wallet address checked

{
  "allowance": "5000000000000000000",
  "enough": false,
  "needed": "10000000000000000000",
  "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}

approve_link

Prepares an unsigned approval transaction so the vault can spend LINK.

amount

string

required

Amount of LINK to approve (human-readable)

unsignedTx

object

Unsigned approval transaction

Show properties

string

LINK token contract address

data

string

Encoded approve function call

value

string

ETH value (always “0”)

message

string

User-friendly approval message

{
  "unsignedTx": {
    "to": "0xLINK_ADDRESS",
    "data": "0x095ea7b3000000000000000000000000VAULT_ADDRESS000000000000000000000000002386f26fc10000",
    "value": "0"
  },
  "message": "Please sign this transaction to approve 10.00 LINK for spending."
}

Public Information Tools

get_public_vault_info

Gets public vault information including total managed assets and total supply.

raw.totalManaged

string

Total managed assets (raw 18 decimals)

raw.totalSupply

string

Total share supply (raw 18 decimals)

human.totalManaged

string

Human-readable total managed LINK

human.totalSupply

string

Human-readable total shares

{
  "raw": {
    "totalManaged": "1000000000000000000000",
    "totalSupply": "950000000000000000000"
  },
  "human": {
    "totalManaged": "1000.00",
    "totalSupply": "950.00"
  }
}

get_token_prices

Fetches real-time LINK price from CoinGecko API.

raw.linkPriceUSD

string

LINK price in USD (scaled by 1e18)

human.linkPriceUSD

string

Human-readable LINK price

human.link24hChange

string

24-hour price change percentage

source

string

Data source (“CoinGecko API”)

{
  "raw": {
    "linkPriceUSD": "15000000000000000000"
  },
  "human": {
    "linkPriceUSD": "15.00",
    "link24hChange": "2.50%"
  },
  "source": "CoinGecko API"
}

get_vault_apy

Gets the current vault APY based on TVL growth.

apy

number

APY as a decimal (e.g., 0.12 = 12%)

readable

string

Human-readable APY percentage

message

string

Status message

tvl

number

Current total value locked

{
  "apy": 0.1245,
  "readable": "12.45%",
  "tvl": 1000000000000000000000,
  "growth": 0.05,
  "dt": 86400
}

Conversion Tools

convert_to_shares

Converts LINK amount to Vault Share Tokens (VST).

amount

string

required

Amount of LINK (human-readable format)

string

Equivalent number of shares

"95.23"

convert_to_assets

Converts Vault Share Tokens (VST) to LINK.

string

required

Amount of shares/VST (human-readable format)

linkAmount

string

Equivalent amount of LINK

"100.50"

Deposit Flow

The Chat Agent automatically handles the two-step deposit process:

Step 1: Check Allowance

When a user requests a deposit, the agent first checks if the vault has sufficient allowance to spend the user’s LINK tokens.

User requests deposit

User: “Deposit 10 LINK”

Agent checks allowance

Agent calls check_allowance(wallet, "10")

Approval required

If allowance is insufficient, agent calls approve_link("10") and returns approval transaction

User signs approval

User signs the approval transaction in their wallet

Deposit transaction

After approval is confirmed, agent calls user_deposit("10") and returns deposit transaction

User signs deposit

User signs the deposit transaction to complete the deposit

Example Chat Interaction

curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Deposit 10 LINK",
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "sessionId": "user123"
  }'

{
  "success": true,
  "sessionId": "user123",
  "reply": "To deposit 10 LINK, you first need to approve the vault to spend your LINK tokens. Please sign this approval transaction.",
  "unsignedTx": {
    "to": "0xLINK_ADDRESS",
    "data": "0x095ea7b3...",
    "value": "0"
  },
  "step": "approval"
}

Withdrawal Flow

Withdrawals are simpler and only require one transaction:

User requests withdrawal

User: “Withdraw 5 LINK”

Agent prepares transaction

Agent calls user_withdraw("5") and returns unsigned transaction

User signs withdrawal

User signs the withdrawal transaction to receive LINK

Response Format

All Chat Agent responses follow a structured JSON format when tools are used:

{
  "reply": "Human-friendly message",
  "unsignedTx": null | { /* transaction object */ },
  "needsApproval": true | false | null,
  "step": "approval" | "deposit" | "withdrawal" | "info"
}

reply: Text response for the user
unsignedTx: Transaction to sign (if applicable)
needsApproval: Whether an approval is needed before proceeding
step: Current stage in the transaction flow

Error Handling

The Chat Agent returns user-friendly error messages:

{
  "success": false,
  "error": "Insufficient LINK balance. You need 10 LINK but only have 5 LINK."
}

Common error scenarios:

Insufficient LINK balance
Insufficient share balance for withdrawal
Invalid wallet address
Network errors (CoinGecko API failures)
Contract call failures

Smart Contracts

Agent API

Overview

Security Model

Allowed Operations

Restricted Operations

Agent Tools

User Account Tools

get_my_balance

get_link_balance

user_deposit

user_withdraw

Approval Tools

check_allowance

approve_link

Public Information Tools

get_public_vault_info

get_token_prices

get_vault_apy

Conversion Tools

convert_to_shares

convert_to_assets

Deposit Flow

Step 1: Check Allowance

Example Chat Interaction

Withdrawal Flow

Response Format

Error Handling

Build docs developers (and LLMs) love

Smart Contracts

Agent API

​Overview

​Security Model

​Allowed Operations

​Restricted Operations

​Agent Tools

​User Account Tools

​get_my_balance

​get_link_balance

​user_deposit

​user_withdraw

​Approval Tools

​check_allowance

​approve_link

​Public Information Tools

​get_public_vault_info

​get_token_prices

​get_vault_apy

​Conversion Tools

​convert_to_shares

​convert_to_assets

​Deposit Flow

​Step 1: Check Allowance

​Example Chat Interaction

​Withdrawal Flow

​Response Format

​Error Handling

Build docs developers (and LLMs) love

Overview

Security Model

Allowed Operations

Restricted Operations

Agent Tools

User Account Tools

get_my_balance

get_link_balance

user_deposit

user_withdraw

Approval Tools

check_allowance

approve_link

Public Information Tools

get_public_vault_info

get_token_prices

get_vault_apy

Conversion Tools

convert_to_shares

convert_to_assets

Deposit Flow

Step 1: Check Allowance

Example Chat Interaction

Withdrawal Flow

Response Format

Error Handling