Custom profiles

A Custom profile is a pool of your own nodes and provider accounts, routed by the same engine as Lasso’s managed pools. Every key of the account reaches it at /profile/<slug>/…. Create one when you already pay for providers or run nodes and want failover, latency routing and evidence over them.

PUT https://lasso.sh/api/v1/profiles/prod-base?dry_run=true
Authorization: Bearer <management token>
Content-Type: application/json

{"name": "Production Base", "chains": {"base": {"providers": [
  {"name": "alchemy", "url": "https://base-mainnet.g.alchemy.com/v2/…"},
  {"name": "my-node", "url": "https://node.example.com"}
]}}}

The dry run checks every new provider, changes nothing, and needs no Custom access. Saving needs Custom access: an account that has never had it gets five free days on its first saved profile; otherwise subscribe, or buy days with a wallet (trial your own providers). Then repeat the PUT without dry_run and call it:

curl -sS "https://lasso.sh/rpc/k/<key>/profile/prod-base/fastest/base" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

The document

The profile is one JSON document: the whole desired state. The dashboard edits the same document, so a profile an agent builds looks and behaves the same for everyone on the account. The minimum is a chain with a provider list; every other field is optional:

Field	Level	Use it when
`url`, `ws_url`	provider	Always; add `ws_url` when the app subscribes
`headers`	provider	The provider authenticates with secret request headers, shared by its HTTP and WebSocket endpoints
List order	provider	You use the `priority` strategy; first is preferred
`block_protection`	chain	The app polls the latest block and shouldn’t see it go backwards
`max_lag_blocks`	chain	The app tolerates less (or more) staleness than the chain default
`heads`: `live`, `standby`, `passive`, `off`	provider	You want to choose how Lasso tracks a provider’s head; see head tracking
`background_observations`	provider	`false` stops background checks and idle recovery on a provider you’re not actively using; defaults to `true`. `heads: off` only stops head observation
`health_checks`: `standard` or `light`	chain	Lasso’s checks should spend less of your provider quota
`error_interpretation`	profile	You opt in to Lasso interpreting your providers’ error messages
`limits`: `archival`, `logs_span`, `methods_blocked`	provider	You know a limit Lasso hasn’t learned, such as your plan’s log-span cap

Chains are keyed by name or decimal ID. The live field list, limits and workload recipes are in the configuration schema. Editing rules:

Omit a provider, and it’s removed; a dry run lists every removal.
Omit url on a provider you’re keeping, and its stored URL stays.
Omit headers, and stored headers stay; {} clears them; a map replaces them all.
Send If-Match: <revision> to refuse the change if someone else changed the profile since you read it. After a lost response, re-read the revision rather than repeating the PUT blindly.

Onboarding: what Lasso checks

When you save, Lasso checks the chain identity (eth_chainId) of every new or changed provider before storing anything:

Status	Meaning
`verified`	Serves the configured chain, and routes
`verifying`	Didn’t answer; saved but kept out of routing, and rechecked every five minutes
`failed`	Definitely wrong, such as another chain. The whole `PUT` is rejected with `provider_check_failed`, naming the provider

A newly created profile has no live revision yet: it reports activating with retry_after_seconds until its first revision is ready, and RPC on it refuses with a retryable 503 (service_initializing) until then. Read GET /api/v1/profiles/{slug} until it reports live before moving traffic. Saving a replacement to an already-live profile is different: RPC keeps serving the previous revision while the replacement activates. A chain whose providers are all still verifying keeps its previously verified configuration, settings included, until a later identity check verifies one. A chain with both verified and verifying providers publishes the verified subset and its new settings immediately. Only a new chain with no previously verified configuration returns a retryable 503 (profile_config_unavailable) until a provider verifies; other chains on the same profile keep serving.

Head tracking

Lasso tracks each provider’s block height from the requests routed through it and a light background poll. Choose a mode per provider:

`heads`	Behavior	Use it for
`passive` (default)	Traffic plus a light poll	Most providers
`live`	A `newHeads` feed, updated every block	The provider you most want tracked closely
`standby`	Opens a feed only when the chain has no healthy `live` feed	A backup for `live`
`off`	No periodic head checks	Providers that bill per request

Head modes don’t change which providers serve client subscriptions. Omitting heads when you replace the document resets it to passive.

Lasso learns your providers

You supply URLs and intent. Lasso works out the rest from health checks and live traffic: historical depth per method, methods a provider refuses, its eth_getLogs span limit, whether it’s exhausting a quota, and whether its plan refuses the chain outright. GET /api/v1/profiles/{slug} shows that knowledge for each provider, with its source, configured mode and effect:

{"name": "my-node", "status": "verified", "knowledge": {
  "methods_refused": [{"method": "debug_traceTransaction", "source": "learned", "configured_mode": "on", "effect": "on", "suspended": false}],
  "logs_span": {"blocks": 10000, "source": "probe", "configured_mode": "on", "effect": "on", "suspended": false},
  "quota_exhaustion": {"value": true, "source": "learned", "configured_mode": "on", "effect": "excluded", "suspended": false},
  "capability_refusal": {"value": true, "source": "learned", "configured_mode": "on", "effect": "excluded", "suspended": false}
}}

configured_mode is the profile’s setting for that kind of knowledge: off, shadow (Lasso observes without acting), or on (changes routing). effect is what’s applied right now: it matches configured_mode, or reports suspended while you’ve paused that hint; suspended mirrors the same state as a boolean. Learned historical depth, method refusals, eth_getLogs span limits, quota exhaustion and chain-plan refusal are on by default. Matching method, depth and span limits move a provider behind alternatives. Quota exhaustion and chain-plan refusal (capability_refusal) instead report effect: "excluded" while they skip the affected credential until revalidation succeeds. Both behaviors keep one last route when every candidate is excluded. Declare limits only for what you know better than Lasso; declared limits outrank learned ones. How Lasso learns your providers explains how learning works and stays correct. To correct what Lasso learned, call DELETE /api/v1/profiles/{slug}/providers/{name}/knowledge, or use the dashboard’s Learned behavior panel: select a node to see its HTTP and WebSocket evidence, Reset knowledge for one transport, or Suspend 1h to pause one hint. Set a provider’s background_observations: false to stop all background checks and idle recovery on it.

Block protection

Set "block_protection": true on a chain, and sequential latest-block requests (eth_blockNumber, eth_getBlockByNumber("latest")) never return a lower height on the same Lasso server. The behavior, scope and errors are on block regression protection. To read several values at one block, use read at one block instead; it works without protection.

Workload recipes

Workload	Profile	URL strategy
User-facing reads	Two or more providers; `block_protection: true`	`balanced-fast`
Latency-critical trading	Fast providers first; `block_protection: true`; `max_lag_blocks: 1`	`fastest`
Indexer or backfill	Include an archive-capable provider	`load-balanced`
Transaction submission	Preferred broadcast provider first	`priority`
Subscriptions	`ws_url` on at least two providers	Any

Other operations

Call	Result
`GET /api/v1/profiles`, `GET /api/v1/profiles/{slug}`	Document, revision, provider status and knowledge; URLs and header values are never returned
`GET /api/v1/profiles/{slug}` with `Accept: application/yaml`	A Lasso RPC Core YAML file with secrets replaced by environment references. Core has no `standby` mode, so a profile using it returns 422 `invalid_config`
`DELETE /api/v1/profiles/{slug}`	Removes the profile; URLs naming it serve as `premium` with `x-lasso-fallback: profile`

Limits

Holding a Custom profile needs Custom access; a dry run doesn’t. An account that has never had Custom access gets five free days on its first saved profile; provisional accounts can also buy Custom access with a wallet. See trial your own providers.
An account holds up to five Custom profiles.
If Custom access lapses, the profile is kept and its URLs are served as premium until you renew. Open WebSocket connections on it close with custom_access_expired.
block_protection holds per Lasso server.
Onboarding checks chain identity only. Test your exact archive queries through the profile.

Trial your own providers: build and test a profile before anyone signs up.
Keys, URLs and profiles: select the profile in the URL and scope keys to it.
Profiles in RPC Core: the engine’s profile model, for self-hosting.

Get started

Concepts

Guides

Reference

Updates

Custom profiles

Custom profiles

The document

Onboarding: what Lasso checks

Head tracking

Lasso learns your providers

Block protection

Workload recipes

Other operations

Limits

Next

​Custom profiles

​The document

​Onboarding: what Lasso checks

​Head tracking

​Lasso learns your providers

​Block protection

​Workload recipes

​Other operations

​Limits

​Next

Custom profiles

The document

Onboarding: what Lasso checks

Head tracking

Lasso learns your providers

Block protection

Workload recipes

Other operations

Limits

Next