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.
Quickstart
You need a Sonar Max account and a terminal with curl.
-
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.
-
Save it as an environment variable
ShellExample keyexport SONAR_KEY="ut_live_XXXXXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -
Ask for SPX levels
curlcurl https://api.sonar.rippll.ai/v1/levels/SPX \ -H "Authorization: Bearer $SONAR_KEY" -
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.
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
| Rule | Value |
|---|---|
| Active keys | Up to 3 per account |
| New keys | Up to 10 created per account in any 30 days |
| Lifetime | 90 days by default, up to 365 days |
| Name | Up to 40 characters |
| Scopes | read:maps covers every route below. /v1/usage works with any scope. |
| Visibility | Shown 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.
| Limit | Sonar Max |
|---|---|
| Burst | 20 requests |
| Sustained | 300 requests per minute |
| Daily | 50,000 requests |
| In flight at once | 4 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.
RateLimit-Policy: "burst";q=20;w=60, "day";q=50000;w=86400
RateLimit: "burst";r=17;t=42, "day";r=48211;t=50310Data 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
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
| Field | Meaning |
|---|---|
| symbols[].symbol | Ticker, for example NVDA |
| symbols[].access | true when your plan can read it |
| symbols[].stale | true when the map hasn't updated recently |
| symbols[].as_of | Time of the last update |
curl https://api.sonar.rippll.ai/v1/symbols \
-H "Authorization: Bearer $SONAR_KEY"{
"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
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
| Name | In | Description |
|---|---|---|
| symrequired | path | A covered ticker, 1 to 6 capital letters |
Fields
| Field | Meaning |
|---|---|
| spot | Last price of the underlying |
| flip | Price where total gamma changes sign. null for Books tickers. |
| call_wall, put_wall | {strike, net_gex} or null |
| king | Strike with the largest net GEX: {strike, expiry, net_gex} |
| total_gex | Net GEX summed across strikes |
| top_strikes[] | Up to 10 {strike, net_gex}, largest first |
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
Net gamma or vanna for each strike near spot, for one expiry. This is one column of the Sonar heatmap.
Parameters
| Name | In | Description |
|---|---|---|
| symrequired | path | A covered ticker |
| kindoptional | query | gamma (default) or vanna |
| expiryoptional | query | YYYY-MM-DD, one of the live expiries listed in expiries. Defaults to the nearest. |
| aroundoptional | query | Strikes on each side of spot, 5 to 40. Default 20. |
curl "https://api.sonar.rippll.ai/v1/gex/SPY?kind=gamma&around=10" \
-H "Authorization: Bearer $SONAR_KEY"{
"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
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
| Name | In | Description |
|---|---|---|
| symrequired | path | A covered ticker |
| aroundoptional | query | Strikes on each side of spot, 5 to 40. Default 20. |
curl "https://api.sonar.rippll.ai/v1/profile/QQQ?around=15" \
-H "Authorization: Bearer $SONAR_KEY"{
"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
Your own plan limits and how much of today's quota is left.
| Field | Meaning |
|---|---|
| tier | Limit tier on your account |
| day | The quota day being counted |
| requests, quota, remaining | Used today, daily allowance, what's left |
| resets_at | When the daily count resets |
| per_min, burst, inflight | Your per-minute, burst and concurrency limits |
curl https://api.sonar.rippll.ai/v1/usage \
-H "Authorization: Bearer $SONAR_KEY"{
"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.
{ "error": { "code": "rate_limited", "message": "Request limit reached", "retry_after_s": 10 } }| Status | Code | What it means |
|---|---|---|
| 400 | bad_request | Unknown or repeated parameter, or a value out of range. Unknown paths answer 404, other methods than GET 405. |
| 400 | key_in_url | A key was found in the query string. Use the header. |
| 401 | unauthorized | Missing, malformed or unknown key |
| 401 | key_revoked | The key was revoked or expired, or the account can't use the API |
| 403 | forbidden_scope | The key doesn't carry the scope this route needs |
| 404 | not_covered | Sonar doesn't map this symbol. Uncovered lookups aren't charged. |
| 429 | rate_limited | Burst or per-minute limit reached. Wait Retry-After. |
| 429 | quota_exhausted | Daily quota used up |
| 429 | paused | Account paused for 15 minutes after ignoring 429s |
| 503 | upstream_degraded | Data is briefly unavailable. Retry after the delay. |
| 503 | api_disabled | The 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.