Sonar API for your own scripts and agents.

Pull the same dealer positioning maps you see in Sonar into your code: spot, gamma flip, call and put walls, the king strike, and net GEX by strike.

The API is read-only. Every route is a GET that returns JSON with a timestamp, so you always know how fresh a number is. It serves finished map outputs only, the same values the Sonar app shows.

Who can use it. API access is part of the Sonar Max plan. Max members create keys in Sonar under Settings, API keys. Accounts without API access see a short note there instead. See pricing for plans.

Quickstart

You need a Sonar Max account and a terminal with curl.

  1. Create a key

    In Sonar, open Settings, then API keys, and choose New key. Give it a name, pick the Maps scope, set how long it lasts, and accept the API terms. The key is shown once, so copy it somewhere safe.

  2. Save it as an environment variable

    ShellExample key
    export SONAR_KEY="ut_live_XXXXXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  3. Ask for SPX levels

    curl
    curl https://api.sonar.rippll.ai/v1/levels/SPX \
      -H "Authorization: Bearer $SONAR_KEY"
  4. Read the response

    Every answer comes in the same wrapper. Your numbers sit in data, and as_of and stale tell you how fresh they are.

    200 OKExample values
    {
      "data": {
        "symbol": "SPX",
        "spot": 6842.15,
        "flip": 6810,
        "call_wall": { "strike": 6900, "net_gex": 2.41e9 },
        "put_wall": { "strike": 6750, "net_gex": -1.87e9 },
        "king": { "strike": 6850, "expiry": "2026-11-16", "net_gex": 3.12e9 },
        "total_gex": 8.6e9,
        "top_strikes": [ { "strike": 6850, "net_gex": 3.12e9 } /* …up to 10 */ ]
      },
      "as_of": "2026-11-16T10:31:02-05:00",
      "stale": false,
      "lag_s": 1,
      "api_version": "1"
    }

Authentication

Send your key in the Authorization header as a bearer token. That is the only place a key is accepted.

Header
Authorization: Bearer ut_live_…
  • Keys start with ut_live_. That prefix makes them easy to spot if one ends up in a repo or a log.
  • A key in the URL query string is refused with key_in_url, so it never lands in server logs or browser history.
  • The API has no CORS. Call it from a server, a script or an agent, never from a public web page.
  • Revoking a key in Settings takes effect on your very next request.

Key rules

RuleValue
Active keysUp to 3 per account
New keysUp to 10 created per account in any 30 days
Lifetime90 days by default, up to 365 days
NameUp to 40 characters
Scopesread:maps covers every route below. /v1/usage works with any scope.
VisibilityShown once when created. It can't be shown again, only revoked and replaced.

Rate limits

Limits are counted per account, so every key on your account shares one budget. Making more keys does not raise them.

LimitSonar Max
Burst20 requests
Sustained300 requests per minute
Daily50,000 requests
In flight at once4 requests

Each response carries your remaining budget in the RateLimit-Policy and RateLimit headers. A 429 or 503 also carries Retry-After in seconds; wait that long before trying again.

Response headersExample values
RateLimit-Policy: "burst";q=20;w=60, "day";q=50000;w=86400
RateLimit: "burst";r=17;t=42, "day";r=48211;t=50310
Back off on 429. An account that keeps sending requests after being told to wait (over 100 rejected in 5 minutes) is paused for 15 minutes.

Data routes send an ETag. Send it back as If-None-Match and you get a short 304 when nothing changed. A 304 still counts as a request.

Endpoints

Base URL https://api.sonar.rippll.ai/v1. Every route is GET, takes no body, and rejects parameters it doesn't know with 400 bad_request. Symbols are upper case, like SPX or AAPL.

GEX values are in USD and keep the precision Sonar shows: three significant figures for GEX, two decimals for prices.

List symbols

GET/v1/symbols
Scope read:mapsNo parameters

Every ticker Sonar maps, whether your plan can read it, and how fresh it is. Use it as the live list of what you can ask for.

Fields

FieldMeaning
symbols[].symbolTicker, for example NVDA
symbols[].accesstrue when your plan can read it
symbols[].staletrue when the map hasn't updated recently
symbols[].as_ofTime of the last update
curl
curl https://api.sonar.rippll.ai/v1/symbols \
  -H "Authorization: Bearer $SONAR_KEY"
200 OKExample values, shortened
{
  "data": {
    "symbols": [
      { "symbol": "SPX", "access": true, "stale": false, "as_of": "2026-11-16T10:31:01-05:00" },
      { "symbol": "NVDA", "access": true, "stale": false, "as_of": "2026-11-16T10:30:58-05:00" }
    ]
  },
  "as_of": "2026-11-16T10:31:02-05:00", "stale": false, "lag_s": 0, "api_version": "1"
}

Key levels

GET/v1/levels/{sym}
Scope read:maps

The levels traders watch most: spot, gamma flip, call wall, put wall, the king strike, total GEX, and the 10 strikes with the largest net GEX by size.

Parameters

NameInDescription
symrequiredpathA covered ticker, 1 to 6 capital letters

Fields

FieldMeaning
spotLast price of the underlying
flipPrice where total gamma changes sign. null for Books tickers.
call_wall, put_wall{strike, net_gex} or null
kingStrike with the largest net GEX: {strike, expiry, net_gex}
total_gexNet GEX summed across strikes
top_strikes[]Up to 10 {strike, net_gex}, largest first
curl
curl https://api.sonar.rippll.ai/v1/levels/NVDA \
  -H "Authorization: Bearer $SONAR_KEY"

The response looks like the one in the Quickstart.

GEX by strike

GET/v1/gex/{sym}?kind=&expiry=&around=
Scope read:maps

Net gamma or vanna for each strike near spot, for one expiry. This is one column of the Sonar heatmap.

Parameters

NameInDescription
symrequiredpathA covered ticker
kindoptionalquerygamma (default) or vanna
expiryoptionalqueryYYYY-MM-DD, one of the live expiries listed in expiries. Defaults to the nearest.
aroundoptionalqueryStrikes on each side of spot, 5 to 40. Default 20.
curl
curl "https://api.sonar.rippll.ai/v1/gex/SPY?kind=gamma&around=10" \
  -H "Authorization: Bearer $SONAR_KEY"
200 OKExample values, shortened
{
  "data": {
    "symbol": "SPY",
    "kind": "gamma",
    "expiry": "2026-11-16",
    "expiries": ["2026-11-16", "2026-11-17", "2026-11-18"],
    "spot": 682.4,
    "strikes": [
      { "strike": 680, "value": -4.12e8 },
      { "strike": 681, "value": 1.05e8 },
      { "strike": 682, "value": 6.73e8 }
    ]
  },
  "as_of": "2026-11-16T10:31:02-05:00", "stale": false, "lag_s": 1, "api_version": "1"
}

An expiry that isn't live answers 400 bad_request with the message expiry not live.

Profile

GET/v1/profile/{sym}?around=
Scope read:maps

The shape of dealer exposure around spot. Check basis to see which kind you got.

  • strike_total: net GEX per strike across every live expiry. Points are {strike, net_gex} and flip is null. This is what Books tickers return today.
  • spot_sweep: total GEX if spot moved to each price. Points are {price, total_gex}.

Parameters

NameInDescription
symrequiredpathA covered ticker
aroundoptionalqueryStrikes on each side of spot, 5 to 40. Default 20.
curl
curl "https://api.sonar.rippll.ai/v1/profile/QQQ?around=15" \
  -H "Authorization: Bearer $SONAR_KEY"
200 OKExample values, shortened
{
  "data": {
    "symbol": "QQQ",
    "spot": 611.85,
    "flip": null,
    "basis": "strike_total",
    "points": [
      { "strike": 610, "net_gex": 9.4e8 },
      { "strike": 612, "net_gex": 3.1e8 }
    ]
  },
  "as_of": "2026-11-16T10:31:02-05:00", "stale": false, "lag_s": 1, "api_version": "1"
}

Usage

GET/v1/usage
Any scopeNo parameters

Your own plan limits and how much of today's quota is left.

FieldMeaning
tierLimit tier on your account
dayThe quota day being counted
requests, quota, remainingUsed today, daily allowance, what's left
resets_atWhen the daily count resets
per_min, burst, inflightYour per-minute, burst and concurrency limits
curl
curl https://api.sonar.rippll.ai/v1/usage \
  -H "Authorization: Bearer $SONAR_KEY"
200 OKExample values
{
  "data": {
    "tier": "pro", "day": "2026-11-16",
    "requests": 1789, "quota": 50000, "remaining": 48211,
    "resets_at": "2026-11-17T00:00:00Z",
    "per_min": 300, "burst": 20, "inflight": 4
  },
  "as_of": "2026-11-16T10:31:02-05:00", "stale": false, "lag_s": 0, "api_version": "1"
}

Errors

Errors share one shape. retry_after_s appears on 429 and 503 and matches the Retry-After header.

429 Too Many RequestsExample
{ "error": { "code": "rate_limited", "message": "Request limit reached", "retry_after_s": 10 } }
StatusCodeWhat it means
400bad_requestUnknown or repeated parameter, or a value out of range. Unknown paths answer 404, other methods than GET 405.
400key_in_urlA key was found in the query string. Use the header.
401unauthorizedMissing, malformed or unknown key
401key_revokedThe key was revoked or expired, or the account can't use the API
403forbidden_scopeThe key doesn't carry the scope this route needs
404not_coveredSonar doesn't map this symbol. Uncovered lookups aren't charged.
429rate_limitedBurst or per-minute limit reached. Wait Retry-After.
429quota_exhaustedDaily quota used up
429pausedAccount paused for 15 minutes after ignoring 429s
503upstream_degradedData is briefly unavailable. Retry after the delay.
503api_disabledThe API is switched off for maintenance

Tickers covered

Max keys can read all 262 tickers Sonar maps. The chips below are a sample, not the full list: the three dark ones are the index maps and the rest are Books, which cover all live expiries. Call /v1/symbols for the current list, since tickers are added and swapped over time.

Changelog

API access opens to Sonar Max members.

Version 1: symbols, levels, gex, profile and usage routes.

Breaking changes ship under a new version path, and /v1 stays up for at least six months after.