# 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 290+ protocols and 10+ networks
2. **Trading APIs**: Intent-based swap and zap execution for any-to-any token conversions, including cross-chain operations

## Quick Facts

- **290+ 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 /v2/tokens/transactions** - Transaction history for tokens (Pioneer+ plan)
- Last 24 hours of deposits, withdrawals, swaps
- Transaction hashes and timestamps
- USD value calculations

**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 token approvals
- Supports traditional ERC-20 approvals
- Gasless approvals via EIP-2612 permit
- Returns ready-to-execute approval transactions
- Checks current allowance status

## 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
- Expiry timestamps prevent stale quotes
- 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 290+ 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:0x4d9079bb4165aeb4084c526a32695dcfd2f77381&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: 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: 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

## Authentication

- **Data endpoints** require API key in Authorization header
- **Swap/zap endpoints** work without API key (optional for tracking)
- Get free API key at: https://build.portals.fi/dashboard
- Keep API keys secure, never expose in client-side code

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

- **Free**: Basic access, 100 RPM, includes token data and account balances
- **Pioneer**: 500 RPM, $99/month, same features as Free
- **Pioneer+**: Includes historical data, transaction history, token holders endpoint

## 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
- 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
- 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**: December 2025

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