Lowcap Connector

Lowcap Connector provides real-time and on-demand USD prices for low-cap tokens across EVM chains.

Use the API to:

• request token-level USD prices;
• inspect pool-level quotes and recent events;
• discover supported chains, tokens, and pools;
• consume live price, swap, and feed-health updates over WebSocket.

The public API base URL is:

https://lowcapsxyz.com

API requests require an operator-issued credential. This documentation site is public and does not require authentication.

Getting started

Authentication

Send an operator-issued API key as a bearer token:

Authorization: Bearer <your-api-key>

Never put a key in a URL. Browser clients may exchange a bearer credential through POST /v1/session; the response sets a secure, HTTP-only, same-origin session cookie for later API requests and WebSocket handshakes.

Keys are issued by the service operator. Contact the operator to request access; there is no self-service signup.

List supported chains

curl --fail-with-body \
  -H 'Authorization: Bearer <your-api-key>' \
  'https://lowcapsxyz.com/v1/chains'

Request a token quote

Replace the chain ID and token address with the asset you need:

curl --fail-with-body \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Accept: application/json' \
  'https://lowcapsxyz.com/v1/quote/token/8453/0x1111111111111111111111111111111111111111'

See Errors and response states before treating a successful HTTP response as a priced result.

API overview

All paths below are relative to https://lowcapsxyz.com.

For schemas, parameters, and executable requests, open the interactive OpenAPI reference.

Chains, tokens, and search

Pools and events

Quotes

Health

Session

POST /v1/session requires authentication (a bearer token, or an existing session cookie) and has no request body. Its optional query parameters select a chain and a snapshot boundary.

Admin endpoints also exist. They are allowlist-gated and are covered only in the interactive OpenAPI reference.

WebSocket streaming

Connect to:

wss://lowcapsxyz.com/v1/stream

Authenticate the WebSocket handshake with either Authorization: Bearer <your-api-key> or a valid same-origin session cookie. Then send exactly one JSON subscribe frame.

Subscribe

{
  "filter": {
    "chain_ids": [8453],
    "pool_ids": [
      "0x1111111111111111111111111111111111111111111111111111111111111111"
    ],
    "token_ids": [
      "0x2222222222222222222222222222222222222222222222222222222222222222"
    ]
  },
  "resume_cursor": null
}

Filter arrays must be strictly sorted and unique. Empty pool_ids and token_ids arrays select every routed message for the chosen chains. A null cursor starts live-only delivery.

Message envelope

Durable messages share this envelope:

{
  "stream_sequence": 10842,
  "routing": {
    "chain_id": 8453,
    "pool_ids": [],
    "token_ids": []
  },
  "type": "PRICE_UPSERT",
  "payload": {}
}

stream_sequence is monotonic, not necessarily contiguous. Use it for ordering and recovery. Message types are:

RESET_REQUIRED is a control message and has no stream_sequence.

Resume and replay

For snapshot-plus-delta consumption:

1. Read every page of GET /v1/pools and retain the minimum snapshot_sequence returned across the pages.

2. Create a cursor after that boundary:

   curl --fail-with-body -X POST \
     -H 'Authorization: Bearer <your-api-key>' \
     'https://lowcapsxyz.com/v1/session?chain_id=8453&snapshot_sequence=<snapshot-sequence>'
   

3. Reconnect and send the returned resume_cursor in the subscribe frame.

4. Apply replayed records, then continue with live records. Ignore overlap at or below the last applied sequence.

The current session cursor is chain-wide. A narrower pool or token filter with that cursor causes RESET_REQUIRED with FILTER_MISMATCH. For resumable delivery, subscribe chain-wide and filter locally.

Heartbeats and slow consumers

The server sends a WebSocket ping every 30 seconds and expects a pong before the next heartbeat. It also responds to client pings.

If a slow consumer falls behind, the connection closes with code 1013 and identifies the last delivered sequence. Create a new session cursor after that sequence and reconnect. If replay is no longer available, discard local state and take a fresh snapshot.

RESET_REQUIRED

{
  "type": "RESET_REQUIRED",
  "payload": {
    "reason": "REPLAY_UNAVAILABLE",
    "server_time_unix_ms": 1784217600000
  }
}

Possible reasons are INVALID_CURSOR, EXPIRED_CURSOR, FILTER_MISMATCH, REPLAY_UNAVAILABLE, and SCHEMA_MISMATCH.

On receipt:

1. stop applying stream messages;
2. discard state whose consistency depends on the rejected cursor;
3. fetch a fresh pool snapshot;
4. create a new cursor at that snapshot boundary;
5. reconnect chain-wide.

Errors and response states

Generic errors

Non-quote application errors use:

{
  "error": "message"
}

Quote errors

Quote failures use a structured body. detail may be null.

{
  "code": "NO_ROUTE",
  "message": "no route",
  "detail": "NO_QUALIFIED_ROUTE_WITHIN_HOP_LIMIT"
}

The following code strings map to HTTP status codes:

Authentication and authorization

• 401 Unauthorized: the credential is missing, invalid, expired, or revoked. The response body is empty and includes WWW-Authenticate: Bearer.
• 403 Forbidden: the credential is valid but the consumer is not allowed to use the requested endpoint. The response body is empty.

Rate limiting

429 Too Many Requests has an empty body. The numeric Retry-After header gives the number of seconds to wait before retrying. Rate limiting is isolated per consumer; requests made with a session cookie use the same bucket as the bearer credential that created it.

Token-quote response states

GET /v1/quote/token/{chain_id}/{token_address} may return a non-error response without a price:

A 202 response means work is pending. A 200 UNPRICED response is a completed evaluation with no usable price at that time.

Chains and deployments

These tables record public EVM chain identities and on-chain deployment facts verified on 2026-07-17.

Chain identity

Factory deployments

The BNB Smart Chain deployment is admitted through the compatible V2 pair ABI. V3 compatibility is not assumed.

Known pool contracts

Event-topic hashes

Routing confidence

Routing computes an exact token/USD value and a confidence score from chain-local pool evidence. Confidence is a weakest-link score, not a probability or permission to trade.

Invariants

1. Graph operations are chain-local; asset identity is (chain_id, opaque asset_id).
2. Authoritative prices are positive reduced rationals. Zero, NaN, infinity, and binary floats are invalid.
3. A physical pool contributes capacity at most once.
4. Path depth and confidence use weakest-link values.
5. External coverage data may lower or cap confidence; it cannot create or delete an on-chain price.
6. Routes expire without events. Every score exposes its components and active caps.

Exact price composition

q(X→Y) = (a × 10^dX) / (b × 10^dY)

Q(S/X₀) = (∏aᵢ × 10^dX₀) / (∏bᵢ × 10^dS)

P_USD(X₀) = Q(S/X₀) × U_S

a/b is the oriented atomic execution ratio. Reverse orientation is the exact reciprocal of observed evidence, not a reverse executable quote. Token decimals must be verified. U_S is an exact guarded stable/USD ratio.

Arithmetic cross-cancels by greatest common divisor, supports 4,096 bits per side, persists decimal strings, and rounds only the final display value to 18 significant digits using ties-to-even.

Common 2% depth

D↑ = USD input required to raise oriented marginal price by 2%
D↓ = USD input required to lower oriented marginal price by 2%
L  = min(D↑, D↓)
L_eff = min(L_current, EWMA_30m(L))

Adapters simulate protocol-exact integer swaps and choose the greatest consumed gross input still within the boundary. Depth rounds down to microdollars. TVL, reserves, and active liquidity are diagnostics, not substitutes for the simulation. Incomplete state makes depth UNKNOWN.

Weighted median and outlier rejection

Sort prices before applying the weighted median:

weighted median: first k where 2 × Σ(i≤k) wᵢ ≥ Σwᵢ

dev_bps(p,q) = 10000 × (max(p/q, q/p) - 1)
MADw = weighted_median(dev_bps(pᵢ,m₀), Lᵢ_eff)
τ = clamp(ceil((22239/5000) × MADw), 200, 1000) bps

Outlier rejection is one-pass. Proposed outliers are removed only when survivors retain at least 67% of the weight and span at least two independent pools and deployments. Otherwise all observations remain, NO_INDEPENDENT_CONSENSUS applies, and confidence is capped at 2.

Shared edges are capacity-limited:

b_r = min edge capacity on route r
B_e = Σ b_r for routes using edge e
w_r = floor_microUSD(b_r × min_e(min(1, L_e/B_e)))

Invariant: Σ(r using e) w_r ≤ L_e

The published value is the selected weighted-median path’s exact rational. The support envelope spans accepted inlier prices; it is diagnostic, not a calibrated probability interval.

Confidence algebra

S_edge = min(S_depth, S_fresh, S_agreement, S_temporal,
             S_feed, S_state, S_stable?)
S_anchor = min(S_edge, S_coverage)
S_route = min(all edge scores, routing-asset score)
S_published = min(S_path_agreement, material route scores,
                  S_aggregate_state)

State and ordering

• Recompute on price, liquidity, retraction, health, finality, timer, policy, and external-anchor changes.
• PRICE_RETRACT recomputes from final post-reorganization state; it is not a blind tombstone.
• Sequence causal pool records before one coalesced token record.
• When no route survives, timer expiry retracts the price with ROUTE_EXPIRED.

No score authorizes liquidation. Independent flag-then-confirm policy remains mandatory, especially when one party controls most effective depth, the sole venue, the ingestion cursor, or the sole stable source.