Liquidity Lens

Truefill, Execution-price oracle

API docs

Executable bid and ask for any token at any size, depth at 1 % and 2 %, batches on one block and 14 days of minute history. Every answer is pinned to a block and carries the exact route that produces it.

Base URL https://llens.abanchev.com/api/v1. Authentication, deadlines, metering and errors are on Getting started. See the Truefill live demo.

Example values are illustrative. Token addresses are real Base contracts; amounts are raw integer units as decimal strings.

GET/api/v1/ext/oracle/quote

Quote a trade

The exact amount out for any pair and amount at the latest block, the price, the impact against spot and the route proof.

Cost: 51 CU
Headers: Send your key in x-api-key and a compute budget in x-compute-budget-ms (1 to 5000 ms; the example uses 2000).

Query	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
tokenIn	yes	Token you sell (address).
tokenOut	yes	Token you receive (address).
amountIn	no	Raw units of tokenIn. Send this or sizeUsd, not both.
sizeUsd	no	Trade size in USD (the chain's quote token).
minBlock	no	Answer only from this block or later; 409 when our indexed state has not reached it yet.

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/quote?chainId=8453&tokenIn=0x4200000000000000000000000000000000000006&tokenOut=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&amountIn=10000000000000000000" \
  -H "x-api-key: $LL_API_KEY" \
  -H "x-compute-budget-ms: 2000"

Example response

{
  "chainId": "8453",
  "sequence": "1843207",
  "blockNumber": "52914031",
  "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
  "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
  "blockTimestamp": "1792419821",
  "stateAgeMs": 412,
  "tokenIn": "0x4200000000000000000000000000000000000006",
  "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "amountIn": "10000000000000000000",
  "amountOut": "26161734512",
  "price": "2616.1734512",
  "impactPercent": "0.0857978781",
  "spotSource": "canonical-stable-100usd-routing",
  "instantaneous": true,
  "route": [
    {
      "tokenIn": "0x4200000000000000000000000000000000000006",
      "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "amountIn": "10000000000000000000",
      "amountOut": "26161734512",
      "feeToken": "0x4200000000000000000000000000000000000006",
      "feeAmount": "4600000000000000",
      "legs": [
        {
          "pool": "0xd0b53d9277642d899df5c87a3966a349a798f224",
          "deploymentId": 41,
          "dex": "Uniswap v3",
          "tokenIn": "0x4200000000000000000000000000000000000006",
          "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "amountIn": "6000000000000000000",
          "amountOut": "15697201234",
          "feeToken": "0x4200000000000000000000000000000000000006",
          "feeAmount": "3000000000000000",
          "shareNumerator": "3",
          "shareDenominator": "5"
        },
        {
          "pool": "0xb2cc224c1c9fee385f8ad6a55b4d94e92359dc59",
          "deploymentId": 57,
          "dex": "Aerodrome Slipstream",
          "tokenIn": "0x4200000000000000000000000000000000000006",
          "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "amountIn": "4000000000000000000",
          "amountOut": "10464533278",
          "feeToken": "0x4200000000000000000000000000000000000006",
          "feeAmount": "1600000000000000",
          "shareNumerator": "2",
          "shareDenominator": "5"
        }
      ]
    }
  ]
}

GET/api/v1/ext/oracle/price

Price at a USD size

price(asset, size, side): the executable USD price to sell (bid) or buy (ask) a token at an explicit size, with the route.

Cost: 51 CU
Headers: Send your key in x-api-key and a compute budget in x-compute-budget-ms (1 to 5000 ms; the example uses 2000).

Query	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
token	yes	Token address.
sizeUsd	yes	Trade size in USD.
side	yes	sell (bid) or buy (ask).
minBlock	no	Answer only from this block or later; 409 when our indexed state has not reached it yet.

Ask for the quote token itself (USDC on Base) and the answer is flagged isQuoteToken: true with quoteTokenRate, its executable rate into USDT at that size. See the second example below.

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/price?chainId=8453&token=0x4200000000000000000000000000000000000006&sizeUsd=100000&side=sell" \
  -H "x-api-key: $LL_API_KEY" \
  -H "x-compute-budget-ms: 2000"

Example response

{
  "chainId": "8453",
  "sequence": "1843207",
  "blockNumber": "52914031",
  "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
  "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
  "blockTimestamp": "1792419821",
  "stateAgeMs": 412,
  "token": "0x4200000000000000000000000000000000000006",
  "side": "sell",
  "sizeUsd": "100000",
  "priceUsd": "2615.53",
  "spotUsd": "2618.42",
  "impactPercent": "0.1103719037",
  "amountIn": "38190970127023163627",
  "amountOut": "99889628096",
  "route": [
    {
      "tokenIn": "0x4200000000000000000000000000000000000006",
      "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "amountIn": "38190970127023163627",
      "amountOut": "99889628096",
      "feeToken": "0x4200000000000000000000000000000000000006",
      "feeAmount": "17567846258430655",
      "legs": [
        {
          "pool": "0xd0b53d9277642d899df5c87a3966a349a798f224",
          "deploymentId": 41,
          "dex": "Uniswap v3",
          "tokenIn": "0x4200000000000000000000000000000000000006",
          "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "amountIn": "22914582076213898176",
          "amountOut": "59935001902",
          "feeToken": "0x4200000000000000000000000000000000000006",
          "feeAmount": "11457291038106949",
          "shareNumerator": "3",
          "shareDenominator": "5"
        },
        {
          "pool": "0xb2cc224c1c9fee385f8ad6a55b4d94e92359dc59",
          "deploymentId": 57,
          "dex": "Aerodrome Slipstream",
          "tokenIn": "0x4200000000000000000000000000000000000006",
          "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "amountIn": "15276388050809265451",
          "amountOut": "39954626194",
          "feeToken": "0x4200000000000000000000000000000000000006",
          "feeAmount": "6110555220323706",
          "shareNumerator": "2",
          "shareDenominator": "5"
        }
      ]
    }
  ],
  "canonicalStable": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "spotSource": "canonical-stable-100usd-routing",
  "instantaneous": true,
  "isQuoteToken": false
}

GET/api/v1/ext/oracle/price

Price of the quote token

Every price is in the chain's quote token, so its own price is 1 by definition. The answer says so and adds the real executable rate into USDT, or the reason there is none.

Cost: 51 CU
Headers: Send your key in x-api-key and a compute budget in x-compute-budget-ms (1 to 5000 ms; the example uses 2000).

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/price?chainId=8453&token=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&sizeUsd=100000&side=sell" \
  -H "x-api-key: $LL_API_KEY" \
  -H "x-compute-budget-ms: 2000"

Example response

{
  "chainId": "8453",
  "sequence": "1843207",
  "blockNumber": "52914031",
  "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
  "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
  "blockTimestamp": "1792419821",
  "stateAgeMs": 412,
  "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "side": "sell",
  "sizeUsd": "100000",
  "priceUsd": "1",
  "spotUsd": "1",
  "impactPercent": "0",
  "amountIn": "100000000000",
  "amountOut": "100000000000",
  "route": [],
  "canonicalStable": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "spotSource": "canonical-stable-100usd-routing",
  "instantaneous": true,
  "isQuoteToken": true,
  "quoteTokenRate": {
    "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "symbol": "USDC",
    "decimals": 6,
    "side": "sell",
    "sizeUsd": "100000",
    "amountIn": "100000000000",
    "amountOut": "99987412345",
    "rate": "0.99987412345",
    "route": [
      {
        "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "tokenOut": "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2",
        "amountIn": "100000000000",
        "amountOut": "99987412345",
        "feeToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "feeAmount": "10000000",
        "legs": [
          {
            "pool": "0x8d3c9f1d8a2e6b0f1c4e5a7b9d2f3a6c8e0b1d4f",
            "deploymentId": 63,
            "dex": "Uniswap v3",
            "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
            "tokenOut": "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2",
            "amountIn": "100000000000",
            "amountOut": "99987412345",
            "feeToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
            "feeAmount": "10000000",
            "shareNumerator": "1",
            "shareDenominator": "1"
          }
        ]
      }
    ]
  },
  "quoteTokenRateUnavailable": null
}

GET/api/v1/ext/oracle/depth

Depth and ladder

Bid and ask from $1K to $10M and the size that moves the price 1 % and 2 % on each side, found by bisection on the router.

Cost: 51 CU
Headers: Send your key in x-api-key and a compute budget in x-compute-budget-ms (1 to 5000 ms; the example uses 2000).

Query	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
token	yes	Token address.
minBlock	no	Answer only from this block or later; 409 when our indexed state has not reached it yet.

Abridged: two of the ladder's levels shown. A size with no executable route is listed with its reason, never dropped.

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/depth?chainId=8453&token=0x4200000000000000000000000000000000000006" \
  -H "x-api-key: $LL_API_KEY" \
  -H "x-compute-budget-ms: 2000"

Example response

{
  "chainId": "8453",
  "sequence": "1843207",
  "blockNumber": "52914031",
  "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
  "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
  "blockTimestamp": "1792419821",
  "stateAgeMs": 412,
  "token": "0x4200000000000000000000000000000000000006",
  "canonicalStable": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "instantaneous": true,
  "spotUsd": "2618.42",
  "spreadPercent": "0.0412",
  "levels": [
    {
      "chainId": "8453",
      "sequence": "1843207",
      "blockNumber": "52914031",
      "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
      "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
      "blockTimestamp": "1792419821",
      "stateAgeMs": 412,
      "token": "0x4200000000000000000000000000000000000006",
      "side": "sell",
      "sizeUsd": "100000",
      "priceUsd": "2615.53",
      "spotUsd": "2618.42",
      "impactPercent": "0.1103719037",
      "amountIn": "38190970127023163627",
      "amountOut": "99889628096",
      "route": [
        {
          "tokenIn": "0x4200000000000000000000000000000000000006",
          "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "amountIn": "38190970127023163627",
          "amountOut": "99889628096",
          "feeToken": "0x4200000000000000000000000000000000000006",
          "feeAmount": "17567846258430655",
          "legs": [
            {
              "pool": "0xd0b53d9277642d899df5c87a3966a349a798f224",
              "deploymentId": 41,
              "dex": "Uniswap v3",
              "tokenIn": "0x4200000000000000000000000000000000000006",
              "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "amountIn": "22914582076213898176",
              "amountOut": "59935001902",
              "feeToken": "0x4200000000000000000000000000000000000006",
              "feeAmount": "11457291038106949",
              "shareNumerator": "3",
              "shareDenominator": "5"
            },
            {
              "pool": "0xb2cc224c1c9fee385f8ad6a55b4d94e92359dc59",
              "deploymentId": 57,
              "dex": "Aerodrome Slipstream",
              "tokenIn": "0x4200000000000000000000000000000000000006",
              "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "amountIn": "15276388050809265451",
              "amountOut": "39954626194",
              "feeToken": "0x4200000000000000000000000000000000000006",
              "feeAmount": "6110555220323706",
              "shareNumerator": "2",
              "shareDenominator": "5"
            }
          ]
        }
      ],
      "canonicalStable": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "spotSource": "canonical-stable-100usd-routing",
      "instantaneous": true,
      "available": true
    },
    {
      "chainId": "8453",
      "sequence": "1843207",
      "blockNumber": "52914031",
      "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
      "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
      "blockTimestamp": "1792419821",
      "stateAgeMs": 412,
      "available": false,
      "token": "0x4200000000000000000000000000000000000006",
      "side": "buy",
      "sizeUsd": "10000000",
      "reason": "NO_EXECUTABLE_ROUTE",
      "instantaneous": true
    }
  ],
  "bid1Percent": {
    "sizeUsd": "2410000",
    "atLeast": false,
    "resolutionUsd": "10000"
  },
  "bid2Percent": {
    "sizeUsd": "5870000",
    "atLeast": false,
    "resolutionUsd": "10000"
  },
  "ask1Percent": {
    "sizeUsd": "2260000",
    "atLeast": false,
    "resolutionUsd": "10000"
  },
  "ask2Percent": {
    "sizeUsd": "5120000",
    "atLeast": false,
    "resolutionUsd": "10000"
  }
}

POST/api/v1/ext/oracle/batch

Batch on one block

Up to 100 quotes computed on the same block in one call. Above 100, the answer is a task id to read with batch-result.

Cost: 50 CU + 1 CU per item
Headers: Send your key in x-api-key and a compute budget in x-compute-budget-ms (1 to 5000 ms; the example uses 2000).

Body	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
quotes	yes	Array of { tokenIn, tokenOut, amountIn \| sizeUsd }.
minBlock	no	Answer only from this block or later; 409 when our indexed state has not reached it yet.

Abridged: the second route is shortened.

curl -s -X POST "https://llens.abanchev.com/api/v1/ext/oracle/batch" \
  -H "x-api-key: $LL_API_KEY" \
  -H "x-compute-budget-ms: 2000" \
  -H "content-type: application/json" \
  -d '{"chainId":"8453","quotes":[{"tokenIn":"0x4200000000000000000000000000000000000006","tokenOut":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","amountIn":"10000000000000000000"},{"tokenIn":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","tokenOut":"0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf","sizeUsd":"250000"}]}'

Example response

{
  "chainId": "8453",
  "sequence": "1843207",
  "blockNumber": "52914031",
  "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
  "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
  "blockTimestamp": "1792419821",
  "stateAgeMs": 412,
  "results": [
    {
      "chainId": "8453",
      "sequence": "1843207",
      "blockNumber": "52914031",
      "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
      "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
      "blockTimestamp": "1792419821",
      "stateAgeMs": 412,
      "tokenIn": "0x4200000000000000000000000000000000000006",
      "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "amountIn": "10000000000000000000",
      "amountOut": "26161734512",
      "price": "2616.1734512",
      "impactPercent": "0.0857978781",
      "spotSource": "canonical-stable-100usd-routing",
      "instantaneous": true,
      "route": [
        {
          "tokenIn": "0x4200000000000000000000000000000000000006",
          "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "amountIn": "10000000000000000000",
          "amountOut": "26161734512",
          "feeToken": "0x4200000000000000000000000000000000000006",
          "feeAmount": "4600000000000000",
          "legs": [
            {
              "pool": "0xd0b53d9277642d899df5c87a3966a349a798f224",
              "deploymentId": 41,
              "dex": "Uniswap v3",
              "tokenIn": "0x4200000000000000000000000000000000000006",
              "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "amountIn": "6000000000000000000",
              "amountOut": "15697201234",
              "feeToken": "0x4200000000000000000000000000000000000006",
              "feeAmount": "3000000000000000",
              "shareNumerator": "3",
              "shareDenominator": "5"
            },
            {
              "pool": "0xb2cc224c1c9fee385f8ad6a55b4d94e92359dc59",
              "deploymentId": 57,
              "dex": "Aerodrome Slipstream",
              "tokenIn": "0x4200000000000000000000000000000000000006",
              "tokenOut": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "amountIn": "4000000000000000000",
              "amountOut": "10464533278",
              "feeToken": "0x4200000000000000000000000000000000000006",
              "feeAmount": "1600000000000000",
              "shareNumerator": "2",
              "shareDenominator": "5"
            }
          ]
        }
      ]
    },
    {
      "chainId": "8453",
      "sequence": "1843207",
      "blockNumber": "52914031",
      "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
      "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
      "blockTimestamp": "1792419821",
      "stateAgeMs": 412,
      "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenOut": "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
      "amountIn": "250000000000",
      "amountOut": "230418211",
      "price": "0.00000921672844",
      "impactPercent": "0.0784",
      "spotSource": "canonical-stable-100usd-routing",
      "instantaneous": true,
      "route": [
        {
          "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "tokenOut": "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
          "amountIn": "250000000000",
          "amountOut": "230418211",
          "feeToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "feeAmount": "125000000",
          "legs": [
            {
              "pool": "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
              "deploymentId": 41,
              "dex": "Uniswap v3",
              "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "tokenOut": "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
              "amountIn": "250000000000",
              "amountOut": "230418211",
              "feeToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "feeAmount": "125000000",
              "shareNumerator": "1",
              "shareDenominator": "1"
            }
          ]
        }
      ]
    }
  ]
}

POST/api/v1/ext/oracle/health

Token health

Per token and size: the round-trip gap between spot and executable price now, its 24-hour baseline from stored reference samples, and a flag when the gap is above the configured multiple of the baseline.

Cost: 50 CU + 1 CU per token × size
Headers: Send your key in x-api-key and a compute budget in x-compute-budget-ms (1 to 5000 ms; the example uses 2000).

Body	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
items	yes	Up to 25 distinct { token, sizeUsd } pairs.
minBlock	no	Answer only from this block or later; 409 when our indexed state has not reached it yet.

Baselines exist for the reference sizes ($10K and $100K) of sampled assets. Anything else answers baseline: null with the reason.

curl -s -X POST "https://llens.abanchev.com/api/v1/ext/oracle/health" \
  -H "x-api-key: $LL_API_KEY" \
  -H "x-compute-budget-ms: 2000" \
  -H "content-type: application/json" \
  -d '{"chainId":"8453","items":[{"token":"0x4200000000000000000000000000000000000006","sizeUsd":"100000"},{"token":"0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf","sizeUsd":"10000"}]}'

Example response

{
  "chainId": "8453",
  "sequence": "1843207",
  "blockNumber": "52914031",
  "blockHash": "0x7c1e5f0b9a2d43e8c6f1a0b7d9e2c4f6a8b0d1e3f5a7c9b2d4e6f8a0c2e4b6d8",
  "stateDigest": "4b9e0c7f2a1d3e5b8c6a9f0d2e4b7c1a3f5e8d0b2c4a6e9f1d3b5c7a0e2f4d6b",
  "blockTimestamp": "1792419821",
  "stateAgeMs": 412,
  "canonicalStable": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "gapMultiple": 3,
  "minSamples": 144,
  "items": [
    {
      "token": "0x4200000000000000000000000000000000000006",
      "sizeUsd": "100000",
      "spotUsd": "2618.42",
      "sellImpactPercent": "0.1103719037",
      "buyImpactPercent": "0.1126633619",
      "gapPercent": "0.2230352656",
      "unavailable": null,
      "baseline": {
        "percent": "0.1874",
        "samples": 24,
        "from": "2026-10-18T14:23:41.000Z",
        "to": "2026-10-19T14:23:41.000Z"
      },
      "baselineUnavailable": null,
      "flag": false
    },
    {
      "token": "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
      "sizeUsd": "10000",
      "spotUsd": "108412.55",
      "sellImpactPercent": "0.0211",
      "buyImpactPercent": "0.0234",
      "gapPercent": "0.0445",
      "unavailable": null,
      "baseline": {
        "percent": "0.0131",
        "samples": 281,
        "from": "2026-10-18T14:23:41.000Z",
        "to": "2026-10-19T14:23:41.000Z"
      },
      "baselineUnavailable": null,
      "flag": true
    }
  ]
}

GET/api/v1/ext/oracle/history

Minute history

Executable price at a size over any interval in the last 14 days. Each point keeps its block and the digest of its route proof.

Cost: 50 CU
Headers: Send your key in x-api-key.

Query	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
token	yes	Token address.
side	yes	sell or buy.
sizeUsd	yes	Trade size in USD.
from	yes	Start, unix seconds.
to	yes	End, unix seconds.

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/history?chainId=8453&token=0x4200000000000000000000000000000000000006&side=sell&sizeUsd=100000&from=1792333421&to=1792419821" \
  -H "x-api-key: $LL_API_KEY"

POST/api/v1/ext/oracle/swap-costs

Swap-cost history

For backtests: the average, p50 and p90 cost of trading each token or pair at your sizes, per hour, day or week over the last 14 days, against the mid at the same block, with the fee part, the pools used and the 1 % depth.

Cost: 50 CU + 1 CU per item × size × side × bucket
Headers: Send your key in x-api-key.

Body	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
items	yes	Up to 20 tokens ({ token }) or pairs ({ tokenIn, tokenOut }).
sizesUsd	yes	1 to 3 trade sizes in USD.
sides	no	buy, sell or both (the default); a pair has one side.
from	yes	Start, unix seconds, within the last 14 days.
to	yes	End, unix seconds, at most 14 days after from.
bucket	yes	hour, day or week (UTC; weeks start Monday).

Tokens with stored oracle minutes in every bucket are answered at once (status complete). Anything else is a task: poll /ext/oracle/swap-costs-task. Either answer carries estimates at once (estimates: a fee estimate from today's route at each bucket's replayed pool fees, and a two-leg upper bound from stored minutes), within the same CU. At most 1680 units per call, 1 running task and 20 tasks a day per organization.

curl -s -X POST "https://llens.abanchev.com/api/v1/ext/oracle/swap-costs" \
  -H "x-api-key: $LL_API_KEY" \
  -H "content-type: application/json" \
  -d '{"chainId":"8453","items":[{"token":"0x4200000000000000000000000000000000000006"},{"token":"0x940181a94a35a4569e4529a3cdfb74e38fd98631"},{"token":"0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf"},{"tokenIn":"0x940181a94a35a4569e4529a3cdfb74e38fd98631","tokenOut":"0x4200000000000000000000000000000000000006"}],"sizesUsd":["1000","10000","100000"],"sides":["buy","sell"],"from":"1791763200","to":"1792972800","bucket":"day"}'

Example response

{
  "status": "queued",
  "units": 294,
  "taskId": "6d2b8f3e-1c4a-4e7b-9f20-8a5c3d1e7b42",
  "taskStatus": "queued",
  "cached": false,
  "attachedToTaskId": null,
  "estimates": {
    "kind": "estimates",
    "note": "Estimates, not the exact cost: feeBp prices today's best route with each pool's replayed effective fee in the bucket (the route's own live rate where the pool had no exact swaps, or for Liquidity Book pools, whose fee depends on size); twoLegUpperCostBp is an upper bound from stored oracle minutes. The exact cost is the fork-sampled result.",
    "chains": [
      {
        "chainId": "8453",
        "routeBlockNumber": "52870000",
        "routeBlockHash": "0x7c1e4a9b2d6f8a0c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c",
        "routeUnavailable": null,
        "timingsMs": {
          "route": 242,
          "marketStats": 24,
          "oracleHistory": 1983
        }
      }
    ],
    "rows": [
      {
        "item": 0,
        "sizeUsd": "10000",
        "side": "sell",
        "bucketStart": "2026-10-17T00:00:00.000Z",
        "bucketEnd": "2026-10-18T00:00:00.000Z",
        "feeBp": "3.71",
        "feeSource": "replayed",
        "feeCoverage": "1",
        "feeUnavailable": null,
        "twoLegUpperCostBp": null,
        "twoLegSamples": 0,
        "twoLegUnavailable": "SWAP_COST_NOT_A_PAIR"
      },
      {
        "item": 3,
        "sizeUsd": "10000",
        "side": "swap",
        "bucketStart": "2026-10-17T00:00:00.000Z",
        "bucketEnd": "2026-10-18T00:00:00.000Z",
        "feeBp": "17.6",
        "feeSource": "tier",
        "feeCoverage": "0.82",
        "feeUnavailable": null,
        "twoLegUpperCostBp": "34.1",
        "twoLegSamples": 1436,
        "twoLegUnavailable": null
      }
    ]
  }
}

GET/api/v1/ext/oracle/swap-costs-task

Swap-cost task result

Status, progress and result of this key's own swap-cost task. A task that fails on our side has its CU refunded, and the answer says so.

Cost: 0 CU
Headers: Send your key in x-api-key.

Query	Required	Description
taskId	yes	The id the swap-costs call returned.

Abridged: two rows and two method lines of each kind shown. costBp is one way and all in: (mid − executable) / mid, positive for a cost on both sides. For a pair, twoLegCostBp is selling tokenIn and buying tokenOut through the stable at the same blocks; costBp never exceeds it. samples is the count actually used: one fork sample per hour (24 in a full day, fewer where an hour had no published block or a partial bucket), or one per minute from stored minutes.

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/swap-costs-task?taskId=6d2b8f3e-1c4a-4e7b-9f20-8a5c3d1e7b42" \
  -H "x-api-key: $LL_API_KEY"

Example response

{
  "taskId": "6d2b8f3e-1c4a-4e7b-9f20-8a5c3d1e7b42",
  "status": "succeeded",
  "progressPct": 100,
  "progressMessage": null,
  "errorCode": null,
  "errorMessage": null,
  "refunded": false,
  "result": {
    "kind": "swap-costs",
    "basis": "executable-vs-mid",
    "mid": "midpoint-1000usd-bid-ask",
    "bucket": "day",
    "from": "2026-10-06T00:00:00.000Z",
    "to": "2026-10-20T00:00:00.000Z",
    "samplesPerHour": 1,
    "depthSamplesPerHour": 1,
    "chains": [
      {
        "chainId": "8453",
        "retentionDays": 14,
        "windowFrom": "2026-10-06T00:00:00.000Z",
        "forkSamples": 336,
        "cachedSamples": 0
      }
    ],
    "items": [
      {
        "kind": "token",
        "chainId": "8453",
        "token": "0x4200000000000000000000000000000000000006"
      },
      {
        "kind": "token",
        "chainId": "8453",
        "token": "0x940181a94a35a4569e4529a3cdfb74e38fd98631"
      },
      {
        "kind": "token",
        "chainId": "8453",
        "token": "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf"
      },
      {
        "kind": "pair",
        "chainId": "8453",
        "tokenIn": "0x940181a94a35a4569e4529a3cdfb74e38fd98631",
        "tokenOut": "0x4200000000000000000000000000000000000006"
      }
    ],
    "rows": [
      {
        "item": 0,
        "sizeUsd": "10000",
        "side": "sell",
        "bucketStart": "2026-10-17T00:00:00.000Z",
        "bucketEnd": "2026-10-18T00:00:00.000Z",
        "source": "fork-samples",
        "samples": 24,
        "unavailableSamples": 0,
        "costBp": "3.486032",
        "p50CostBp": "3.321158",
        "p90CostBp": "4.965172",
        "feeBp": "3.837631",
        "impactBp": "-0.351599",
        "splitSamples": 24,
        "pools": [
          {
            "pool": "0xd0b53d9277642d899df5c87a3966a349a798f224",
            "dex": "Uniswap v3 BASE",
            "feeBp": "5",
            "share": "0.61",
            "samples": 24
          },
          {
            "pool": "0xb2cc224c1c9fee385f8ad6a55b4d94e92359dc59",
            "dex": "Aerodrome Slipstream BASE",
            "feeBp": "4",
            "share": "0.39",
            "samples": 21
          }
        ],
        "depth1PctUsd": "10000000",
        "depthSamples": 24,
        "twoLegCostBp": null,
        "unavailable": null
      },
      {
        "item": 3,
        "sizeUsd": "10000",
        "side": "swap",
        "bucketStart": "2026-10-17T00:00:00.000Z",
        "bucketEnd": "2026-10-18T00:00:00.000Z",
        "source": "fork-samples",
        "samples": 24,
        "unavailableSamples": 0,
        "costBp": "26.93404",
        "p50CostBp": "28.5765",
        "p90CostBp": "34.57592",
        "feeBp": "17.25223",
        "impactBp": "9.68181",
        "splitSamples": 24,
        "pools": [
          {
            "pool": "0xcdac0d6c6c59727a65f871236188350531885c43",
            "dex": "Aerodrome v2 BASE",
            "feeBp": "30",
            "share": "0.55",
            "samples": 24
          },
          {
            "pool": "0xb2cc224c1c9fee385f8ad6a55b4d94e92359dc59",
            "dex": "Aerodrome Slipstream BASE",
            "feeBp": "4",
            "share": "0.45",
            "samples": 23
          }
        ],
        "depth1PctUsd": "2255014",
        "depthSamples": 24,
        "twoLegCostBp": "33.00114",
        "unavailable": null
      }
    ],
    "method": {
      "exact": [
        "cost: (mid − executable) / mid × 10,000 bp one way, all in (fees and price impact), at the same block, signed so a cost is positive on both sides: a sell (mid − bid) / mid, a buy (ask − mid) / mid, with prices in USD per token",
        "mid: the midpoint of the token's executable $1,000 bid and ask in the canonical stable at that block, the oracle's own mid ((bid + ask) / 2); a pair's reference is midIn / midOut"
      ],
      "modelled": [
        "fork samples: one block per sample slot, by default one per hour (the first canonical bound publication at or after the hour): 1 sample in an hourly bucket, 24 in a day, 168 in a week; with one sample, p50 and p90 are that sample",
        "impact: the remainder of the cost after the fee part, so it can be negative where one side's fees are below the mid's half-spread; impact on an earlier hop that changes what a later hop receives is not separated"
      ]
    }
  }
}

GET/api/v1/ext/oracle/reference

Reference price

Time-weighted median of per-block samples over 5, 30 or 60 minutes at $10K or $100K, with coverage and status. Conditions are reported, never clamped.

Cost: 51 CU
Headers: Send your key in x-api-key.

Query	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
token	yes	Token address.
sizeUsd	yes	10000 or 100000.
windowSeconds	no	300, 1800 (default) or 3600.

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/reference?chainId=8453&token=0x4200000000000000000000000000000000000006&sizeUsd=100000&windowSeconds=1800" \
  -H "x-api-key: $LL_API_KEY"

GET/api/v1/ext/oracle/assets

Asset inventory

Every asset the oracle prices on a chain, with published spot, spread and ±1 % / ±2 % depth.

Cost: 50 CU
Headers: Send your key in x-api-key and a compute budget in x-compute-budget-ms (1 to 5000 ms; the example uses 2000).

Query	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
minBlock	no	Answer only from this block or later; 409 when our indexed state has not reached it yet.

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/assets?chainId=8453" \
  -H "x-api-key: $LL_API_KEY" \
  -H "x-compute-budget-ms: 2000"

GET/api/v1/ext/oracle/batch-result

Async batch result

Status and result of this key's own batch above 100 quotes.

Cost: 50 CU
Headers: Send your key in x-api-key.

Query	Required	Description
taskId	yes	The id the batch call returned.

curl -s "https://llens.abanchev.com/api/v1/ext/oracle/batch-result?taskId=3f8f6a52-6f0e-4d2b-9a43-1b2c3d4e5f60" \
  -H "x-api-key: $LL_API_KEY"

GET/api/v1/public/oracle/overview

Free: market overview

No key. The deepest assets per chain with bid, ask and mid at a reference size, depth and 24 h change.

Cost: free, 1 request/s per IP
Headers: No key needed. Rate limited per IP.

Query	Required	Description
chainId	yes	8453 (Base) or 146 (Sonic).
limit	no	Number of assets.
sizeUsd	no	Reference size.

curl -s "https://llens.abanchev.com/api/v1/public/oracle/overview?chainId=8453&limit=5&sizeUsd=100000"