Chat Agent API - MetaVault AI

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.

string

required

The user’s wallet address

string

Raw share balance (18 decimals)

string

Raw withdrawable LINK amount (18 decimals)

string

Human-readable share balance

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.

string

required

The user’s wallet address

string

Wallet address queried

string

Raw LINK balance (18 decimals)

string

Human-readable LINK balance

string

Token symbol (“LINK”)

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.

string

required

Amount of LINK to deposit (human-readable format)

boolean

Always true if transaction is prepared successfully

object

Unsigned transaction object

Show properties

string

Vault contract address

string

Encoded deposit function call

string

ETH value (always “0” for ERC20 deposits)

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)

boolean

Always true if transaction is prepared successfully

object

Unsigned transaction object (same structure as deposit)

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.

string

required

User’s wallet address

string

required

Desired deposit amount (human-readable)

string

Current allowance (raw 18 decimal format)

boolean

Whether allowance is sufficient

string

Required allowance (raw 18 decimal format)

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.

string

required

Amount of LINK to approve (human-readable)

object

Unsigned approval transaction

Show properties

string

LINK token contract address

string

Encoded approve function call

string

ETH value (always “0”)

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.

string

Total managed assets (raw 18 decimals)

string

Total share supply (raw 18 decimals)

string

Human-readable total managed LINK

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.

string

LINK price in USD (scaled by 1e18)

string

Human-readable LINK price

string

24-hour price change percentage

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.

number

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

string

Human-readable APY percentage

string

Status message

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).

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)

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

​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

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