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_check_capacity

Agent checks what tokens and how much liquidity is available.

Plan vaea_find_best_route

Agent finds the optimal protocol. Evaluates cost and 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 prefix/suffix instructions with an _agent_hint marker.

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. Plugins never touch keys.

Transaction Structure

vaea_build_flash_loan returns prefix + suffix instructions that wrap the agent's logic:

// Atomic sandwich transaction
┌──────────────────────────────────┐
│ 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 + collects fee
└──────────────────────────────────┘

⚠️ Warning

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

Signing & Sending

The plugin returns an unsigned serialized transaction. The agent must:

Present to user

Show the TX details for review and approval.

Sign with wallet

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

Send to RPC

Submit the signed TX to Solana.

Confirm

Wait for confirmation. Reverts atomically on failure.

Full Example

Complete interaction between an AI agent and the VAEA plugin:

Agent: "I want to arbitrage SOL across Orca and Raydium"
→ vaea_check_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."