# Pods API

> Pods API is a DeFi aggregation platform that enables cross-chain and same-chain token swaps, yield strategies, and DeFi protocol integrations. The API provides quotes, transaction bytecode generation, and monitoring for blockchain transactions across Ethereum Mainnet, Polygon, Arbitrum, Optimism, Base, Avalanche, Gnosis, BNB Chain, HyperEVM, Solana and Bitcoin networks.

Pods operates as a trustless platform where users maintain full custody of their funds. The API aggregates multiple swap providers (1inch, Jupiter, TeleSwap, Mayan, Relay, LiFi, Uniswap) and DeFi protocols (Aave, Morpho, Lido, Compound) to provide optimal rates and routes for swaps and yield opportunities.

**Key Constraints**: All requests require an API key via `x-api-key` header. Quotes expire after 5 minutes.

## Overview

- [Introduction](https://docs.pods.finance/): Welcome to Pods API with key features, supported networks, and quick examples
- [Quickstart](https://docs.pods.finance/getting-started/quickstart): Get your first API call running in 5 minutes
- [Architecture Overview](https://docs.pods.finance/getting-started/architecture): System architecture, trustless operation flow, and API patterns
- [Authentication](https://docs.pods.finance/getting-started/authentication): How to authenticate API requests using API keys
- [Why Pods](https://docs.pods.finance/getting-started/why-pods): The case for using Pods vs building in-house
- [Error Codes](https://docs.pods.finance/error-codes): Complete reference for all API error codes, HTTP status codes, and resolution guidance
- [Changelog](https://docs.pods.finance/changelog): API updates, new features, and documentation changes

## Fees

[Fees](/getting-started/fees): Pods charges 25 BPS (0.25%) on swap transactions and a 5% performance fee on yield position exits. Integrators can add custom markup fees (both for swaps and yield performance) by contacting support. A self-service admin page for markup fee management is coming soon.

## Guides

### Yield Strategies
- [Check Protocol Info](https://docs.pods.finance/guides/yield/check-protocol-info): Retrieve yield protocol information including APY rates and terms
- [Deposit to Yield](https://docs.pods.finance/guides/yield/deposit): Generate transaction bytecode for depositing into yield positions
- [Check Open Positions](https://docs.pods.finance/guides/yield/check-positions): Retrieve and monitor current yield positions for wallet addresses
- [Withdraw from Yield](https://docs.pods.finance/guides/yield/withdraw): Generate transaction bytecode for withdrawing from yield positions

### Swaps
- [Get a Quote](https://docs.pods.finance/guides/swaps/get-quote): Learn how to request quotes for same-chain and cross-chain token swaps
- [Execute Swap](https://docs.pods.finance/guides/swaps/execute-swap): Generate bytecode and execute token swaps using quotes

## Code Examples

- [Same-Chain Swap](https://docs.pods.finance/examples/javascript/same-chain-swap): Complete example of executing a same-chain token swap with ethers.js and viem
- [Cross-Chain Swap](https://docs.pods.finance/examples/javascript/cross-chain-swap): Complete example of executing cross-chain token swaps with bridge integration
- [Strategy Deposit](https://docs.pods.finance/examples/javascript/strategy-deposit): Complete example of depositing funds into DeFi yield strategies
- [EIP-7702 Batch Deposit](https://docs.pods.finance/examples/javascript/using-eip7702): Batch multiple DeFi transactions into a single atomic operation using EIP-7702

## API Reference

- [API Introduction](https://docs.pods.finance/api-reference/introduction): Overview of the Pods API with base URL, authentication, and quick links
- [Health](https://docs.pods.finance/api-reference/endpoint/get-health): Check API health status
- [Swap — Get Quote](https://docs.pods.finance/api-reference/endpoint/get-v2-swap-quote): Request a quote for same-chain or cross-chain token swaps. Optionally include `originAddress` + `destinationAddress` to receive inline bytecode without a separate call to the bytecode endpoint. Quotes include a `feeBreakdown` field itemizing platform fees and bridge/slippage impact.
- [Swap — Generate Bytecode](https://docs.pods.finance/api-reference/endpoint/post-v2-swap-bytecode): Generate ready-to-sign transaction data from a confirmed quote
- [Swap — Check Status](https://docs.pods.finance/api-reference/endpoint/get-v2-swap-status-id): Poll swap transaction status through its lifecycle
- [Tracking — List](https://docs.pods.finance/api-reference/endpoint/get-actions): List tracked swap, transfer, and strategy operations
- [Tracking — Get by ID](https://docs.pods.finance/api-reference/endpoint/get-actions-id): Retrieve execution status details by ID
- [Strategies — List](https://docs.pods.finance/api-reference/endpoint/get-strategies): List all available DeFi yield strategies
- [Strategies — Get by ID](https://docs.pods.finance/api-reference/endpoint/get-strategies-id): Retrieve a single strategy with full details
- [Strategies — Bytecode](https://docs.pods.finance/api-reference/endpoint/get-strategies-strategyid-bytecode): Generate bytecode for depositing into or withdrawing from a yield strategy
- [Wallets — Positions](https://docs.pods.finance/api-reference/endpoint/get-wallets-wallet): Retrieve open yield positions for a wallet address
- [Wallets — History](https://docs.pods.finance/api-reference/endpoint/get-wallets-wallet-history-strategyid): Retrieve transaction history for a wallet in a specific strategy
- [Yield — Get by Identifier](https://docs.pods.finance/api-reference/endpoint/get-yield-identifier): Get the highest-APY strategy matching an asset name or category

## Protocols & Integrations

- [Supported Protocols](https://docs.pods.finance/protocols): Full list of supported DeFi protocols and networks with chain availability
- [Widget Integration Overview](https://docs.pods.finance/widget-integration): Integration paths for API-only and SDK widget flows
- [EarnWidget Integration](https://docs.pods.finance/widgets/earn-widget): Full customer integration for yield UI + API + tx execution
- [SwapWidget Integration](https://docs.pods.finance/widgets/swap-widget): Full customer integration for same-chain and cross-chain swap UI + API
- [processBytecode Contract](https://docs.pods.finance/widgets/process-bytecode): Required host tx bridge status lifecycle
- [LLM Integration Playbook](https://docs.pods.finance/widgets/llm-playbook): Prompt template and acceptance checklist for AI-assisted integrations
- [Privy Integration](https://docs.pods.finance/external-integrations/privy-integration): Integrate Pods with Privy wallet authentication
- [Fireblocks Integration](https://docs.pods.finance/external-integrations/fireblocks-integration): Integrate Pods with Fireblocks custody — covers Omnibus Account vs Segregated Vaults architectures, Smart Wallet provisioning, and a `@fireblocks/ts-sdk` example for submitting Pods-generated `transactionData` via `fireblocks.transactions.createTransaction()`
- [Dynamic Integration](https://docs.pods.finance/external-integrations/dynamic-integration): Integrate Pods with Dynamic wallet management
- [Notus Integration](https://docs.pods.finance/external-integrations/notus-integration): Account abstraction integration with Notus smart wallets and ERC-4337 user operations

### Iframe
- [Iframe Overview](https://docs.pods.finance/iframe/overview): Embed Pods widgets in any stack using a hosted iframe and postMessage protocol
- [Iframe + Privy](https://docs.pods.finance/iframe/privy): Iframe wrapper using Privy authentication with embedded smart wallets and multi-chain support
- [Iframe + Wagmi/Viem](https://docs.pods.finance/iframe/wagmi-viem): Iframe wrapper using browser wallets with ERC-4337 smart accounts via permissionless

## MCP Server

The Pods MCP Server exposes the full Pods API as discoverable, typed tools for MCP-compatible AI hosts (Claude Desktop, Cursor, Windsurf). Install with `npx pods-mcp` and configure your API key — no raw HTTP requests needed.

- [MCP Server Overview](https://docs.pods.finance/ai-tools/mcp-server): What the server does, when to use it, and the minimal tool set for common agent workflows
- [MCP Server Setup](https://docs.pods.finance/ai-tools/mcp-setup): Step-by-step installation for Claude Desktop, Cursor, Windsurf, and HTTP team deployments
- [MCP Tools Reference](https://docs.pods.finance/ai-tools/mcp-tools-reference): Complete reference for all 21 tools and 7 prompts

**21 tools across four categories:**
- Shared (5): `recommend_integration_path`, `get_health`, `validate_api_key`, `list_tokens`, `get_error_explanation`
- Swap (3): `get_swap_quote`, `execute_swap_bytecode`, `get_swap_status`
- Yield (7): `list_strategies`, `get_strategy`, `get_strategy_quote`, `get_deposit_bytecode`, `get_withdraw_bytecode`, `get_wallet_positions`, `get_wallet_history`
- Code generation (1): `get_code_example` — supports typescript, javascript, python, go, curl
- SDK Widgets (4): `scaffold_project`, `validate_provider_config`, `check_sdk_compatibility`, `setup_env`

**7 pre-built prompts:** `choose_integration_path`, `troubleshoot`, `api_quickstart`, `api_integration_wizard`, `sdk_quickstart`, `sdk_integration_wizard`, `sdk_migration_guide`

## Key Concepts

**Same-Chain Swaps**: Token swaps executed on a single blockchain network using DEX aggregators like 1inch. Transactions complete immediately with 2-3 steps: approve, swap, and optional tracking.

**Cross-Chain Swaps**: Token swaps across different blockchain networks using bridge providers like Relay, LiFi, Mayan, CCTP, TeleSwap, or Symbiosis. Quote status values are `pending`, `confirmed`, `processing`, `fulfilled`, `expired`, `failed`, and `refunded`.

**Yield Strategies**: Deposit tokens into DeFi lending and staking protocols to earn passive income. The API supports Aave, Morpho, Lido, Compound, and other protocols across multiple networks.

**Bytecode Generation**: The API generates ready-to-execute transaction data (bytecode) that users sign and broadcast using their own wallets. Pods never has custody of funds.

**Quote System**: Quotes expire after 5 minutes. Each quote includes a `quoteId`, expected amounts, provider information, and deadline timestamp. Use `quoteId` with `/v2/swap/status/{id}`. When both `originAddress` and `destinationAddress` are passed to `GET /v2/swap/quote`, the response includes ready-to-sign `transactionData` alongside the quote — no separate `POST /v2/swap/bytecode` call is needed.

**Execution Tracking**: Swap bytecode and strategy bytecode responses include an `id`. Use `GET /actions/{id}` for execution status tracking, especially for cross-chain swaps, deposits, and withdrawals.

**Webhook Notifications**: Configure webhooks to receive real-time updates for cross-chain transaction status changes.

## Optional

- [API Status](https://pods.betteruptime.com): Real-time API uptime and incident history
- [OpenAPI Spec](https://docs.pods.finance/openapi.yaml): Full OpenAPI 3.0 specification for code generation and tooling
- [LLM Privy Integration Guide](https://docs.pods.finance/llms-privy-integration.txt): Canonical one-shot prompt for Privy SDK widget integration
- [LLM Iframe + Wagmi/Viem Guide](https://docs.pods.finance/llms-iframe-wagmi-viem.txt): Canonical one-shot prompt for iframe wrapper with browser wallets
- [LLM Iframe + Privy Multi-chain Guide](https://docs.pods.finance/llms-iframe-privy-multichain.txt): Canonical one-shot prompt for iframe wrapper with Privy multi-chain