# Portals API

> Build powerful DeFi applications with a single unified API

## Overview

Portals provides comprehensive DeFi infrastructure through two main offerings:

1. **Data APIs**: Real-time and historical token data, balances, prices, APYs, volume across 400+ protocols and 10+ networks
2. **Trading APIs**: Intent-based swap and zap execution for any-to-any token conversions, including cross-chain operations

## Documentation

- [Documentation overview](https://build.portals.fi/docs): Start here for workflow-oriented API docs.
- [API reference](https://build.portals.fi/docs/api-reference): Browse every documented endpoint by product area.
- [Quickstart](https://build.portals.fi/docs/quickstart): Make the first authenticated data request and execution quote.
- [Portals API skill](https://build.portals.fi/skills/portals-defi-api/SKILL.md): Agent-ready integration instructions and endpoint contracts.
- [Full LLM context](https://build.portals.fi/llms-full.txt): Expanded documentation context for automated readers.

## Quick Facts

- **400+ DeFi protocols** integrated (Yearn, Aave, Curve, Uniswap, Morpho, Balancer, Convex, Beefy, etc.)
- **9 networks** supported (Ethereum, Arbitrum, Base, Optimism, Polygon, BSC, Avalanche, Sonic, HyperEVM)
- **7 cross-chain enabled networks** for seamless asset movement (Ethereum, Arbitrum, Base, Optimism, Polygon, BSC, Avalanche)
- **Intent-based architecture** - specify outcomes, not implementation steps
- **No API key required** for swap/zap endpoints
- **100% fee retention** for partners (0-1% customizable fee range)
- **Atomic transactions** - complete or revert, no partial states

## Core Endpoints

### Data Endpoints (Require API Key)

**GET /v2/tokens** - Comprehensive token data with filtering, search, sorting
- Real-time prices, liquidity, APY, volume, reserves
- Filter by platform, network, liquidity range, APY range
- Search across all tokens and protocols
- Sort by liquidity, price, APY, volume
- Pagination support (up to 250 items per request)

**GET /v2/account** - Multichain account balances
- Aggregate balances across all supported networks
- Returns USD values and token metadata
- Supports both EOAs and smart contract addresses
- Filter by specific networks for optimized queries

**GET /v2/tokens/history** - Historical price, APY, TVL, volume data (Pioneer plan)
- OHLC candlestick data
- Multiple resolutions: 15m, 1h, 4h, 1d
- Time-series metrics for yield comparisons
- Pagination for large datasets

**GET /v3/tokens/transactions** - Cursor-paginated activity feed for tokens (Pioneer plan)
- Swaps, deposits, withdrawals, borrows, repays
- Cursor pagination via pageInfo.endCursor (not page numbers)
- Transaction hashes, block numbers, USD values
- Currently available for Platform Tokens only

**GET /v3/tokens/metrics** - Rolling-window volume metrics (Pioneer plan)
- Eight time windows: 15m, 30m, 1h, 2h, 4h, 8h, 1d, 2d
- Gross/net USD volume, swap buy/sell breakdown
- Deposit/withdrawal volume and event counts
- Percentage change vs prior matching window

**GET /v2/tokens/holders** - Token holder distribution (Pioneer plan, Beta)
- Paginated list of all token holders
- Balance, USD value, ownership percentage
- Sorted by balance descending

### Trading Endpoints (API Key Optional)

**GET /v2/portal** - Generate executable swap/zap transactions
- Any-to-any token swaps (including complex DeFi positions)
- Returns ready-to-execute transaction calldata
- Automatic slippage protection (max 2.5% auto-slippage)
- Gas-optimized routing across multiple DEXs
- Cross-chain support (single transaction on source chain)
- Fee/revenue sharing: 0-1% (default 0.3%)

**GET /v2/portal/estimate** - Simulate transactions without approvals
- Preview outcomes without gas costs
- No token balances or approvals required
- Works for both single-chain and cross-chain
- Returns accurate quotes including fees and slippage

**GET /v2/approval** - Check and generate single-chain token approvals
- Supports traditional ERC-20 approvals
- Gasless approvals via EIP-2612 permit
- Returns ready-to-execute approval transactions
- Checks current allowance status

**GET /v2/approval/cross-chain** - Cross-chain token approvals
- Same shape as /v2/approval but spends to the Squid router
- Required when inputToken.network !== outputToken.network
- Using /v2/approval for cross-chain swaps causes TRANSFER_FROM_FAILED revert

## Key Features

### Any-to-Any Swaps
- Swap between any two tokens, including complex DeFi positions
- Examples: ETH → Yearn vault, Curve pool → Morpho vault, USDC → Aave position
- Automatic DEX aggregation finds optimal pricing
- Single transaction execution

### Cross-Chain Operations
- Single transaction on source chain, everything else automated
- Automatic bridging via Axelar (1-10 minute completion)
- 7 networks with full cross-chain support
- Quotes do not expose a public expiry field; re-fetch before signing if the user waits
- Tracking via Axelar explorer: https://axelarscan.io/gmp/{txHash}

### Gasless Approvals
- EIP-2612 permit support for compatible tokens
- Bundle approval + swap in one transaction
- Reduces gas costs and improves UX
- Returns permit signature data for signing

### Simulation Engine
- Validates transactions before execution
- Checks balance, allowances, gas costs, slippage
- Accurate quotes based on on-chain simulation
- No approvals or balances required for /estimate endpoint

## Token Types

1. **Native Tokens**: Network gas tokens (ETH, POL, BNB)
   - Use address: `0x0000000000000000000000000000000000000000`
   - No approvals needed for swaps

2. **Basic Tokens**: Simple ERC-20s (USDC, WETH, USDT, LINK, UNI)
   - Standard token interface
   - Require approval for swaps

3. **Platform Tokens**: Composed tokens from DeFi protocols
   - LP tokens (Uniswap, Curve, Balancer)
   - Vault tokens (Yearn, Morpho, Beefy)
   - Lending positions (Aave, Compound)
   - Liquid staking derivatives (Lido, Ether.fi)

## Common Use Cases

1. **DeFi Aggregators**: Build swapping interfaces with best pricing across 400+ protocols
2. **Wallets**: Multi-chain balance tracking and any-to-any swaps
3. **Yield Optimizers**: Cross-protocol and cross-chain yield strategies
4. **Portfolio Managers**: Rebalancing tools across multiple chains
5. **Trading Bots**: Historical data analysis + real-time execution
6. **NFT Marketplaces**: Accept any token as payment
7. **Payment Processors**: Token conversion for checkout flows
8. **Analytics Platforms**: Track trading patterns and token movements

## Example: Simple Swap (ETH to USDC)

```bash
curl 'https://api.portals.fi/v2/portal?inputToken=ethereum:0x0000000000000000000000000000000000000000&inputAmount=100000000000000000&outputToken=ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&sender=0xYOUR_ADDRESS'
```

Returns transaction object with:
- `tx.data`: Encoded calldata ready for execution
- `tx.to`: Router contract address
- `tx.value`: ETH amount to send
- `context.outputAmount`: Expected USDC output
- `context.route`: Token swap path
- `context.steps`: Human-readable action breakdown

## Example: Cross-Chain Zap (Ethereum to Arbitrum)

```bash
curl 'https://api.portals.fi/v2/portal?inputToken=ethereum:0x0000000000000000000000000000000000000000&inputAmount=100000000000000000&outputToken=arbitrum:0xe50fa9b3c56ffb159cb0fca61f5c9d750e8128c8&sender=0xYOUR_ADDRESS'
```

Single transaction:
1. Exits position on Ethereum
2. Bridges via Axelar (automated)
3. Enters position on Arbitrum (automated)
4. Takes 1-10 minutes total

## Example: Get Token Prices & Metrics

```bash
curl 'https://api.portals.fi/v2/tokens?platforms=yearn-v3&networks=ethereum&sortBy=liquidity&sortDirection=desc&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

Returns array of tokens with price, APY, TVL, volume, reserves, and metadata.

## Example: Get Multichain Account Balances

```bash
curl 'https://api.portals.fi/v2/account?owner=0xYOUR_ADDRESS&networks=ethereum&networks=arbitrum' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

Returns all token balances across specified networks with USD values.

## Tools & Resources

- **Portals Explorer**: https://explorer.portals.fi - Visual DeFi dashboard to discover tokens, view charts, execute swaps
- **API Documentation**: https://build.portals.fi/docs - Complete API reference with code examples
- **Swagger UI**: https://api.portals.fi/docs - Interactive API testing
- **Dashboard**: https://build.portals.fi/dashboard - Get API keys, view usage statistics
- **OpenAPI Schema**: https://api.portals.fi/docs-json - For code generation tools
- **Agent Skill (SKILL.md)**: https://build.portals.fi/skills/portals-defi-api/SKILL.md - Anthropic Agent Skill bundle for Claude Code / Agent SDK. Examples lead with curl (works from any language); TypeScript snippets use axios; execution flow shows viem (Node) and web3.py (Python) side-by-side. Full TypeScript response shapes, six worked recipes, and paste-ready helpers (see https://build.portals.fi/docs/skill)
- **Examples cookbook**: https://build.portals.fi/docs/examples - 16 copy-paste recipes by use case

## Authentication

- **Data endpoints** require API key in `Authorization: Bearer <key>` header (Bearer prefix is mandatory)
- **Swap/zap endpoints** (`/v2/portal`, `/v2/portal/estimate`, `/v2/approval`, `/v2/approval/cross-chain`) work without API key — header is accepted but optional
- Get free API key at: https://build.portals.fi/dashboard
- Keep API keys secure, never expose in client-side code (proxy data calls through your backend)

## Rate Limits

- **Free tier**: 100 requests/minute for data endpoints
- **Pioneer tier**: 500 requests/minute for data endpoints ($99/month)
- **Swap/zap endpoints**: 100 requests/minute (all tiers)
- Rate limit headers included in every response
- Implement exponential backoff for 429 errors

## Pricing Plans

- **Basic (Free)**: 50K calls/month, 100 RPM, 1 API key, attribution required
- **Pioneer** ($50/month): 150K calls/month, 500 RPM, 5 API keys, commercial license, includes historical data, transactions, holders, and metrics endpoints
- **Enterprise**: Custom limits up to 3000 RPM, unlimited API keys, email/Telegram/Slack support — contact for pricing

## Response Format

All endpoints return JSON with consistent structure:
- Token identifier format: `{network}:{address}` (e.g., `ethereum:0x...`)
- Amounts in base units (wei for ETH, smallest unit for tokens)
- USD values included for prices and amounts
- Pagination metadata when applicable

## Important Links

- Main Site: https://portals.fi
- Documentation: https://build.portals.fi/docs
- FAQ: https://build.portals.fi/docs/faq (Answers to 45+ common questions)
- API Reference: https://api.portals.fi/docs
- Quickstart: https://build.portals.fi/docs/quickstart
- Examples cookbook: https://build.portals.fi/docs/examples
- AI Agent Skill: https://build.portals.fi/docs/skill
- Cross-Chain Guide: https://build.portals.fi/docs/cross-chain
- Token Prices & Metrics Guide: https://build.portals.fi/docs/getting-tokens
- Multichain Account Balances: https://build.portals.fi/docs/getting-balances
- Token Volume Metrics: https://build.portals.fi/docs/tokens-metrics
- Token Activity & Transactions: https://build.portals.fi/docs/token-transactions
- Token Holders: https://build.portals.fi/docs/token-holders
- Historical Token Data: https://build.portals.fi/docs/token-history
- Token Approvals: https://build.portals.fi/docs/token-approvals
- Simulate Transactions: https://build.portals.fi/docs/estimate
- Swaps & Zaps: https://build.portals.fi/docs/portal
- Troubleshooting: https://build.portals.fi/docs/troubleshooting
- Dashboard: https://build.portals.fi
- Explorer: https://explorer.portals.fi

## Support

- Telegram: https://t.me/PortalsFi_Official
- Discord: https://discord.gg/portals
- Twitter: https://twitter.com/portals_fi
- Feature Requests: https://portals.canny.io/feature-requests

## Technical Details

- Built on EVM-compatible networks
- Smart contract interactions abstracted via API
- Automatic gas estimation included
- Transaction simulation validates outcomes
- Supports Viem, Ethers.js, Web3.py for execution
- Compatible with MetaMask, WalletConnect, Coinbase Wallet

---

**Last updated**: April 2026

For the most comprehensive documentation, see: https://build.portals.fi/docs
For AI-optimized full documentation, see: /llms-full.txt