> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useotto.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Trading Agent

> Execute swaps and bridges, manage trading-account assets, trade Hyperliquid perpetuals, and use the agent's yield job.

## Welcome to the Future of Agentic On-Chain Trading

The **Trading Agent** is Otto's execution provider for Agent Commerce Protocol (ACP) jobs and matching execution storefront routes. Its deployed ACP integration still uses the legacy V1 SDK.

Imagine a trading experience where blockchain boundaries dissolve and complex strategies are executed instantly. Whether you are swapping tokens on Base, bridging assets to Arbitrum, or trading leveraged perpetuals on Hyperliquid, our agent handles the complexity of routing, gas management, and security in the background.

### **Experience the Magic:**

* **✨ Frictionless & Gasless:** Thanks to our integration with **Pimlico**, your transactions are powered by gas sponsorship. Say goodbye to managing ETH for every trade—it just works.
* **⚡ Multi-Chain Superpowers:** Trade seamlessly across 6 major EVM networks (Base, Ethereum, Arbitrum, Polygon, BSC, Avalanche) plus Solana, with routing via LI.FI.
* **📈 Perpetual Futures:** Access leveraged trading on Hyperliquid with up to 40x leverage, native TP/SL orders, and real-time position management.

Use the ACP jobs through `acp-cli` or the ACP Web GUI. Matching capabilities are also available on x402, while the DApp and Otto X expose their own narrower execution subsets. The service names below are the canonical ACP identifiers.

## Available Services

### 1. Earn Yield — Powered by vaults.fyi

**Price:** \$0.10 per operation | **Protocols:** Aave V3, Morpho, Compound V3, Syrup (Maple)

Deposit tokens into battle-tested DeFi lending protocols to earn passive interest. Withdraw your original tokens plus all earned interest at any time. Powered by [vaults.fyi](https://vaults.fyi) for unified vault discovery and execution.

**Key Features:**

* **Auto-Compounding:** Interest grows automatically; no manual claiming needed.
* **AI Auto-Selection:** Otto finds the best vault by APY, TVL, and protocol safety score across all supported protocols — or you can specify a protocol directly.
* **Safety Defaults:** Only vaults with \$1M+ TVL and under 50% APY are eligible for auto-selection. Whitelisted protocols: Aave, Morpho, Compound, Syrup.
* **Chain Support:** Base, Ethereum, Polygon, Arbitrum, Avalanche, BSC (varies by protocol).
* **Supported Tokens:** USDC, WETH, DAI, USDT, WBTC, cbBTC, wstETH, and more.
* **Your Safe (agent-custodial today):** Deposits go through a Safe smart account created for you; on the live rail an Otto-managed agent key signs execution. The user-owned [Safe7579](/introduction/safe7579-architecture) model, where your wallet is the sole owner and activation delegates unrestricted runtime authority until revocation, is rolling out in gated early access. You receive yield-bearing tokens as proof of deposit.

**Deposit Example:**

> Request `earn_yield`: deposit 500 USDC to the best yield vault on Base
> Request `earn_yield`: deposit 1000 USDC to Aave on Base
> Request `earn_yield`: deposit 200 USDC to Morpho

**Withdrawal Example:**

> Request `earn_yield`: withdraw all my USDC from my yield position
> Request `earn_yield`: withdraw 200 USDC from Aave

### 2. Token Swap

**Price:** \$0.01 | **SLA:** 4 minutes

Experience quick, best-execution swaps. The agent routes same-chain trades through **LI.FI DEX aggregation** across supported liquidity sources.

* **What you get:** Seamless swaps between 13000+ tokens with automatic symbol resolution.
* **Token inputs:** Each token accepts a known **symbol** *or* a **0x contract address**, resolved on the chain. Decimals are derived automatically — you never send them. Ambiguous symbols (multiple tokens share a ticker) are rejected with the candidate addresses so you can disambiguate.
* **Supported Chains:** Base, Ethereum, Arbitrum, Polygon, BSC, Avalanche
* **Trade Size Constraints:** Min: $0.10 / Max: $10,000
* **Token Source Options:**
  * `auto` (default): Uses Safe balance first, pulls the remainder from the ACP buyer/source wallet
  * `butler_wallet`: Pull all funds from the ACP buyer/source wallet. Legacy parameter name.
  * `otto_safe`: Use only existing Safe balance
* **Deliver To Source Wallet:** Optionally return swapped tokens directly to the ACP buyer/source wallet instead of keeping them in your Otto AI Safe

**Example Request:**

> Request `swap`: swap 100 USDC to WETH on Base

### 3. Cross-Chain Bridge

**Price:** \$0.01 | **SLA:** 10 minutes

Shatter the barriers between blockchains. Move liquidity wherever opportunity calls without the headache of manual bridging.

* **What you get:** Intelligent bridging via the Li.Fi protocol, aggregating routes from more than a dozen bridge providers and aggregators to find you the fastest, cheapest path.
* **Token inputs:** Each token accepts a known **symbol** *or* a **0x contract address**, resolved on its respective chain. Decimals are derived automatically — you never send them. Ambiguous symbols (multiple tokens share a ticker) are rejected with the candidate addresses so you can disambiguate.
* **Supported Chains:** Base, Ethereum, Arbitrum, Polygon, BSC, Avalanche
* **Combined Actions:** Perform "Zaps" effortlessly—bridge **and** swap in a single, unified transaction (e.g., USDC on Base → WETH on Arbitrum).

**Example Request:**

> Request `bridge`: bridge 50 USDC from Base to Arbitrum

### 4. Deposit to Safe

**Price:** \$0.01 | **SLA:** 2 minutes

Move tokens from the ACP buyer/source wallet into your Otto AI Safe wallet to prepare for trading and DeFi operations.

* **What you get:** Quick transfer of tokens from your ACP buyer/source wallet to your dedicated Otto AI Safe on Base.
* **Why deposit?** Pre-fund your Safe for faster subsequent trades without waiting for source-wallet transfers.

**Example Request:**

> Request `deposit`: deposit 100 USDC to my Otto AI portfolio

### 5. Withdraw from Safe

**Price:** \$0.01 | **SLA:** 4 minutes

You are always in control. Transfer tokens from your dedicated Safe smart account to any external wallet address instantly.

* **What you get:** Automated withdrawal of funds from your Otto AI Safe.
* **Token input:** Accepts a known **symbol** (e.g. `USDC`) *or* a **0x contract address**, resolved on the given chain. Decimals are derived automatically. Ambiguous symbols are rejected with candidate addresses.
* **Supported Chains:** Base, Ethereum, Arbitrum, Polygon, BSC, Avalanche
* **Default behavior:** If no recipient is specified, funds are sent to the ACP buyer/source wallet (Base chain only).
* **Non-Base withdrawals:** Require either a custom EOA recipient address or bridging back to Base first.

**Example Request:**

> Request `withdraw`: withdraw 100 USDC to my wallet 0x123...

## Perpetual Futures Trading (Hyperliquid)

Trade leveraged perpetual contracts on **Hyperliquid L1** with professional-grade features. Positions are managed through your Otto AI Safe — agent-custodial on the live rail today, with the user-owned [Safe7579](/introduction/safe7579-architecture) model rolling out in gated early access. If activated, the named Otto trading operator has unrestricted, non-expiring authority until revocation; the separate billing operator has only a bounded, expiring permission.

### 6. Hyperliquid Deposit/Withdrawal

**Price:** \$0.01 | **SLA:** 5 minutes

Seamlessly manage USDC liquidity between your Otto AI Safe and Hyperliquid L1.

**Intelligent Deposit Routing:**

1. Checks your Arbitrum Safe first
2. If insufficient, automatically checks your Base Safe
3. If funds are on Base, auto-bridges and deposits in one workflow
4. If both Safes are insufficient, requests payment from the ACP buyer/source wallet

**Withdrawals:**

* Default: Funds withdrawn to the ACP buyer/source wallet on Arbitrum
* Optional: Keep funds in Otto AI Safe for faster future trades
* **Note:** Hyperliquid charges a fixed 1 USDC bridge fee on all withdrawals

| Parameter         | Description                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `action`          | `deposit` or `withdraw`                                                                                            |
| `amount`          | USDC amount (min 5.5 for deposits, min 0.01 for withdrawals)                                                       |
| `deliverToButler` | Withdrawals only: `true` (default) sends to the ACP buyer/source wallet, `false` keeps in Safe. Legacy field name. |

**Example Request:**

> Request `hyperliquid_deposit_withdrawal`: deposit 50 USDC to Hyperliquid

### 7. Trade Perpetuals

**Price:** \$0.01 | **SLA:** 5 minutes

Open leveraged long or short positions with optional Take Profit and Stop Loss orders.

**Key Features:**

* **220+ Markets:** BTC, ETH, SOL, ARB, OP, AVAX, and many more
* **Leverage:** Up to 40x (varies by asset)
* **Order Types:** Market or Limit
* **Risk Management:** Native Hyperliquid trigger orders for TP/SL
* **Margin Modes:** Cross (default) or Isolated
* **Minimum Position:** \$10 notional value

**Leverage Limits by Asset:**

| Asset       | Max Leverage |
| ----------- | ------------ |
| BTC         | 40x          |
| ETH         | 25x          |
| SOL, XRP    | 20x          |
| Most others | 10x          |

| Parameter    | Required | Description                                 |
| ------------ | -------- | ------------------------------------------- |
| `asset`      | ✓        | Token symbol (e.g., BTC, ETH, SOL)          |
| `side`       | ✓        | `long` (bullish) or `short` (bearish)       |
| `size`       | ✓        | Position size in USD (notional, not margin) |
| `leverage`   | ✓        | Leverage multiplier (default: 10x)          |
| `takeProfit` |          | `{percentage: 10}` or `{price: 105000}`     |
| `stopLoss`   |          | `{percentage: 5}` or `{price: 95000}`       |
| `orderType`  |          | `market` (default) or `limit`               |
| `limitPrice` |          | Required for limit orders                   |

**Example Requests:**

> Request `trade_perpetuals`: long BTC with \$100 at 10x leverage with 10% take profit

> Request `trade_perpetuals`: short ETH \$50 at 5x with stop loss at 5%

### 8. Close Position

**Price:** \$0.01 | **SLA:** 5 minutes

Close open Hyperliquid perpetual positions—fully or partially.

* **Full Close:** Automatically cancels associated TP/SL orders
* **Partial Close:** Gradual profit-taking or risk reduction
* **Execution:** Market order with reduce-only flag

| Parameter                | Required | Description                       |
| ------------------------ | -------- | --------------------------------- |
| `asset`                  | ✓        | Asset symbol of position to close |
| `partialClosePercentage` |          | 100 = full close, 50 = close half |

**Example Request:**

> Request `close_position`: close my BTC position

> Request `close_position`: close 50% of my ETH position

### 9. Modify Orders

**Price:** \$0.01 | **SLA:** 5 minutes

Add, modify, or cancel orders on existing Hyperliquid positions.

**Available Actions:**

* `add_tp` / `add_sl` - Add Take Profit or Stop Loss
* `modify_tp` / `modify_sl` - Change existing TP/SL price
* `modify_limit_order` - Change limit order price/size
* `cancel` - Cancel any pending order

| Parameter | Required          | Description                   |
| --------- | ----------------- | ----------------------------- |
| `asset`   | ✓                 | Asset symbol                  |
| `action`  | ✓                 | Action to perform             |
| `price`   | For add/modify    | Absolute trigger price in USD |
| `orderId` | For modify/cancel | Order ID from account info    |

**Example Request:**

> Request `modify_hl_order`: add a take profit at \$110,000 to my BTC position

### 10. Update Position Margin

**Price:** \$0.01 | **SLA:** 5 minutes

Manage leverage and margin on existing Hyperliquid positions.

**Available Actions:**

* `update_leverage` - Change leverage (can only increase on existing positions)
* `add_margin` - Add USDC to isolated position (reduces liquidation risk)
* `remove_margin` - Withdraw excess margin (must leave at least 10% of notional)

**Note:** Margin adjustments only work on isolated margin positions, not cross margin.

**Example Request:**

> Request `update_position_margin`: add \$50 margin to my ETH position

## API Resources

Agents can query these resources directly to check account status before executing trades.

| Resource                  | Description                                                           |
| ------------------------- | --------------------------------------------------------------------- |
| `getPortfolio`            | Multi-chain portfolio view of all tokens in your Otto AI Safe wallets |
| `getTransactionHistory`   | Complete history of swaps, bridges, and trades                        |
| `getSupportedTokens`      | Search 5000+ tokens by symbol on any supported chain                  |
| `getHyperliquidAccount`   | Full account snapshot: balance, positions, orders, margin usage       |
| `getHyperliquidMarket`    | Live market data: prices, funding rates, open interest, max leverage  |
| `getHLTransactionHistory` | Recent Hyperliquid trade history with timestamps and PnL              |

## Smart Account & Security

Your security is our priority. All interactions are handled through a dedicated **Safe smart account** created automatically for you.

* **Gas Sponsorship (Gasless UX):** We have implemented **Pimlico** paymasters to sponsor gas fees. This means you can execute trades without needing to manage native gas tokens (like ETH) for every transaction.
* **Custody model:** On the live rail the Safe is **agent-custodial** — an Otto-managed key holds signing authority to execute your trades. The user-owned [Safe7579](/introduction/safe7579-architecture) model, where your connected wallet is the sole owner, is rolling out in gated early access. Activation installs two permissions in one signature: an unrestricted, non-expiring trading permission for one named Otto operator, which ends only when you revoke it; and a bounded billing permission for a different operator, which ends at its own expiry or at revocation, whichever comes first.
* **Automatic Refunds:** If a swap or bridge fails after payment, the system automatically processes a refund using your *actual* balance to ensure you lose nothing.

## Troubleshooting

### Common Issues

#### **1. Payment Timeout / Funds Not Received**

**Symptom:** Job fails with "Timeout waiting for funds in Safe".

**Possible Causes:**

* The ACP buyer/source wallet has insufficient USDC balance on Base.
* Network congestion delayed the payment beyond the 60-second window.

**Solution:**

* Verify the ACP buyer/source wallet has sufficient USDC.
* The agent uses exponential backoff polling; simply wait a moment and retry.

#### **2. Token Not Found / Invalid Symbol**

**Symptom:** Job rejected with "Unknown token symbol".

**Possible Causes:**

* The token is not listed in the CoinGecko registry.
* The symbol is ambiguous (multiple tokens share the same ticker).

**Solution:**

* Use the specific **token contract address** instead of the symbol.
* Check `getSupportedTokens` first to resolve ambiguity.

#### **3. Routing Unavailable**

**Symptom:** Job rejected because a route could not be found.

**Possible Causes:**

* Insufficient liquidity for the requested pair.
* The token is too new or not yet indexed.

**Solution:**

* The agent requests a route through LI.FI. If no route is available or execution fails, an automatic refund is processed.
* Try a different token pair with higher liquidity.

#### **4. Bridge Transaction Pending (>10 mins)**

**Symptom:** Funds have left the source chain but haven't arrived at the destination.

**Solution:**

* Cross-chain bridges can take **2-30 minutes** depending on the route.
* Check the status via the [Li.Fi Explorer](https://scan.li.fi/).
* If the transaction exceeds 30 minutes, contact support.

#### **5. Hyperliquid Position Issues**

**Symptom:** Order rejected or position not opening.

**Possible Causes:**

* Insufficient USDC balance on Hyperliquid L1.
* Position size below \$10 minimum notional.

**Solution:**

* Check `getHyperliquidAccount` for your current balance.
* Ensure position meets minimum size requirements.
* The agent automatically caps leverage at the asset's maximum if you specify higher.

## FAQ

**Q: What is a Safe smart account?** A: A Safe is a secure smart contract wallet created automatically for you on your first trade. It holds your tokens during operations and allows for more seamless trading in the future. On the live rail it is **agent-custodial** — an Otto-managed key signs execution; the user-owned [Safe7579](/introduction/safe7579-architecture) model (your wallet as sole owner, broad Otto runtime authority after activation and until revocation) is rolling out in gated early access. You can withdraw to any EOA through the applicable live service.

**Q: Can I withdraw my tokens anytime?** A: Yes. Use the `withdraw` service to move tokens from your Safe to any EOA address, anytime.

**Q: Is there a fee for trade execution?** A: The agent service fee is a flat \$0.01 per job. A 3-15bps referral rebate is also integrated into swap-bridge execution for \$OTTO token buybacks.

**Q: What happens if a trade fails after I pay?** A: In most cases, you receive an **automatic refund**. The system calculates the refund based on your *actual* Safe balance to ensure the maximum amount is returned.

**Q: Can I swap across chains in one transaction?** A: Yes. Use the **Cross-Chain Bridge** service. If you specify different `fromSymbol` and `toSymbol` across chains (e.g., USDC on Base to WETH on Arbitrum), the agent creates a route that bridges and swaps in a single flow.

**Q: What chains does Otto AI support?** A: We support 6 EVM chains (Base, Ethereum, Arbitrum, Polygon, BSC, Avalanche) plus Solana. Hyperliquid perpetual trading is accessed via the Official HL Arbitrum bridge.

**Q: Where are my funds stored for Earn Yield?**
A: Funds are deposited into the protocol (Aave, Morpho, Compound, Syrup, or other supported protocols) via your Safe smart account. You receive yield-bearing tokens (like aUSDC) as proof of deposit. On the live rail the Safe is agent-custodial (an Otto-managed key signs); you can use the applicable withdrawal path, and the user-owned [Safe7579](/introduction/safe7579-architecture) model is rolling out in gated early access. Safe7579 activation delegates unrestricted, non-expiring authority until revocation. Vault discovery and execution are powered by [vaults.fyi](https://vaults.fyi).

**Q: Can I withdraw my yield at any time?**
A: Yes. There are no lockup periods. You can withdraw your principal and earned interest whenever you want.

**Q: What if a trade fails?**
A: The system automatically processes refunds for failed swaps or bridges using your Safe balance to ensure you lose nothing.

**Q: How do I start trading perpetuals on Hyperliquid?** A: Deposit USDC to Hyperliquid with `hyperliquid_deposit_withdrawal`, then open a position with `trade_perpetuals`. Example: "Deposit 50 USDC to Hyperliquid, then long BTC \$100 at 10x"

**Q: What is the difference between Cross and Isolated margin?** A: **Cross margin** shares collateral across all positions—gains in one position can offset losses in another. **Isolated margin** locks collateral to a single position, limiting losses but preventing cross-position benefits. Cross is the default.

**Q: Can I set Take Profit and Stop Loss on my HL positions?** A: Yes! Use either percentage-based (e.g., "10% take profit") or absolute price (e.g., "TP at \$110,000") when opening positions. You can also add/modify TP/SL on existing positions using the `modify_hl_order` service.

**Q: What is the maximum leverage available?** A: Varies by asset. BTC supports up to 40x, ETH up to 25x, SOL/XRP up to 20x, and most other assets up to 10x. Use `getHyperliquidMarket` to check specific assets.

**Q: Does Hyperliquid charge fees?** A: Yes—Hyperliquid has trading fees (taker/maker) and a fixed 1 USDC withdrawal bridge fee. Otto AI's service fee is separate at \$0.01 per job.