HTTP Endpoints

Overview

All HTTP RPC endpoints accept POST requests with Content-Type: application/json and follow the JSON-RPC 2.0 specification.

Base Endpoint

Routes requests using the default strategy (configurable, defaults to load_balanced).

POST /rpc/:chain

Parameters

:chain - Chain identifier (name or numeric ID)
- Chain name: ethereum, base, arbitrum
- Chain ID: 1, 8453, 42161

Example

curl -X POST http://localhost:4000/rpc/ethereum \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x8471c9a"
}

Strategy Endpoints

Explicitly specify the routing strategy for provider selection.

Fastest

POST /rpc/fastest/:chain

Orders eligible providers by recent, reliability-qualified latency. Other eligible providers remain available for bounded fallback.

curl -X POST http://localhost:4000/rpc/fastest/ethereum \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Load Balanced

POST /rpc/load-balanced/:chain
POST /rpc/round-robin/:chain

Starts from randomized order and gives distinct physical instances a first pass for replay-safe requests.

curl -X POST http://localhost:4000/rpc/load-balanced/ethereum \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x0000000000000000000000000000000000000000","latest"],"id":1}'

Latency Weighted

POST /rpc/latency-weighted/:chain

Probabilistically routes requests with bias toward lower-latency providers.

curl -X POST http://localhost:4000/rpc/latency-weighted/ethereum \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x0000000000000000000000000000000000000000","data":"0x"},"latest"],"id":1}'

Provider Override Endpoints

Route directly to a specific provider, bypassing strategy selection.

POST /rpc/provider/:provider_id/:chain
POST /rpc/:chain/:provider_id

Parameters

:provider_id - Provider identifier (e.g., alchemy, infura, quicknode)
:chain - Chain identifier

Example

curl -X POST http://localhost:4000/rpc/provider/alchemy/ethereum \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Alternative syntax:

curl -X POST http://localhost:4000/rpc/ethereum/alchemy \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Profile-Scoped Endpoints

All routes above are available under a profile namespace for per-profile routing.

POST /rpc/profile/:profile/:chain
POST /rpc/profile/:profile/fastest/:chain
POST /rpc/profile/:profile/load-balanced/:chain
POST /rpc/profile/:profile/round-robin/:chain
POST /rpc/profile/:profile/latency-weighted/:chain
POST /rpc/profile/:profile/provider/:provider_id/:chain
POST /rpc/profile/:profile/:chain/:provider_id

Parameters

:profile - Profile slug (e.g., public, testnet, production)

Example

curl -X POST http://localhost:4000/rpc/profile/testnet/fastest/base \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Without an explicit profile in the URL, requests automatically use the "public" profile. Ensure config/profiles/public.yml exists at startup.

A profile selects configuration; it does not authenticate clients or isolate tenant traffic.

Method and transport policy

Core forwards supported reads and can send eth_sendRawTransaction to one upstream. It rejects eth_subscribe and eth_unsubscribe over HTTP and provides a WebSocket route hint. Unknown methods and provider-local filter methods have separate dispatch and affinity limits. See the released supported-methods contract for the complete method and execution-safety boundary.

Request Headers

Required Headers

Header	Value	Description
`Content-Type`	`application/json`	JSON request body

Optional Headers

Header	Example	Description
`X-Lasso-Provider`	`alchemy`	Override provider selection
`X-Lasso-Transport`	`http` or `ws`	Force transport selection
`X-Lasso-Include-Meta`	`headers` or `body`	Request observability metadata

Provider Override Header

You can specify a provider via header instead of URL path:

curl -X POST http://localhost:4000/rpc/ethereum \
  -H 'Content-Type: application/json' \
  -H 'X-Lasso-Provider: alchemy' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Query Parameters

Parameter	Values	Description
`include_meta`	`headers`, `body`	Return routing metadata
`transport`	`http`, `ws`	Force transport selection
`provider_override` or `provider_id`	provider ID	Override provider selection

Choose a strategy with its URL path, such as /rpc/fastest/ethereum. The default route does not use ?strategy= to override its strategy. Core does not authenticate client requests; protect the endpoint at your network or reverse proxy boundary.

Response Format

Success Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x8471c9a"
}

Error Response

For a request to /rpc/not-a-chain in the default public profile:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32602,
    "message": "Unsupported chain: Unknown chain 'not-a-chain' in profile 'public'"
  }
}

Error Codes

Code	Meaning
`-32700`	Parse error (malformed JSON)
`-32600`	Invalid Request (missing fields, batch too large)
`-32601`	Method not found or not supported on this transport
`-32602`	Invalid params (unsupported chain, missing chain_id)
`-32603`	Internal error
`-32000`	Server error (for example, upstream rate limiting or exhausted routing)

Response Headers

Standard Headers

Header	Description
`Content-Type`	`application/json`
`X-Request-Id`	Phoenix request ID

Observability Headers

With include_meta=headers:

Header	Description
`X-Lasso-Request-ID`	Lasso request tracking ID
`X-Lasso-Meta`	Base64url-encoded routing metadata

CORS

All origins are allowed (*). Allowed headers:

Content-Type
Authorization
X-Requested-With
X-Lasso-Provider
X-Lasso-Transport
X-Lasso-Include-Meta

Preflight responses are cached for 24 hours.

HTTP API

WebSocket API

Status and metrics

Reference

Releases and evidence

HTTP Endpoints

Overview

Base Endpoint

Parameters

Example

Strategy Endpoints

Fastest

Load Balanced

Latency Weighted

Provider Override Endpoints

Parameters

Example

Profile-Scoped Endpoints

Parameters

Example

Method and transport policy

Request Headers

Required Headers

Optional Headers

Provider Override Header

Query Parameters

Response Format

Success Response

Error Response

Error Codes

Response Headers

Standard Headers

Observability Headers

CORS

​Overview

​Base Endpoint

​Parameters

​Example

​Strategy Endpoints

​Fastest

​Load Balanced

​Latency Weighted

​Provider Override Endpoints

​Parameters

​Example

​Profile-Scoped Endpoints

​Parameters

​Example

​Method and transport policy

​Request Headers

​Required Headers

​Optional Headers

​Provider Override Header

​Query Parameters

​Response Format

​Success Response

​Error Response

​Error Codes

​Response Headers

​Standard Headers

​Observability Headers

​CORS

Overview

Base Endpoint

Parameters

Example

Strategy Endpoints

Fastest

Load Balanced

Latency Weighted

Provider Override Endpoints

Parameters

Example

Profile-Scoped Endpoints

Parameters

Example

Method and transport policy

Request Headers

Required Headers

Optional Headers

Provider Override Header

Query Parameters

Response Format

Success Response

Error Response

Error Codes

Response Headers

Standard Headers

Observability Headers

CORS