# 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, Monad, Robinhood, 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) and DeFi protocols (Aave, Morpho, Lido, Compound) to provide optimal rates and routes for swaps and yield opportunities.

**Key Constraints**: Most requests require an API key via `x-api-key` header. `GET /health` is public. Customer dashboard endpoints use a Bearer JWT. Quotes expire after 5 minutes. Production base URL: `https://api.pods.finance`.

## 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
- [Executing Bytecode](https://docs.pods.finance/getting-started/executing-bytecode): Atomic batching rules and `output` format (`bytecode` / `userOperation` / `fireblocks` / `instructions`) by wallet stack
- [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
- [Shared EIP-7702 helper](https://docs.pods.finance/examples/javascript/eip7702-batch.js): `executeLegsViaEip7702()` used by strategy/swap example scripts

## API Reference

- [API Introduction](https://docs.pods.finance/api-reference/introduction): Overview of the Pods API with base URL, authentication, and quick links
- [Health — API health check](https://docs.pods.finance/api-reference/health/api-health-check): Check API health status (public, no auth required)
- [Swap v2 — Get swap quote](https://docs.pods.finance/api-reference/swap-v2/get-swap-quote): Request a quote for same-chain, cross-chain, or fiat off-ramp/on-ramp token swaps. Optionally include `originAddress` + `destinationAddress` (or `pixKey` for fiat destinations) to receive inline bytecode without a separate call to the bytecode endpoint. Quotes include a `feeBreakdown` field with a `charges` array itemizing platform fees and bridge/slippage impact.
- [Swap v2 — Generate transaction bytecode](https://docs.pods.finance/api-reference/swap-v2/generate-transaction-bytecode): Generate ready-to-sign transaction data from a confirmed quote
- [Swap v2 — Get swap status](https://docs.pods.finance/api-reference/swap-v2/get-swap-status): Poll swap transaction status through its lifecycle
- [Swap v2 — Update swap status with a transaction hash](https://docs.pods.finance/api-reference/swap-v2/update-swap-status-with-a-transaction-hash): Report a mined transaction hash for a quote to trigger immediate processing
- [Swap v2 — Fulfill a swap quote by transaction hash](https://docs.pods.finance/api-reference/swap-v2/fulfill-a-swap-quote-by-transaction-hash): Fulfill a quote by supplying the mined transaction hash and chain
- [Tracking — List tracked operations](https://docs.pods.finance/api-reference/tracking/list-tracked-operations): List tracked swap, transfer, and strategy operations
- [Tracking — Get tracked operation](https://docs.pods.finance/api-reference/tracking/get-tracked-operation): Retrieve execution status details by ID
- [Strategies — List strategies](https://docs.pods.finance/api-reference/strategies/list-strategies): List all available DeFi yield strategies
- [Strategies — Get strategy details](https://docs.pods.finance/api-reference/strategies/get-strategy-details): Retrieve a single strategy with historic data and APY metrics
- [Strategies — Get pending strategy status](https://docs.pods.finance/api-reference/strategies/get-pending-strategy-status): Retrieve pending action steps and legs for a strategy
- [Strategies — Get pending strategy status (v2)](https://docs.pods.finance/api-reference/strategies/get-pending-strategy-status-v2): Retrieve pending strategy actions through the canonical v2 route
- [Strategies — Generate strategy transaction bytecode](https://docs.pods.finance/api-reference/strategies/generate-strategy-transaction-bytecode): Generate bytecode for depositing into or withdrawing from a yield strategy
- [Strategies — List strategies (v2)](https://docs.pods.finance/api-reference/strategies/list-strategies-v2): List strategies through the canonical v2 route
- [Strategies — Get strategy details (v2)](https://docs.pods.finance/api-reference/strategies/get-strategy-details-v2): Retrieve enriched strategy details, rate history, and optional wallet data
- [Strategies — Get wallet strategy details (v2)](https://docs.pods.finance/api-reference/strategies/get-wallet-strategy-details-v2): Retrieve enriched strategy details scoped to a wallet in the path
- [Strategies — Generate strategy transaction bytecode (v2)](https://docs.pods.finance/api-reference/strategies/generate-strategy-transaction-bytecode-v2): Generate strategy bytecode through the canonical v2 route
- [Strategies — Get strategy rate history](https://docs.pods.finance/api-reference/strategies/get-strategy-rate-history): Retrieve paginated daily strategy rate history
- [Strategies — Get strategy analytics](https://docs.pods.finance/api-reference/strategies/get-strategy-analytics): Retrieve paginated historical analytics data points for strategies
- [Strategies — Get strategy share-price history](https://docs.pods.finance/api-reference/strategies/get-strategy-share-price-history): Retrieve paginated share-price series for a strategy at configurable range and resolution
- [Strategies — Get wallet PnL history for a strategy](https://docs.pods.finance/api-reference/strategies/get-wallet-pnl-history-for-a-strategy): Returns a daily unrealized-PnL timeline for a wallet supplied as a query parameter
- [Strategies — Get wallet PnL history for a strategy (wallet in path)](https://docs.pods.finance/api-reference/strategies/get-wallet-pnl-history-for-a-strategy-wallet-in-path): Returns the same PnL timeline with the wallet supplied in the path
- [Ondo — Get market status](https://docs.pods.finance/api-reference/ondo/get-ondostocksmarket-status): Ondo GM market-wide open/close status with optional per-symbol tradability and pause details
- [Tokens — List tokens](https://docs.pods.finance/api-reference/tokens/list-tokens): Retrieve the paginated token catalog with filtering and optional token groups
- [Transfer — Generate transfer transaction bytecode](https://docs.pods.finance/api-reference/transfer/generate-transfer-transaction-bytecode): Generate bytecode for a token transfer
- [Wallets — Get wallet positions](https://docs.pods.finance/api-reference/wallets/get-wallet-positions): Retrieve open yield positions for a wallet address
- [Wallets — Get wallet transaction history](https://docs.pods.finance/api-reference/wallets/get-wallet-transaction-history): Retrieve transaction history for a wallet in a specific strategy
- [Wallets — Get wallet overview (v2)](https://docs.pods.finance/api-reference/wallets/get-wallet-overview-v2): Retrieve token balances, earn positions, and transaction history for a wallet
- [Smart Account — Create or retrieve smart account](https://docs.pods.finance/api-reference/smart-account/create-or-retrieve-smart-account): Create or retrieve a generic ERC-4337 Gnosis Safe smart account for a given owner address and chain
- [KYC — Import Sumsub reusable KYC share token](https://docs.pods.finance/api-reference/kyc/import-sumsub-reusable-kyc-share-token): Submit a Sumsub reusable KYC share token with the applicant's tax id — a CPF, or a taxId plus its ISO 3166-1 alpha-3 taxIdCountry when the applicant was verified with a document that carries no CPF, such as a passport. Both may be sent together, since a foreign national resident in Brazil holds each. Pods stores only salted hashes and the last four digits, reuses an approved Avenia identity matching the same tax id, and returns 409 when it conflicts with the existing Sumsub profile. An applicant with no CPF is approved without the BRL rail and unlocks USD through POST /api/v1/kyc/currency-unlock.
- [KYC — Create BigDataCorp KYC iframe session](https://docs.pods.finance/api-reference/kyc/create-bigdatacorp-kyc-iframe-session): Create or reuse a BigDataCorp capture session and return its iframe URL
- [KYC — Submit completed BigDataCorp KYC to Avenia](https://docs.pods.finance/api-reference/kyc/submit-completed-bigdatacorp-kyc-to-avenia): Submit a completed BigDataCorp capture for Avenia verification
- [KYC — Get KYC status](https://docs.pods.finance/api-reference/kyc/get-kyc-status): Retrieve the current normalized KYC profile status

## 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

## SDK Widgets

Current verified widget stack: `pods-sdk@0.2.87`, `@deframe-sdk/components@0.1.91`, `@reduxjs/toolkit`, `react-redux`, and `redux`.

Host apps should import `DeframeProvider`, `EarnWidget`, and `SwapWidget` from `pods-sdk`; import `PodsSwapFormView` and `@deframe-sdk/components/styles.css` from `@deframe-sdk/components`; and register `config.components.SwapFormView = PodsSwapFormView` in the shared `DeframeProvider` config so Swap renders the Pods Wallet-style form view.

Use runtime env names `NEXT_PUBLIC_PODS_API_URL`, `NEXT_PUBLIC_PODS_API_KEY`, and `NEXT_PUBLIC_PODS_WEBSOCKET_URL`. In `pods-sdk@0.2.87`, map those values into the current `DeframeProvider` API config fields. The host app still owns wallet authentication, signing, transaction broadcast, and `processBytecode` status emissions.

For Privy hosts, keep `supportedChains` in sync with every EVM chain that Pods bytecode can target, and keep Polygon as the default chain unless the host product intentionally defaults elsewhere. Privy throws when `sendTransaction`, `switchChain`, or `getClientForChain({ id })` is called for an unsupported chain.

### 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, Ondo Global Markets (tokenized stocks on BSC), Ondo USDY (Arbitrum), Theo thBill (Arbitrum), and other protocols across multiple networks. Some strategies use a queued investment flow (`request-lend` / `request-withdraw`) rather than the immediate `lend` / `withdraw` actions — always check `availableActions` on the strategy. Ondo cross-chain flows require atomic bytecode execution — see [Ondo Global Markets](https://docs.pods.finance/guides/ondoglobal-markets) and [Executing Bytecode](https://docs.pods.finance/getting-started/executing-bytecode). **Ondo funding amounts** use the funding token's decimals (BSC USDC = 18, not 6). Pass `includeMetadata=true` to include Ondo stock metadata fields in token objects (excluded by default for lighter responses). Ondo strategies expose `metadata.maxRequestAmountUsd` and `metadata.minRequestLendUsd` — amounts above `maxRequestAmountUsd` return `REQUEST_LEND_AMOUNT_TOO_HIGH` or `REQUEST_WITHDRAW_AMOUNT_TOO_HIGH` (422). **`GET /ondo/stocks/market-status`** is in the OpenAPI reference.

**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. **Critical:** `bytecode[]` (and swap `transactionData[]`) is an atomic bundle — execute all same-chain legs in ONE transaction (EIP-7702 `executeBatch`, ERC-4337 userOp batch, or Fireblocks). Never loop `sendTransaction` per leg. Choose `output` by wallet stack: EOA → `bytecode` + EIP-7702; smart account → `userOperation`; Fireblocks → `fireblocks` + `accountId`; Solana wallet → `bytecode` (default) or `instructions` (Solana-origin only). See [Executing Bytecode](https://docs.pods.finance/getting-started/executing-bytecode). When a sentinel/zero wallet address is passed, the response returns `previewOnly: true` with quote/fee data only — no `id` or `bytecode` are generated.

**Quote System**: Quotes expire after 5 minutes. Each quote includes a `quoteId`, expected amounts, provider information, a `deadline` Unix timestamp in seconds, and a `deadlineDate` ISO 8601 string. Use `quoteId` with `/v2/swap/status/{id}`. When both `originAddress` and `destinationAddress` (or `pixKey` for fiat destinations) 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. Crypto BRLA↔BRS inventory rails (no fiat/Avenia leg) are supported on both `polygon` and `base`. For PIX/fiat off-ramp routes, pass `thirdParty=true` on both the quote and bytecode requests when the payment is to a third party; a mismatch between the two returns `PIX_THIRD_PARTY_QUOTE_MISMATCH` (400). **Pix ticket expiration**: Avenia BRLA Pix tickets (both on-ramp and off-ramp) must be paid within **10 minutes** of creation. Unpaid tickets are not automatically flipped to EXPIRED by Avenia — Pods monitors them and transitions the associated action to `EXPIRED` status after the 10-minute window, also expiring the linked quote. In-flight tickets whose payment is processing (`DEPOSIT-PROCESSING`, `DELIVERY-PROCESSING`) are not expired by this timer.

**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 `ACTION_UPDATE` notifications for confirmed Actions — including cross-chain swaps, same-chain swaps, strategy deposits, and withdrawals. A per-request `webhookURL` parameter is available on `GET /v2/swap/quote`, `POST /v2/swap/bytecode`, and `GET /strategies/{strategyId}/bytecode` to override the customer-level default webhook URL for that specific quote or action.

## 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