For AI Agents

Building Atomic Transactions

How an AI agent builds and executes a complete flash loan — from discovery to signed transaction.

Agent Flow

Discover vaea_get_capacity

Agent checks what tokens and how much liquidity is available.

Plan vaea_find_best_route

Agent finds the optimal protocol. Evaluates cost, confidence, alternatives.

Validate vaea_check_profitability

Agent checks if the strategy is profitable after all costs (fee + gas + tip).

Build vaea_build_flash_loan

Agent gets back a serialized TX with an _agent_hint marking where to insert logic.

Insert (agent logic)

Agent builds its own instructions (arb, liquidation, swap) and inserts them at _agent_hint.

Sign (user wallet)

Agent presents the TX to the user for signing. MCP server never touches keys.

Building the TX

vaea_build_flash_loan returns a serialized transaction with this structure:

// Transaction structure
┌──────────────────────────────────┐
│ begin_flash(SOL, 1000)          │  ← VAEA borrows from protocol
│                                  │
│ _agent_hint: INSERT_LOGIC_HERE  │  ← Agent inserts its IX here
│                                  │
│ end_flash(SOL, 1000 + fee)      │  ← VAEA repays protocol
└──────────────────────────────────┘

Inserting Agent Logic

The _agent_hint field tells the agent exactly where in the transaction to insert its custom instructions. The agent builds its own logic (arbitrage swap, liquidation call, etc.) and places it between begin_flash and end_flash.

⚠️ Warning

The borrowed funds must be fully repaid (amount + fee) by the end of the transaction. If repayment fails, the entire transaction reverts atomically. No partial execution.

Signing & Sending

The MCP server returns an unsigned serialized transaction. The agent must:

Present to user

Show the TX details for user review and approval.

Sign with wallet

Use the user's wallet (Phantom, Solflare, etc.) to sign.

Send to RPC

Submit the signed TX to a Solana RPC node.

Confirm

Wait for confirmation. If it fails, the TX reverts atomically.

Full Example

Here's what a complete conversation between an AI agent and the MCP server looks like:

Agent: "I want to arbitrage SOL across Orca and Raydium"
→ vaea_get_capacity({"token":"SOL"})
  ← 245,000 SOL available, $36.7M
→ vaea_find_best_route({"token":"SOL","amount":1000})
  ← Marginfi, 2.1 bps, confidence 0.95
→ vaea_check_profitability({"token":"SOL","amount":1000,"expected_revenue":0.5})
  ← net: 0.29 SOL, recommendation: "send"
→ vaea_build_flash_loan({"token":"SOL","amount":1000,"user_pubkey":"..."})
  ← serialized TX with _agent_hint
Agent: "Here's the transaction. It borrows 1000 SOL, swaps on Orca,
        sells on Raydium, and repays. Expected profit: 0.29 SOL.
        Please sign to execute."