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

# MCP Tools Reference

> Complete reference for all 25 tools and 9 prompts exposed by the Pods MCP Server

The Pods MCP Server exposes 25 tools and 9 prompts. Tools are callable by the AI agent during a session. Prompts are pre-built conversation starters you can invoke by name from your AI host to begin a guided workflow.

***

## Shared Tools

Available regardless of integration path.

<AccordionGroup>
  <Accordion title="recommend_integration_path">
    Analyzes your developer stack and recommends whether to use API Direct or SDK Widgets.

    **Inputs:**

    | Field               | Type      | Description                                          |
    | ------------------- | --------- | ---------------------------------------------------- |
    | `frontendFramework` | string    | e.g. `next`, `react`, `remix`, `gatsby`              |
    | `walletProvider`    | string    | e.g. `privy`, `dynamic`, `wagmi`, `ethers`           |
    | `backendLanguage`   | string    | e.g. `typescript`, `javascript`, `python`, `go`      |
    | `features`          | string\[] | Features needed: `swap`, `yield`, `wallet-positions` |

    **Returns:** recommended path (API Direct or SDK Widgets) with rationale and suggested first steps.
  </Accordion>

  <Accordion title="get_health">
    Checks Pods API health status. Use this to verify connectivity before starting a session or before running diagnostics.

    **Inputs:** none

    **Returns:** health status and API version.
  </Accordion>

  <Accordion title="validate_api_key">
    Validates an API key and returns account information.

    **Inputs:**

    | Field    | Type   | Description             |
    | -------- | ------ | ----------------------- |
    | `apiKey` | string | The API key to validate |

    **Returns:** key validity, account name, plan tier, and rate limit details.
  </Accordion>

  <Accordion title="list_tokens">
    Lists all tokens supported by Pods with optional filtering by chain.

    **Inputs:**

    | Field     | Type                | Description                   |
    | --------- | ------------------- | ----------------------------- |
    | `chainId` | number *(optional)* | Filter tokens by EVM chain ID |

    **Returns:** array of token objects with address, symbol, decimals, and chainId.
  </Accordion>

  <Accordion title="get_error_explanation">
    Decodes a Pods error code with causes, HTTP status, retryability flag, and resolution steps.

    **Inputs:**

    | Field       | Type   | Description                                                      |
    | ----------- | ------ | ---------------------------------------------------------------- |
    | `errorCode` | string | Error code string (e.g. `QUOTE_EXPIRED`, `INSUFFICIENT_BALANCE`) |

    **Returns:** description, causes, whether it is retryable, and suggested fixes.
  </Accordion>
</AccordionGroup>

***

## API Direct — Swap

<AccordionGroup>
  <Accordion title="get_swap_quote">
    Request a quote for a same-chain or cross-chain token swap.

    **Inputs:**

    | Field         | Type   | Description                        |
    | ------------- | ------ | ---------------------------------- |
    | `fromChain`   | number | Source chain ID                    |
    | `toChain`     | number | Destination chain ID               |
    | `fromToken`   | string | Token symbol or address            |
    | `toToken`     | string | Token symbol or address            |
    | `fromAmount`  | string | Amount in smallest unit (e.g. wei) |
    | `fromAddress` | string | Sender wallet address              |

    **Returns:** quote object with `transactionRequest`, expected output amount, `feeBreakdown`, and expiry timestamp.

    <Warning>
      Quotes expire after 5 minutes. Call `execute_swap_bytecode` promptly after receiving a quote.
    </Warning>
  </Accordion>

  <Accordion title="execute_swap_bytecode">
    Generate ready-to-sign transaction bytecode from a confirmed swap quote.

    **Inputs:**

    | Field         | Type   | Description                           |
    | ------------- | ------ | ------------------------------------- |
    | `quoteId`     | string | Quote ID returned by `get_swap_quote` |
    | `fromAddress` | string | Sender wallet address                 |

    **Returns:** ordered array of transaction objects (`to`, `data`, `value`, `chainId`) to sign and broadcast.

    <Info>
      Sign and broadcast each transaction in the returned order. Skipping any transaction will cause the swap to fail.
    </Info>
  </Accordion>

  <Accordion title="get_swap_status">
    Poll the status of a submitted swap transaction.

    **Inputs:**

    | Field       | Type                | Description                            |
    | ----------- | ------------------- | -------------------------------------- |
    | `txHash`    | string              | Transaction hash from the source chain |
    | `fromChain` | number *(optional)* | Source chain ID — speeds up lookup     |
    | `toChain`   | number *(optional)* | Destination chain ID                   |

    **Returns:** `status` (`PENDING`, `DONE`, `FAILED`) and `substatus` (`COMPLETED`, `PARTIAL`, `REFUNDED`).

    Poll every 10–30 seconds while status is `PENDING`.
  </Accordion>
</AccordionGroup>

***

## API Direct — Yield

<AccordionGroup>
  <Accordion title="list_strategies">
    List all available DeFi yield strategies.

    **Inputs:**

    | Field     | Type                | Description                                         |
    | --------- | ------------------- | --------------------------------------------------- |
    | `network` | string *(optional)* | Filter by network name (e.g. `polygon`, `arbitrum`) |
    | `asset`   | string *(optional)* | Filter by asset symbol (e.g. `USDC`)                |

    **Returns:** paginated array of strategy objects with id, protocol, APY, fee, and available actions.
  </Accordion>

  <Accordion title="get_strategy">
    Retrieve a single strategy with full details.

    **Inputs:**

    | Field        | Type   | Description                                    |
    | ------------ | ------ | ---------------------------------------------- |
    | `strategyId` | string | Strategy identifier (e.g. `Aave-USDC-polygon`) |

    **Returns:** protocol details, asset, APY, supported actions, fees, and current state.
  </Accordion>

  <Accordion title="get_strategy_quote">
    Calculate estimated output and fees for a deposit or withdrawal before generating bytecode.

    **Inputs:**

    | Field        | Type   | Description                     |
    | ------------ | ------ | ------------------------------- |
    | `strategyId` | string | Strategy identifier             |
    | `amount`     | string | Amount in asset's smallest unit |
    | `action`     | string | `lend` or `withdraw`            |
    | `wallet`     | string | Wallet address                  |

    **Returns:** estimated output, fee charged, and slippage details.
  </Accordion>

  <Accordion title="get_deposit_bytecode">
    Generate transaction bytecode for depositing into a yield strategy.

    **Inputs:**

    | Field        | Type   | Description                             |
    | ------------ | ------ | --------------------------------------- |
    | `strategyId` | string | Strategy identifier                     |
    | `amount`     | string | Deposit amount in asset's smallest unit |
    | `wallet`     | string | Wallet address                          |
    | `action`     | string | Typically `lend`                        |

    **Returns:** ordered array of transactions to sign and broadcast. May include a token approval transaction before the deposit.

    <Info>
      Execute all transactions in order. Each transaction depends on the one before it.
    </Info>
  </Accordion>

  <Accordion title="get_withdraw_bytecode">
    Generate transaction bytecode for withdrawing from a yield strategy.

    **Inputs:**

    | Field        | Type   | Description                                |
    | ------------ | ------ | ------------------------------------------ |
    | `strategyId` | string | Strategy identifier                        |
    | `amount`     | string | Withdrawal amount in asset's smallest unit |
    | `wallet`     | string | Wallet address                             |
    | `action`     | string | Typically `withdraw`                       |

    **Returns:** ordered array of transactions to sign and broadcast.
  </Accordion>

  <Accordion title="get_wallet_positions">
    Retrieve all open yield positions for a wallet address.

    **Inputs:**

    | Field    | Type   | Description                               |
    | -------- | ------ | ----------------------------------------- |
    | `wallet` | string | Wallet address (checksummed or lowercase) |

    **Returns:** array of positions with current value, principal, profit, and APY per strategy, plus a total balance summary in USD.
  </Accordion>

  <Accordion title="get_wallet_history">
    Retrieve transaction history for a wallet in a specific strategy.

    **Inputs:**

    | Field        | Type   | Description         |
    | ------------ | ------ | ------------------- |
    | `wallet`     | string | Wallet address      |
    | `strategyId` | string | Strategy identifier |

    **Returns:** paginated transaction history with timestamps, amounts, and status.
  </Accordion>

  <Accordion title="get_yield_by_identifier">
    Find the highest-APY strategy matching an asset name or yield category.

    **Inputs:**

    | Field        | Type   | Description                                              |
    | ------------ | ------ | -------------------------------------------------------- |
    | `identifier` | string | Asset name (e.g. `USDC`) or category (e.g. `stablecoin`) |

    **Returns:** top-performing strategy matching the identifier, with full strategy details.
  </Accordion>
</AccordionGroup>

***

## API Direct — Code Generation

<AccordionGroup>
  <Accordion title="get_code_example">
    Generate a complete, runnable code example for a given feature and programming language.

    **Inputs:**

    | Field      | Type   | Description                                           |
    | ---------- | ------ | ----------------------------------------------------- |
    | `feature`  | string | `swap`, `yield`, or `wallet-positions`                |
    | `language` | string | `typescript`, `javascript`, `python`, `go`, or `curl` |

    **Returns:** complete code snippet with comments, ready to copy into a project. Includes environment setup, API call, and response handling.
  </Accordion>
</AccordionGroup>

***

## SDK Widgets

<AccordionGroup>
  <Accordion title="scaffold_project">
    Generate all files needed to integrate Pods SDK widgets into a frontend project.

    **Inputs:**

    | Field            | Type      | Description                           |
    | ---------------- | --------- | ------------------------------------- |
    | `framework`      | string    | `next`, `react`, `remix`, or `gatsby` |
    | `features`       | string\[] | `swap`, `yield`, or both              |
    | `walletProvider` | string    | Wallet connection library in use      |

    **Returns:** complete file tree — components, providers, and environment templates — ready to copy into your project.
  </Accordion>

  <Accordion title="validate_provider_config">
    Validate a `DeframeProvider` configuration object before using it in production.

    **Inputs:**

    | Field    | Type   | Description                            |
    | -------- | ------ | -------------------------------------- |
    | `config` | object | The provider config object to validate |

    **Returns:** validation result with any errors or warnings and suggested fixes for each issue.
  </Accordion>

  <Accordion title="check_sdk_compatibility">
    Check compatibility between `pods-sdk`, React, and your wallet provider before installing or upgrading.

    **Inputs:**

    | Field            | Type   | Description                     |
    | ---------------- | ------ | ------------------------------- |
    | `sdkVersion`     | string | Installed version of `pods-sdk` |
    | `reactVersion`   | string | Installed version of React      |
    | `walletProvider` | string | Wallet library name and version |

    **Returns:** compatibility matrix, known issues, and recommended version combinations.
  </Accordion>

  <Accordion title="setup_env">
    Write Pods environment variables to a `.env` or `.env.local` file.

    **Inputs:**

    | Field    | Type                | Description                             |
    | -------- | ------------------- | --------------------------------------- |
    | `apiKey` | string              | Your Pods API key                       |
    | `file`   | string *(optional)* | Target file path. Default: `.env.local` |

    **Returns:** confirmation of which variables were written and the target file path.

    <Warning>
      Ensure `.env` and `.env.local` are listed in your `.gitignore` before running this tool.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Skills

Higher-order workflows that chain multiple atomic tools into a single orchestrated call. Every workflow skill supports `dryRun: true` (preview without generating bytecode) and partial-success returns (preserves already-generated bytecode when a later step fails). Validation failures carry skill-specific error codes like `MISSING_DEPOSIT_TARGET`, `ZERO_POSITION_BALANCE`, and `SOURCE_POSITION_NOT_FOUND`, consumable via `get_error_explanation`.

<Info>
  For decision tables, per-skill walkthroughs of `dryRun` and partial-success, and the full skill-level error code reference, see the [Skills Guide](/ai-tools/mcp-skills). This reference page keeps the accordions short.
</Info>

Each skill also has a markdown documentation resource at `pods://skills/<name>` accessible via `ReadMcpResource`.

<AccordionGroup>
  <Accordion title="swap_and_deposit">
    Swap token A into token B on the destination chain and deposit the proceeds into a yield strategy in a single orchestrated call. Chains `get_swap_quote` → `execute_swap_bytecode` → `get_strategy_quote` → `get_deposit_bytecode` internally.

    **Inputs:**

    | Field               | Type                 | Description                                                                         |
    | ------------------- | -------------------- | ----------------------------------------------------------------------------------- |
    | `fromChain`         | string               | Source chain name (e.g. `ethereum`, `polygon`, `base`)                              |
    | `toChain`           | string               | Destination chain name where the yield strategy lives                               |
    | `fromToken`         | string               | Source token contract address                                                       |
    | `toToken`           | string               | Destination token — gets deposited into the strategy                                |
    | `amountIn`          | string               | Amount in smallest unit of `fromToken`                                              |
    | `wallet`            | string               | Wallet that signs both txs and receives the swap output                             |
    | `depositStrategyId` | string *(one of)*    | Exact strategy ID. Takes precedence over `depositIdentifier`                        |
    | `depositIdentifier` | string *(one of)*    | Asset symbol/category (e.g. `usdc`, `eth`) — resolved via `get_yield_by_identifier` |
    | `dryRun`            | boolean *(optional)* | When `true`, skip bytecode generation and return only quotes. Default `false`       |

    **Returns:** structured payload with `swap.bytecode`, `deposit.bytecode`, `executionOrder`, `warnings`, and `nextSteps`. On partial failure, returns `structuredContent.status === "partial"` with the swap bytecode preserved.

    <Warning>
      The swap bytecode MUST be broadcast and confirmed before the deposit bytecode — the deposit spends the swap output. The deposit amount is sized from the swap quote's expected output; slippage can cause on-chain revert.
    </Warning>
  </Accordion>

  <Accordion title="find_best_yield_for_asset">
    Given an asset, return the highest-APY strategy with a deposit quote, ready-to-sign bytecode, and the top 3 alternatives. Chains `get_yield_by_identifier` → `list_strategies` → `get_strategy_quote` → `get_deposit_bytecode`.

    **Inputs:**

    | Field     | Type                 | Description                                                                          |
    | --------- | -------------------- | ------------------------------------------------------------------------------------ |
    | `asset`   | string               | Symbol, name, or category accepted by `get_yield_by_identifier` (e.g. `usdc`, `eth`) |
    | `wallet`  | string               | Wallet that will deposit                                                             |
    | `amount`  | string               | Amount in smallest unit of the asset                                                 |
    | `network` | string *(optional)*  | Network filter for alternatives search (e.g. `polygon`)                              |
    | `dryRun`  | boolean *(optional)* | When `true`, return best + alternatives + quote without bytecode. Default `false`    |

    **Returns:** `best` strategy, up to 3 `alternatives`, deposit `quote`, deposit `bytecode`, plus warnings and next-step guidance.
  </Accordion>

  <Accordion title="rebalance_position">
    Move capital from one yield strategy to another — typically for better APY. Returns withdraw + deposit bytecode in execution order.

    **Inputs:**

    | Field            | Type                 | Description                                                                        |
    | ---------------- | -------------------- | ---------------------------------------------------------------------------------- |
    | `wallet`         | string               | Wallet that holds the source position                                              |
    | `fromStrategyId` | string               | Current strategy to exit                                                           |
    | `toStrategyId`   | string *(optional)*  | Destination. If omitted, auto-resolved to the best-APY strategy for the same asset |
    | `amount`         | string *(optional)*  | Rebalance amount in smallest unit. Defaults to the full current position balance   |
    | `dryRun`         | boolean *(optional)* | When `true`, return APY delta + amount without bytecode. Default `false`           |

    **Returns:** `from` and `to` strategy details, `apyDelta`, `withdraw.bytecode`, `deposit.bytecode`, `executionOrder`, and warnings. On partial failure, withdraw bytecode is preserved.

    <Warning>
      The withdraw bytecode MUST be broadcast and confirmed before the deposit — the deposit spends withdrawn funds. If the auto-resolver returns worse APY, a high-priority warning is prepended but bytecode is still generated so the caller can confirm intent.
    </Warning>
  </Accordion>

  <Accordion title="diagnose_integration">
    Pre-flight integration health check — runs API key validation, API health, and reachability probes on strategies and tokens endpoints. Run this before shipping to production.

    **Inputs:**

    | Field    | Type                | Description                                                             |
    | -------- | ------------------- | ----------------------------------------------------------------------- |
    | `wallet` | string *(optional)* | If provided, also probes `get_wallet_positions` to verify that endpoint |

    **Returns:** `overall` (`pass` or `fail`), per-check breakdown with status, timing, and resolution hints. A failed `api_key` check cascades — every subsequent check will fail until the key is fixed. The `wallet_positions` check shows `skipped` when no wallet is passed and does not count against overall status.
  </Accordion>
</AccordionGroup>

***

## Prompts

Prompts are pre-built conversation starters. Invoke them by name from your AI host to begin a guided workflow.

<AccordionGroup>
  <Accordion title="choose_integration_path">
    Walks through a brief stack analysis and recommends API Direct or SDK Widgets for your project.

    **Inputs:** `feature`, `frontendFramework`, `walletProvider`, `backendLanguage`

    Use this at the start of a new integration to get a tailored recommendation before writing any code.
  </Accordion>

  <Accordion title="troubleshoot">
    Diagnoses errors given an error code, transaction state, and description. Returns probable causes and resolution steps.

    **Inputs:** `errorCode`, `txState`, `description`

    Use this when a transaction is failing or an API call returns an unexpected error.
  </Accordion>

  <Accordion title="api_quickstart">
    Step-by-step guided session from first API call to a confirmed on-chain transaction, tailored to a specific feature and language.

    **Inputs:** `feature`, `language`

    Use this to get from zero to working code as fast as possible.
  </Accordion>

  <Accordion title="api_integration_wizard">
    Full integration session covering the complete flow: quote → bytecode → signing → status tracking. Walks through each step interactively.

    **Inputs:** none — the wizard collects everything it needs during the session.

    Use this when building an end-to-end swap or yield integration for the first time.
  </Accordion>

  <Accordion title="sdk_quickstart">
    Fast-path SDK session: scaffold a project → write environment variables → validate the provider config.

    **Inputs:** none — the wizard collects framework and wallet provider during the session.

    Use this when you want working widget integration in the fewest possible steps.
  </Accordion>

  <Accordion title="sdk_integration_wizard">
    Complete SDK setup session: compatibility check → project scaffolding → provider config validation.

    **Inputs:** none — the wizard collects all required details interactively.

    Use this for a thorough SDK setup with checks at each stage before proceeding.
  </Accordion>

  <Accordion title="sdk_migration_guide">
    Generates a migration guide for moving between `pods-sdk` versions, including all breaking changes and required code updates.

    **Inputs:** `fromVersion`, `toVersion`

    Use this before upgrading the SDK in a production project.
  </Accordion>

  <Accordion title="portfolio_briefing">
    Skills prompt: guides the agent through producing a conversational briefing of a wallet's yield portfolio — positions, recent activity, underperformers, and recommended rebalances.

    **Inputs:** `wallet` (required), `includeHistoryDays` *(optional)*

    The prompt instructs the agent to call `get_wallet_positions`, `get_wallet_history`, and `get_yield_by_identifier`, identify underperformers (\~0.5pp APY threshold), and suggest actions using `rebalance_position` or `find_best_yield_for_asset` where relevant.
  </Accordion>

  <Accordion title="integration_review">
    Skills prompt: audits the workspace's Pods integration code against a checklist of common pitfalls — API key handling, quote lifecycle, bytecode signing formats, action names, webhook signature verification. Produces a file:line-level report with concrete fixes.

    **Inputs:** `workspacePath` *(optional)*, `feature` *(optional: `swap`, `yield`, `webhook`, `all`)*

    Checklist includes: quote TTL (5 min), `rawQuote` forwarding to `execute_swap_bytecode`, `transactionData` vs `transactions` field name, EIP-1193 value hex encoding, `action=lend` (not `deposit`), `wallet` param (not `fromAddress`), and webhook idempotency.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup Guide" icon="gear" href="/ai-tools/mcp-setup">
    Install the MCP server in Claude Desktop, Cursor, or Windsurf
  </Card>

  <Card title="Quickstart" icon="rocket" href="/getting-started/quickstart">
    Make your first API call in 5 minutes without the MCP server
  </Card>
</CardGroup>