Search API

Size a calldata amount range and access monitoring endpoints through the public Search API.

The Search API is available at:

https://search-<endpoint>.evmkit.app/

Replace <endpoint> with your chosen regional endpoint. See Regions for the current layout.

Use the same headers as the RPC API:

Content-Type: application/json
X-Api-Key: evk_your_live_key

For pricing, use the single table on the Billing & CU pricing page.

`POST /v1/size`

Searches one or more input ranges and returns per-item sizing results for the provided calldata templates.

This request requires blockNumber and one or more items.

state is optional. If provided, set exactly one of state.raw or state.request. If omitted, sizing runs without additional state.

Like the public RPC API, public sizing requests use HTTPS with HTTP/2, share the same public HTTP connection leasing behavior, and benefit from reusing long-lived HTTP/2 connections. HTTP/1.1 requests to POST /v1/size can return 421.

Each batch item is capped to 18 iterations.

Example request:

{
  "state": {
    "hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "request": {
      "from": "0x1111111111111111111111111111111111111111",
      "to": "0x0000000000000000000000000000000000000000",
      "value": "0x0",
      "input": "0x"
    }
  },
  "blockNumber": "0x16e3600",
  "items": [
    {
      "range": {
        "from": "1",
        "to": "1000000",
        "precision": "10",
        "incrementer": "20"
      },
      "settings": {
        "includeOutputs": true,
        "threshold": "7",
        "profile": "balanced"
      },
      "request": {
        "from": "0x1234567890123456789012345678901234567890",
        "to": "0x1234567890123456789012345678901234567890",
        "value": "0x0",
        "input": [
          {
            "kind": "hex",
            "data": "0xabcdef"
          },
          {
            "kind": "amount",
            "codec": "u24be"
          },
          {
            "kind": "hex",
            "data": "99"
          }
        ]
      }
    }
  ]
}

Example success response:

{
  "items": [
    {
      "found": "300000",
      "error": null,
      "reason": "found_best",
      "searchMs": 18,
      "outputs": [
        {
          "in": "100000",
          "out": null,
          "gasSpent": 125000
        },
        {
          "in": "200000",
          "out": "5",
          "gasSpent": 390000
        },
        {
          "in": "300000",
          "out": "7",
          "gasSpent": 420000
        }
      ],
      "simulationsUsed": 3,
      "cusSpent": 12
    },
    {
      "found": null,
      "error": "not found",
      "reason": "no_positive_output",
      "searchMs": 11,
      "outputs": [
        {
          "in": "100000",
          "out": null,
          "gasSpent": 95000
        },
        {
          "in": "300000",
          "out": null,
          "gasSpent": 250001
        }
      ],
      "simulationsUsed": 2,
      "cusSpent": 5
    }
  ],
  "simulationsUsed": 5,
  "cusSpent": 17
}

Notes:

if state is present, state.hash must be a 32-byte 0x-prefixed hex string
set exactly one of state.raw or state.request
blockNumber selects the block used for the request
items must contain at least one entry
items can contain at most 10 entries
items[].range and items[].request are required; items[].settings is optional
set items[].settings.includeOutputs when you want every simulated attempt returned in that item’s response; failed simulations set out to null and still include gasSpent
items[].settings.profile is optional and supports fast, balanced, and deep; omitted defaults to deep
when items[].settings.threshold is set, sizing stops as soon as that threshold is reached
items[].range.from, items[].range.to, items[].range.precision, and items[].range.incrementer can be decimal strings or 0x-prefixed hex strings
items[].range.to must be greater than items[].range.from
items[].settings.threshold can be a decimal string or 0x-prefixed hex string
items[].range.precision and items[].range.incrementer are optional and default to 1
items[].range.precision controls the minimum search resolution and items[].range.incrementer controls the search step growth used by the sizing algorithm
items[].request.from and items[].request.to must be valid addresses, and items[].request.value is the call value used during sizing
items[].request.input must contain at least one amount segment
supported segment kinds are hex and amount
supported amount codecs are u16be, u24be, u32be, u40be, u64be, and trimmedBe
per-item simulationsUsed is capped at 18, and top-level simulationsUsed / cusSpent reflect the full batch totals
each sized item that runs costs a 1 CU base plus 1 CU for each started 100k gas across that item’s simulations
reason explains why an item stopped, and searchMs reports the item search time in milliseconds

`GET /v1/monitoring/positions`

Returns the current monitored positions for the requested protocols.

This endpoint is available only on the Advanced plan.

Example request:

curl -sS 'https://search-<endpoint>.evmkit.app/v1/monitoring/positions?protocol=protocol1&protocol=protocol2&limit=2&cursor=2' \
  -H 'X-Api-Key: evk_your_live_key'

Example response:

{
  "items": [
    {
      "id": "protocol1:0x1111111111111111111111111111111111111111",
      "protocol": "protocol1",
      "account": "0x1111111111111111111111111111111111111111",
      "collaterals": ["0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
      "loans": ["0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
      "markets": [],
      "healthFactor": "0.973421"
    },
    {
      "id": "protocol2:0x2222222222222222222222222222222222222222",
      "protocol": "protocol2",
      "account": "0x2222222222222222222222222222222222222222",
      "collaterals": [],
      "loans": [],
      "markets": ["0xcccccccccccccccccccccccccccccccccccccccc"],
      "healthFactor": "0.991002"
    }
  ],
  "nextCursor": "2"
}

Notes:

repeat protocol in the query string to request more than one protocol
cursor is an offset-style query parameter returned as nextCursor
healthFactor may be null when the underlying protocol does not expose a comparable value

`GET /v1/monitoring/unhealthy/ws`

Opens a websocket that forwards unhealthy-position events as they are observed.

This endpoint is available only on the Advanced plan.

Example connection:

npx wscat -c wss://search-<endpoint>.evmkit.app/v1/monitoring/unhealthy/ws -H 'X-Api-Key: evk_your_live_key'

Example event:

{
  "id": "protocol1:0x1111111111111111111111111111111111111111",
  "protocol": "protocol1",
  "account": "0x1111111111111111111111111111111111111111",
  "collaterals": ["0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
  "loans": ["0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
  "markets": [],
  "trigger": {
    "raw": "0x02f8728201..."
  },
  "observedAt": "2026-03-14T18:28:14Z"
}

Notes:

the feed publishes all supported protocols on one stream; there are no filters
events are forwarded as observed; clients should handle duplicates or reordering on their side
there is no replay on subscribe

Common errors

Status	Meaning
`400`	Invalid sizing request or pagination cursor
`401`	Missing or invalid API key
`402`	No active CU allowance, or monitoring access is unavailable below `Advanced`
`429`	Too many requests; see the rate limits page
`503`	Search API is temporarily unavailable