Portals Foresight API

Simulate EVM transactions and get back structured token changes, gas costs, and metadata. For supported flows, no wallet connection, pre-funded balance, or manual approval transaction is required.

Quick Start

Preview wrapping 0.01 ETH into WETH on Ethereum. This complete example needs no funded wallet and sends nothing on-chain.

1. Get an API key

Sign up at foresight.portals.fi to get your API key. Free tier includes 1,000 simulations per month.

2. Make your first request

curl -X POST "https://foresight.portals.fi/v1/simulate?network=ethereum" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "inputToken": "0x0000000000000000000000000000000000000000",
    "inputAmount": "10000000000000000",
    "tx": {
      "from": "0x1111111111111111111111111111111111111111",
      "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "data": "0xd0e30db0",
      "value": "10000000000000000"
    }
  }'

const response = await fetch("https://foresight.portals.fi/v1/simulate?network=ethereum", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    inputToken: "0x0000000000000000000000000000000000000000",
    inputAmount: "10000000000000000",
    tx: {
      from: "0x1111111111111111111111111111111111111111",
      to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      data: "0xd0e30db0",
      value: "10000000000000000",
    },
  }),
});

const result = await response.json();
console.log(result.assetChanges);

import requests

response = requests.post(
    "https://foresight.portals.fi/v1/simulate",
    params={"network": "ethereum"},
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY",
    },
    json={
        "inputToken": "0x0000000000000000000000000000000000000000",
        "inputAmount": "10000000000000000",
        "tx": {
            "from": "0x1111111111111111111111111111111111111111",
            "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "data": "0xd0e30db0",
            "value": "10000000000000000",
        },
    },
)

result = response.json()
print(result["assetChanges"])

3. Read the response

Check success, then confirm 0.01 ETH was sent and 0.01 WETH received. Selected response fields are shown below; gas usage and cost vary with chain state.

{
  "success": true,
  "sender": "0x1111111111111111111111111111111111111111",
  "assetChanges": [
    {
      "token": "0x0000000000000000000000000000000000000000",
      "amount": "10000000000000000",
      "direction": "sent",
      "standard": "native"
    },
    {
      "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "amount": "10000000000000000",
      "direction": "received",
      "standard": "erc20"
    }
  ],
  "gasUsed": "27938",
  "gasCost": "8233129346184",
  "tokenMetadata": {
    "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": {
      "name": "Wrapped Ether",
      "symbol": "WETH",
      "decimals": 18
    }
  },
  "errors": []
}

Authentication

Authenticate requests by passing your API key in the X-Api-Key header.

X-Api-Key: your_api_key_here

Health checks, network discovery, and cached trace retrieval do not require authentication.

An invalid API key returns 401. Missing keys on x402-enabled endpoints (/v1/simulate, /v1/simulate/batch) return 402 with a payment-required header instead — see x402 Payments.

{
  "success": false,
  "error": "Invalid or missing API key"
}

Simulate Transaction

Simulates an EVM transaction against live chain state and returns structured results including net asset changes, gas costs, decoded events, and token metadata when available.

Query Parameters

Request Body

Response Format

A completed simulation returns HTTP 200 even when the transaction reverts. Check success for the execution outcome. Invalid requests and service failures use HTTP error codes.

Response Fields

AssetChange

TokenEvent

TokenMetadata

TokenAmount

Used by inputTokens and outputTokens to represent the tokens sent or received by the user.

BypassInfo

Describes signature checks skipped to preview a supported call before signing. A successful simulation with these entries is not proof that the signatures are valid. Review each entry before treating the transaction as ready to submit.

Batch Simulation

Simulate multiple transactions in a single call with shared state. All steps execute sequentially in one simulated block — the state changes from each step carry forward to the next. Ideal for multi-step DeFi flows like leverage loops (supply → borrow → swap → re-supply).

Query Parameters

Batch Request Body

The request body contains a sender, optional recipient and trackedAccount, and an array of steps (1–50).

Batch Response

The response includes a result for each step and a combined aggregate. Its blockNumber (decimal string) and blockHash identify the chain state used before simulated funding, approvals, and execution. Both fields are returned with or without trackedAccount. Foresight checks the block hash again after execution and rejects results if that block changed or cannot be verified. This does not guarantee finality.

StepResult

Custom Event Decoding Pro

Decode protocol-specific events (Uniswap Swap, Curve AddLiquidity, Aave LiquidationCall, etc.) from simulation logs by passing Solidity event ABI strings in the customEvents request field. API-key requests require Pro, Business, or Enterprise and return HTTP 403 on lower plans; x402 requests are allowed.

Request

Add a customEvents array to your request body. Up to the first 10 entries are attempted; invalid ABI strings are skipped. Each entry is a Solidity event signature string:

{
  "inputToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "inputAmount": "10000000000",
  "customEvents": [
    "event Swap(address indexed sender, uint256 amount0In, uint256 amount1In, uint256 amount0Out, uint256 amount1Out, address indexed to)"
  ],
  "tx": { "from": "0x...", "to": "0x...", "data": "0x...", "value": "0" }
}

Response

Matching logs are returned in the customEvents response field:

{
  "customEvents": [
    {
      "name": "Swap",
      "signature": "event Swap(address indexed sender, uint256 amount0In, uint256 amount1In, uint256 amount0Out, uint256 amount1Out, address indexed to)",
      "address": "0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc",
      "logIndex": 4,
      "args": {
        "sender": "0x...",
        "amount0In": "0",
        "amount1In": "10000000000",
        "amount0Out": "2918274610283746",
        "amount1Out": "0",
        "to": "0x..."
      }
    }
  ]
}

DecodedCustomEvent

Trace Transaction

Simulate a transaction with a full execution trace — decoded call tree, best-effort storage state changes, token transfers, decoded events, gas profiling, and ABI-decoded function inputs/outputs. Returns a shareable traceId for later retrieval. Results are cached for 7 days.

Query Parameters

Request Body

Request Example

curl -X POST "https://foresight.portals.fi/v1/simulate/trace?network=ethereum" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
  "tx": {
    "from": "0x1111111111111111111111111111111111111111",
    "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "data": "0xd0e30db0",
    "value": "10000000000000000"
  },
  "includeStateDiffs": true
}'

const response = await fetch("https://foresight.portals.fi/v1/simulate/trace?network=ethereum", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    tx: {
      from: "0x1111111111111111111111111111111111111111",
      to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      data: "0xd0e30db0",
      value: "10000000000000000",
    },
    includeStateDiffs: true,
  }),
});

const trace = await response.json();
console.log(trace.traceId, trace.callTrace);

import requests

response = requests.post(
    "https://foresight.portals.fi/v1/simulate/trace",
    params={"network": "ethereum"},
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY",
    },
    json={
        "tx": {
            "from": "0x1111111111111111111111111111111111111111",
            "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "data": "0xd0e30db0",
            "value": "10000000000000000",
        },
        "includeStateDiffs": True,
    },
)

trace = response.json()
print(trace["traceId"], trace["callTrace"])

Response Format

Returns the call tree, state changes, token movements, and decoded events when available. Selected fields for the wrapping example are shown below; trace IDs, blocks, and gas costs vary between requests.

CallFrame

StateDiff

StorageDiff

{
  "success": true,
  "traceId": "e8fb04cb-e222-42f9-876a-13408c67ac8f",
  "gasUsed": "27938",
  "gasCost": "6088502720854",
  "blockNumber": 26199345,
  "network": "ethereum",
  "callTrace": {
    "type": "CALL",
    "from": "0x1111111111111111111111111111111111111111",
    "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "functionName": "function deposit() payable",
    "input": "0xd0e30db0"
  },
  "assetChanges": [
    {
      "token": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "amount": "10000000000000000",
      "direction": "received",
      "standard": "erc20"
    },
    {
      "token": "0x0000000000000000000000000000000000000000",
      "amount": "10000000000000000",
      "direction": "sent",
      "standard": "native"
    }
  ]
}

Trace Limits

Each plan includes a monthly trace quota. Starter, Pro, and Business accounts can enable per-trace overage billing up to their configured cap.

Replay Transaction

Replay a historical on-chain transaction at its original block with full execution trace. Returns the same response format as POST /v1/simulate/trace. Counts against your monthly trace quota.

Path Parameters

Query Parameters

curl "https://foresight.portals.fi/v1/simulate/trace/tx/0x1cddbcf4e1adf110e500b0df2b33853a60c722b3a173af25913aa9785f394bc8?network=ethereum" \
  -H "X-Api-Key: YOUR_API_KEY"

Get Trace by ID

Retrieve a previously generated trace by its UUID. No authentication required — traces are shareable via URL. Does not count against quota (read-only cache lookup).

Traces are cached for 7 days. After expiration, returns 404. The cached response body may not include a traceId field, so clients should retain the requested UUID. View traces in the browser at https://foresight.portals.fi/trace?id=YOUR_TRACE_ID.

Path Parameters

curl "https://foresight.portals.fi/v1/simulate/trace/e8fb04cb-e222-42f9-876a-13408c67ac8f"

Error Handling

Reverted transactions

A reverted simulation still returns HTTP 200 with "success": false. The error field contains the decoded revert reason.

{
  "success": false,
  "error": "Insufficient output amount",
  "sender": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "gasUsed": "50000",
  "gasCost": "500000000000000",
  "assetChanges": [],
  "events": [],
  "errors": []
}

HTTP Error Codes

Validation errors

Invalid request fields return HTTP 400 with an errors array listing every issue:

{
  "success": false,
  "errors": [
    "inputToken must be a valid Ethereum address",
    "tx.value must be a valid number string"
  ]
}

Examples that contain ... inside calldata are shortened for readability. Real requests must send complete 0x-prefixed hex calldata.

Health Check

Returns the server's health status and the networks currently available in this deployment. No authentication required.

Returns 200 when healthy or partially available. Returns 503 when a required service fails or no networks are reachable.

Status Values

{
  "status": "ok",
  "timestamp": "2026-03-16T08:28:36.181Z",
  "totalNetworks": <configured count>,
  "healthyNetworks": <healthy count>,
  "networks": {
    "healthy": ["ethereum", "base", "arbitrum", "..."]
  }
}

Examples

Examples with ... or placeholder addresses are request templates, not executable quotes. Replace them with complete calldata and addresses for your chosen network. The Quick Start is a complete runnable example.

ERC20 token swap

Simulate a WETH to DAI swap through a DEX router. The sender doesn't need to hold WETH — balance is injected automatically.

curl -X POST "https://foresight.portals.fi/v1/simulate?network=ethereum" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "inputToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "inputAmount": "1000000000000000000",
    "tx": {
      "from": "0x1111111111111111111111111111111111111111",
      "to": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
      "data": "0x38ed1739...",
      "value": "0"
    }
  }'

const result = await fetch("https://foresight.portals.fi/v1/simulate?network=ethereum", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": process.env.PORTALS_API_KEY,
  },
  body: JSON.stringify({
    inputToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
    inputAmount: "1000000000000000000",              // 1 WETH
    tx: {
      from: "0x1111111111111111111111111111111111111111",
      to: "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",  // Uniswap V2
      data: "0x38ed1739...",
      value: "0",
    },
  }),
}).then(r => r.json());

Native token transfer

Simulate a plain native-token transfer. Use the zero address (0x000...0) or the native sentinel (0xEeee...eeeE) as inputToken and set tx.value to the amount in wei.

{
  "inputToken": "0x0000000000000000000000000000000000000000",
  "inputAmount": "1000000000000000000",
  "tx": {
    "from": "0x1111111111111111111111111111111111111111",
    "to": "0x2222222222222222222222222222222222222222",
    "data": "0x",
    "value": "1000000000000000000"
  }
}

Vault deposit with separate recipient

Use the recipient field when the output tokens go to a different address than the sender.

{
  "inputToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "inputAmount": "10000000000",
  "recipient": "0x2222222222222222222222222222222222222222",
  "tx": {
    "from": "0x1111111111111111111111111111111111111111",
    "to": "0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458",
    "data": "0x6e553f65...",  // ERC4626 deposit(amount, receiver)
    "value": "0"
  }
}

NFT / CLP position mint

Simulate a Uniswap V3 concentrated liquidity position mint. The response includes the ERC721 position NFT with its tokenId.

{
  "inputToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "inputAmount": "10000000000",
  "tx": {
    "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "to": "0xC36442b4a4522E871399CD717aBDD847Ab11FE88",
    "data": "0x88316456...",  // NonfungiblePositionManager.mint()
    "value": "0"
  }
}

{
  "success": true,
  "assetChanges": [
    {
      "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "amount": "4217390000",
      "direction": "sent",
      "standard": "erc20"
    },
    {
      "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "amount": "1500000000000000000",
      "direction": "sent",
      "standard": "erc20"
    },
    {
      "token": "0xC36442b4a4522E871399CD717aBDD847Ab11FE88",
      "amount": "1",
      "direction": "received",
      "standard": "erc721",
      "tokenId": "1207888"
    }
  ],
  "tokenMetadata": {
    "0xc36442b4a4522e871399cd717abdd847ab11fe88": {
      "name": "Uniswap V3 Positions NFT-V1",
      "symbol": "UNI-V3-POS",
      "decimals": 0,
      "standard": "erc721"
    },
    ...
  },
  ...
}

Multi-chain simulation

Simulate on any supported chain by changing the network query parameter. Token addresses differ per chain.

POST /v1/simulate?network=base

{
  "inputToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // USDC on Base
  "inputAmount": "1000000000",
  "tx": { ... }
}

POST /v1/simulate?network=polygon

{
  "inputToken": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",  // USDC on Polygon
  "inputAmount": "1000000000",
  "tx": { ... }
}

POST /v1/simulate?network=arbitrum

{
  "inputToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",  // USDC on Arbitrum
  "inputAmount": "1000000000",
  "tx": { ... }
}

Rendering results in your UI

Use tokenMetadata to display human-readable amounts:

function formatAssetChange(change, metadata) {
  const meta = metadata[change.token.toLowerCase()];

  // NFT: show token name + ID
  if (change.standard === "erc721" || change.standard === "erc1155") {
    const name = meta?.name || change.token;
    const sign = change.direction === "sent" ? "-" : "+";
    return `${sign}${change.amount} ${name} #${change.tokenId}`;
  }

  // Fungible: show decimal amount
  if (!meta) return `${change.amount} ${change.token}`;
  const digits = change.amount.padStart(meta.decimals + 1, "0");
  const whole = meta.decimals ? digits.slice(0, -meta.decimals) : digits;
  const fraction = meta.decimals ? digits.slice(-meta.decimals).replace(/0+$/, "") : "";
  const amount = whole + (fraction ? "." + fraction : "");
  const sign = change.direction === "sent" ? "-" : "+";
  return `${sign}${amount} ${meta.symbol}`;
}

// Output: "-4217.39 USDC" or "+1 Uniswap V3 Positions NFT-V1 #1207888"

Batch simulation — leverage loop

Chain Aave V3 supply → borrow → swap in a single call. Only the first step needs inputToken/inputAmount since subsequent steps consume tokens from prior state.

curl -X POST "https://foresight.portals.fi/v1/simulate/batch?network=ethereum" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sender": "0x1111111111111111111111111111111111111111",
    "steps": [
      {
        "inputToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "inputAmount": "10000000000",
        "tx": {
          "from": "0x1111111111111111111111111111111111111111",
          "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
          "data": "0x617ba037...",
          "value": "0"
        }
      },
      {
        "tx": {
          "from": "0x1111111111111111111111111111111111111111",
          "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
          "data": "0xa415bcad...",
          "value": "0"
        }
      },
      {
        "tx": {
          "from": "0x1111111111111111111111111111111111111111",
          "to": "0xE592427A0AEce92De3Edee1F18E0157C05861564",
          "data": "0xc04b8d59...",
          "value": "0"
        }
      }
    ]
  }'

const response = await fetch(
  "https://foresight.portals.fi/v1/simulate/batch?network=ethereum",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.PORTALS_API_KEY,
    },
    body: JSON.stringify({
      sender: "0x1111111111111111111111111111111111111111",
      steps: [
        {
          inputToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
          inputAmount: "10000000000",                      // 10,000 USDC
          tx: {
            from: "0x1111111111111111111111111111111111111111",
            to: "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",   // Aave V3
            data: "0x617ba037...",                             // supply()
            value: "0",
          },
        },
        {
          tx: {
            from: "0x1111111111111111111111111111111111111111",
            to: "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",   // Aave V3
            data: "0xa415bcad...",                             // borrow()
            value: "0",
          },
        },
        {
          tx: {
            from: "0x1111111111111111111111111111111111111111",
            to: "0xE592427A0AEce92De3Edee1F18E0157C05861564",   // Uniswap V3
            data: "0xc04b8d59...",                             // exactInput()
            value: "0",
          },
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(data.success);         // true
console.log(data.steps.length);    // 3
console.log(data.aggregate);       // combined SimulationResult

import requests

response = requests.post(
    "https://foresight.portals.fi/v1/simulate/batch",
    params={"network": "ethereum"},
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY",
    },
    json={
        "sender": "0x1111111111111111111111111111111111111111",
        "steps": [
            {
                "inputToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
                "inputAmount": "10000000000",
                "tx": {
                    "from": "0x1111111111111111111111111111111111111111",
                    "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
                    "data": "0x617ba037...",
                    "value": "0",
                },
            },
            {
                "tx": {
                    "from": "0x1111111111111111111111111111111111111111",
                    "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
                    "data": "0xa415bcad...",
                    "value": "0",
                },
            },
            {
                "tx": {
                    "from": "0x1111111111111111111111111111111111111111",
                    "to": "0xE592427A0AEce92De3Edee1F18E0157C05861564",
                    "data": "0xc04b8d59...",
                    "value": "0",
                },
            },
        ],
    },
)

data = response.json()
print(data["success"])         # True
print(len(data["steps"]))     # 3
print(data["aggregate"])      # combined SimulationResult

{
  "success": true,
  "steps": [
    { "stepIndex": 0, "success": true, "gasUsed": "248103" },
    { "stepIndex": 1, "success": true, "gasUsed": "312847" },
    { "stepIndex": 2, "success": true, "gasUsed": "184529" }
  ],
  "aggregate": {
    "blockNumber": "25932600",
    "blockHash": "0x21760a99d0e609a55db78ddeeb8b8c487eed54e19f39a550fbae40083390100c",
    "success": true,
    "sender": "0x1111111111111111111111111111111111111111",
    "assetChanges": [
      {
        "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "amount": "10000000000",
        "direction": "sent",
        "standard": "erc20"
      }
    ],
    "inputTokens": [
      { "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "amount": "10000000000" }
    ],
    "outputTokens": [...],
    "events": [...],
    "gasUsed": "745479",
    "gasCost": "2386840000000000",
    "tokenMetadata": {
      "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": {
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6
      }
    },
    "errors": []
  }
}

Supported Chains

Simulate transactions on supported EVM networks with the same API and response format. Call GET /v1/networks for the current registry, capabilities, and deployment availability.

How It Works

Understanding the simulation pipeline helps you get the most out of the API.

The simulation pipeline

When you send a request, here's what happens:

Balance injection

The key feature behind Portals Foresight is automatic balance injection. The sender address doesn't need to hold supported input tokens — we provision the simulated balance so you can test flows without pre-funding wallets.

You only need to supply the token address and amount. Some tokens take longer to prepare on the first request. Preparation and execution time vary by token and network.

What you can simulate

Any EVM transaction that interacts with tokens or NFTs:

• DEX swaps (Uniswap, Curve, 1inch, Paraswap, etc.)
• Lending deposits and borrows (Aave, Compound, Morpho)
• Vault deposits and withdrawals (ERC4626, Yearn, Beefy)
• Concentrated liquidity positions (Uniswap V3/V4 mint, burn, collect)
• NFT purchases and sales (OpenSea/Seaport, Blur, aggregators)
• ERC1155 transfers (game items, multi-token contracts)
• Flash loan arbitrage and leverage loops
• Bridge transactions (preview source-chain side)
• Batch/multi-step flows — supply→borrow→swap chains, leverage loops (Pro for API-key requests, or x402)
• Plain native token transfers
• Any contract call that moves ERC20, ERC721, or ERC1155 tokens

Rate Limits

Simulation and trace requests made with an API key use your plan's requests-per-second limit. Requests without an API key, including x402 requests, share a per-IP limit.

Rate limit headers

RPS-limited responses include these standard headers:

Request tracing

Send an X-Request-Id header to trace requests through your system. If omitted, a UUID is generated automatically. The value is echoed back in the response header.

# Your request
X-Request-Id: my-trace-id-abc123

# Response header
X-Request-Id: my-trace-id-abc123

x402 Payments

AI agents can pay per-request on supported simulation endpoints using the x402 protocol instead of an API key. Payments use USDC on Base. Trace endpoints still require API-key auth, except cached trace retrievals that are public.

Pricing

How it works

The x402 protocol uses HTTP 402 Payment Required to enable pay-per-request. The flow is fully automatic with compatible client libraries.

Client libraries

Use any x402-compatible client to handle the payment flow automatically:

Try the payment challenge

This request previews the same ETH-to-WETH call as the Quick Start, but without an API key. It returns 402 with payment instructions; this first request does not charge you.

curl -i -X POST "https://foresight.portals.fi/v1/simulate?network=ethereum" \
  -H "Content-Type: application/json" \
  -d '{
    "inputToken": "0x0000000000000000000000000000000000000000",
    "inputAmount": "10000000000000000",
    "tx": {
      "from": "0x1111111111111111111111111111111111111111",
      "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "data": "0xd0e30db0",
      "value": "10000000000000000"
    }
  }'

To complete a paid request, configure a client using the official JavaScript or Python buyer guide, then submit this same URL, method, and JSON body. The client handles the payment challenge and retry.

Foresight payments use real USDC on Base mainnet, even when the transaction being simulated is on another network. Configure your payment wallet for Base, not Base Sepolia. Simulation does not spend the example's ETH, but completing the payment retry does spend the advertised USDC fee.

LLM Integration

Give your AI coding assistant full context on the Portals Foresight API. Copy the docs as markdown or install the Claude Code skill.

Copy as Markdown

Click the Copy as Markdown button at the top of this page to copy the entire documentation as clean markdown. Paste it into ChatGPT, Claude, Gemini, Cursor, or any LLM-powered tool as context.

Claude Code Skill

If you use Claude Code, install the Portals Foresight skill so Claude automatically knows the API when you're writing integration code.

View and copy the skill file, then save it into your project:

# Create the skill directory and save SKILL.md into it
mkdir -p .claude/skills/portals-foresight

# Then paste the copied content into:
# .claude/skills/portals-foresight/SKILL.md

Once installed, Claude Code will automatically reference the Portals Foresight API when you ask it to write simulation code, build integrations, or debug API responses. You can also invoke it directly:

# Claude Code will auto-detect when relevant, or invoke directly:
/portals-foresight

# Example prompts that trigger the skill:
"Write a function that simulates a USDC to DAI swap on Ethereum"
"Add transaction preview to our swap UI using Portals Foresight"
"Debug why my simulation is returning success: false"

API Explorer

Test every endpoint directly in your browser. The explorer comes with pre-filled examples for simulate, batch simulate, and health.