API reference

One REST surface, 25 endpoints, one key. Every route is versioned under a single base URL, every collection paginates the same way, and every error is the same shape.

Base URL

https://api.hedg3.ai/v1

Pricing and plan limits are on the API overview. Keys are minted from your account settings once your subscription is active.

Authentication

Send your key as a bearer token. Keys are prefixed so a leaked one is identifiable on sight, stored only as a hash, and shown in plaintext once, at creation. There is no way to recover one afterwards. Mint a new key and revoke the old.

A query-string token is deliberately not supported: it ends up in browser history, proxy logs and referrer headers.

Header

Authorization: Bearer hg3_live_...

Revocation takes effect immediately because the authorizer caches nothing. Both market-data subscriber agreements are re-checked on every request, not only at mint, so a lapsed agreement stops the key rather than silently degrading it.

Response shape

Every data route returns rows under data and context under meta. The two introspection routes are the exception and return a bare object.

Envelope

{
  "data": [ /* rows */ ],
  "meta": {
    "dataset": "congress",
    "count": 50,
    "cursor": "1a2b3c4d.eyJrIjp7…",
    "hasMore": true,
    "asOf": "2026-10-19",
    "source": "…",
    "since": "2026-07-22",
    "sinceClamped": false,
    "reportingDelay": "…",
    "coverageNote": "…"
  }
}

meta.cursorSend it back to read the next page. null when no matching rows remain.

meta.hasMoretrue while matching rows remain. true with a null cursor means they lie past what one walk can serve: narrow since and until. With cursorUnavailable, it means a next page exists that this response could not hand out.

meta.cursorUnavailablePresent and true only when paging is briefly unavailable: the rows are served, cursor is null and hasMore is true. Retry the same request shortly for a cursor. Sending a cursor while paging is unavailable returns 503 api-unavailable.

meta.asOfThe newest date or timestamp the page's own rows carry, in that field's format. Never the fetch time. null when the rows carry none.

meta.sinceThe first date served, always YYYY-MM-DD.

meta.sinceClampedtrue when your since was raised to your tier's lookback floor.

meta.untilPresent when you sent one.

meta.session/data/plays and /data/unusual: the ET session served, YYYY-MM-DD.

meta.limit/data/plays and /data/unusual: the page size applied.

meta.limitClamped/data/plays and /data/unusual: true when your limit was above 50.

meta.source names the originating public source for the rows on that page.
meta.reportingDelay appears on the datasets that have a statutory one. It is stated rather than netted out. Rows are as-reported and are never back-dated.
meta.coverageNote appears where coverage is genuinely partial. A known gap is on the response, not left to be inferred from missing rows.

Pagination

Cursor-based. Pass the previous response's meta.cursor back as cursor. Walk until it is null.

A null cursor means the walk PROVED there is nothing more, not that this page came back short. A filtered page can legitimately return fewer rows than your limit and still hand you a live cursor. That is the correct behaviour, not an empty result.

A cursor is signed and bound to the route and query that minted it, so send it with the same parameters. The date window is part of the read's key, so a walk ends at the window's edge.

Walking a dataset

cursor=""
while true; do
  resp=$(curl -s -H "Authorization: Bearer hg3_live_..." \
    "https://api.hedg3.ai/v1/data/insiders?limit=500&cursor=$cursor")
  echo "$resp" | jq -c '.data[]'
  cursor=$(echo "$resp" | jq -r '.meta.cursor // empty')
  [ -z "$cursor" ] && break
done

Rate limits

Two independent limits: a per-minute burst that protects the platform, and a daily allowance that is what you are buying. The burst is the same on every tier.

Tier	Per minute	Per day	Lookback
Basic	120	20,000	30 days
Advanced	120	50,000	90 days
Custom	120	Negotiated	Negotiated

Headers

RateLimit-PolicyYour quotas as policies: "burst";q=120;w=60 and, when the tier has a daily cap, "daily";q=…;w=86400.

RateLimitWhat is left in each window: "burst";r=…;t=… where r is requests remaining and t seconds until the window rolls.

Retry-After429 only. Seconds to wait before retrying; it takes precedence over RateLimit.

X-RateLimit-LimitYour per-minute burst allowance.

X-RateLimit-RemainingRequests left in the current minute.

X-RateLimit-ResetUnix epoch at which the minute window rolls.

X-RateLimit-Limit-DayYour daily allowance.

X-RateLimit-Remaining-DayRequests left today.

These ride every response that reached the limiter, a 429 included. A 429 also carries Retry-After: wait that many seconds. A 401 or a scope 403 carries none of them. The minute window is fixed rather than sliding, so a burst spanning a boundary can briefly clear up to twice the limit.

/data/meta/usage reports your remaining daily allowance and is not itself charged against it.

Errors

RFC 9457 problem details, served as application/problem+json, with a requestId on every one. Quote it to support and we can find the exact request. Every type is https://hedg3.ai/errors/ plus a slug below.

Error

{
  "type": "https://hedg3.ai/errors/api-quota",
  "title": "Daily quota exceeded",
  "status": 429,
  "detail": "Daily limit of 50000 requests reached.",
  "requestId": "a1b2c3d4-…"
}

Types

api-unauthorized401The key is missing, unknown, revoked or expired.

api-scope403The key is valid but not scoped for this dataset, or your current plan does not include it.

api-quota429The daily allowance is spent.

api-rate-limit429The per-minute burst allowance is spent.

api-validation400A required parameter is missing, a value is outside its allowed set, or a date is not in the documented format.

api-invalid-cursor400The cursor is malformed or altered, or was minted for a different route or query.

api-not-found404The dataset is not currently served.

api-live-unavailable503/data/regime only: inside the options session, live positioning could not be served.

api-unavailable503A dependency the request needs is unavailable. Retry with backoff.

api-internal500An unexpected server error. Quote the requestId.

api-forbidden403The gateway refused the request before it reached a dataset.

api-route-not-found403No such route. A request that carries an Authorization header usually answers api-error 403 instead; read message to tell them apart.

api-throttled429The gateway's own throttle refused the request. Back off and retry.

api-error4xx / 5xxAny other gateway error. Quote the requestId.

One exception worth knowing before you write the handler: the gateway answers an authorizer rejection itself, so the body is NOT problem-details. That covers an unknown key, an inactive subscription and an outstanding agreement. Branch on the status first and parse the body second.

Public record

GET/data/congress

Congressional trading disclosures

Reported trades disclosed by sitting members, newest first.

Requires the read:congress scope.

Coverage is House-only today. That gap is stated in meta.coverageNote on every response rather than left for you to infer from missing rows.
meta.reportingDelay carries the statutory delay. Rows are as-reported and are not back-dated.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return, inclusive. Any other format returns 400. CLAMPED to your tier's floor rather than rejected; meta.sinceClamped is true when that happened.
untilstring (YYYY-MM-DD)default no upper bound: Latest date to return, inclusive. Must be on or after since, else 400.
symbolstring: Filter to one ticker. Upper-cased server-side.
memberstring: Exact member name. Case-sensitive.

Response fields

disclosedAtstringWhen the disclosure published.

transactionDatestringWhen the trade was made.

reportedAtstringFiling timestamp as reported.

symbolstringTicker, where the disclosure names one.

memberstringDisclosing member.

chamberstringChamber, where reported.

actionstringPurchase / sale / exchange, as reported.

amountRangestringThe disclosed value BAND. Disclosures report a range, not an amount.

transactionCountnumberTransactions folded into the row.

sourcestringOriginating public source for this row.

Test it outRecorded · 2026-08-15

limitcursorsinceuntilsymbolmember

GET https://api.hedg3.ai/v1/data/congress?limit=3&symbol=VSNT&member=Kevin%20Hern

Response

200 · 1 row

{
  "data": [
    {
      "action": "SALE",
      "amountRange": "$1,001 - $15,000",
      "chamber": null,
      "disclosedAt": "2026-08-12",
      "member": "Kevin Hern",
      "reportedAt": "2026-08-12",
      "source": "house_clerk",
      "symbol": "VSNT",
      "transactionCount": 1,
      "transactionDate": "2026-08-05"
    }
  ],
  "meta": {
    "dataset": "congress",
    "count": 1,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/insiders

Insider transactions

Open-market transactions by company insiders, newest first.

Requires the read:insiders scope.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return, inclusive. Any other format returns 400. CLAMPED to your tier's floor rather than rejected; meta.sinceClamped is true when that happened.
untilstring (YYYY-MM-DD)default no upper bound: Latest date to return, inclusive. Must be on or after since, else 400.
symbolstring: Filter to one ticker. A value that is not ticker-shaped (a filer typo such as GEF, GEF-B) is read by filter, so its walk can return short pages that still carry a cursor.

Response fields

datestringTransaction date as reported.

symbolstringTicker.

insiderstringReporting person.

titlestringTheir role at the issuer.

actionstringBuy / sell, as reported.

sharesnumberShare count.

pricePerSharenumberThe price REPORTED IN THE FILING. It is a public-record figure, not a market quote.

transactionCodestringThe filing's own transaction code.

cikstringIssuer identifier.

Test it outRecorded · 2026-08-15

limitcursorsinceuntilsymbol

GET https://api.hedg3.ai/v1/data/insiders?limit=3&symbol=ZETA

Response

200 · 1 row

{
  "data": [
    {
      "action": "Grant",
      "cik": "1865076",
      "date": "2026-08-14",
      "insider": "Ravella Satish",
      "pricePerShare": 0,
      "shares": 51696,
      "symbol": "ZETA",
      "title": "Chief Accounting Officer",
      "transactionCode": "G"
    }
  ],
  "meta": {
    "dataset": "insiders",
    "count": 1,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/institutions

Institutional filers

Which filers this API serves, and their CIKs.

Requires the read:institutions scope.

A curated set of managers, not every 13F filer. This is the list the two routes below accept. A CIK that is not here has no data to return.
Served from the registry rather than the store, so it costs no read and always matches what the detail route will accept.

Response fields

cikstringZero-padded CIK. Use it on the filer routes below.

namestringManager name.

Test it outRecorded · 2026-08-15

No parameters.

GET https://api.hedg3.ai/v1/data/institutions

Response

200 · 3 rows

{
  "data": [
    {
      "cik": "0001067983",
      "name": "Berkshire"
    },
    {
      "cik": "0001649339",
      "name": "Scion"
    },
    {
      "cik": "0001336528",
      "name": "Pershing Square"
    }
  ],
  "meta": {
    "dataset": "institutions-index",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/institutions/{cik}

Institutional filings

A manager's filed quarters, newest first.

Requires the read:institutions scope.

This route takes NO `since` and applies NO lookback clamp. A filing history is not a rolling window, so your tier's lookback does not truncate it.

Parameters

cikstringrequired: The manager's identifier.
limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.

Response fields

cikstringManager identifier.

managerstringManager name as filed.

quarterstringReporting quarter.

accessionstringFiling accession number.

positionCountnumberPositions in the filing.

Test it outRecorded · 2026-08-15

cikreqlimitcursor

GET https://api.hedg3.ai/v1/data/institutions/0001067983?limit=1

Response

200 · 1 row

{
  "data": [
    {
      "accession": "0001193125-26-226661",
      "cik": "0001067983",
      "manager": "Berkshire",
      "positionCount": 90,
      "quarter": "2026Q1"
    }
  ],
  "meta": {
    "dataset": "institutions",
    "count": 1,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/institutions/{cik}/holdings

Institutional holdings

The positions inside a manager's filings.

Requires the read:institutions scope.

Holdings are filed by CUSIP, not by ticker. A row carries the identifier the filing carried, so mapping it to a symbol is the caller's step.

Parameters

cikstringrequired: The manager's identifier.
limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
quarterstring: Exact quarter. Omit for every filed quarter.

Response fields

cusipstringSecurity identifier as filed.

issuerstringIssuer name as filed.

valueUsdnumberReported position value.

sharesnumberReported share count.

quarterstringReporting quarter.

Test it outRecorded · 2026-08-15

cikreqlimitcursorquarter

GET https://api.hedg3.ai/v1/data/institutions/0001067983/holdings?limit=3&quarter=2026Q1

Response

200 · 3 rows

{
  "data": [
    {
      "cusip": "H1467J104",
      "issuer": "CHUBB LTD SWITZ",
      "quarter": "2026Q1",
      "shares": 34249183,
      "valueUsd": 11162836215
    },
    {
      "cusip": "92343E102",
      "issuer": "VERISIGN INC",
      "quarter": "2026Q1",
      "shares": 8989880,
      "valueUsd": 2232726597
    },
    {
      "cusip": "829933100",
      "issuer": "SIRIUSXM HOLDINGS INC",
      "quarter": "2026Q1",
      "shares": 124807117,
      "valueUsd": 2880548260
    }
  ],
  "meta": {
    "dataset": "institution-holdings",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/ipos

IPO registrations

Registration filings in the pre-listing pipeline, newest first.

Requires the read:ipos scope.

This is a REGISTRATION feed, not a pricing calendar. There is no offer date, price range or syndicate. A registrant that has not priced has none of those, and the API does not invent them.
`symbol` is legitimately empty for pre-listing registrants.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return, inclusive. Any other format returns 400. CLAMPED to your tier's floor rather than rejected; meta.sinceClamped is true when that happened.
untilstring (YYYY-MM-DD)default no upper bound: Latest date to return, inclusive. Must be on or after since, else 400.

Response fields

symbolstringTicker, once one is assigned.

companystringRegistrant name.

cikstringRegistrant identifier.

filedAtstringFiling date. The since parameter filters on this.

formTypestringRegistration form type.

filingUrlstringLink to the filing itself.

Test it outRecorded · 2026-08-15

limitcursorsinceuntil

GET https://api.hedg3.ai/v1/data/ipos?limit=3

Response

200 · 3 rows

{
  "data": [
    {
      "cik": "0001580149",
      "company": "BIOVIE INC.",
      "filedAt": "2026-08-14",
      "filingUrl": "https://www.sec.gov/Archives/edgar/data/1580149/000152013826000350/0001520138-26-000350-index.htm",
      "formType": "S-1/A",
      "symbol": "BIVI"
    },
    {
      "cik": "0001649739",
      "company": "BayFirst Financial Corp.",
      "filedAt": "2026-08-13",
      "filingUrl": "https://www.sec.gov/Archives/edgar/data/1649739/000164973926000056/0001649739-26-000056-index.htm",
      "formType": "S-1",
      "symbol": "BAFN"
    },
    {
      "cik": "0002094710",
      "company": "ARC Group Securities Acquisition II",
      "filedAt": "2026-08-13",
      "filingUrl": "https://www.sec.gov/Archives/edgar/data/2094710/000149315226037855/0001493152-26-037855-index.htm",
      "formType": "S-1/A",
      "symbol": null
    }
  ],
  "meta": {
    "dataset": "ipos",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/shorts/{symbol}

Short data

Three distinct datasets behind one path: short interest, daily short volume, and fails to deliver.

Requires the read:shorts scope.

Short INTEREST and short VOLUME are different measurements and are routinely confused: interest is open positions at a settlement date, volume is one session's flow.
The fails dataset is published roughly a month in arrears. Its as-of date being weeks old is correct, not stale.
The fails file also carries a price column, which is deliberately not returned.

Parameters

symbolstringrequired: Ticker.
limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return, inclusive. Any other format returns 400. CLAMPED to your tier's floor rather than rejected; meta.sinceClamped is true when that happened.
untilstring (YYYY-MM-DD)default no upper bound: Latest date to return, inclusive. Must be on or after since, else 400.
datasetinterest | volume | failsdefault interest: Which dataset to return. An unrecognised value returns 400, never a silent fallback to the default.

Response fields

symbolstringTicker. Present on all three datasets.

settlementDatestringinterest, fails: the settlement date the row reports.

sessionstringvolume: the trading session. NOTE the date field differs per dataset.

shortSharesnumberinterest: shares reported short.

priorShortSharesnumberinterest: the prior period's figure.

periodChangeSharesnumberinterest: change since the prior period.

periodChangePercentnumberinterest: that change as a percent.

daysToCovernumberinterest.

avgDailyVolumenumberinterest.

shortVolumenumbervolume: shares sold short in the session.

shortExemptVolumenumbervolume.

totalVolumenumbervolume: the reporting file's own total, which is NOT consolidated volume.

shortVolumeRationumbervolume: derived. Null when it cannot be computed, never 0.

marketsstringvolume: the venues folded in.

quantityFailednumberfails: the failed quantity.

cusipstringfails.

descriptionstringfails.

Test it outRecorded · 2026-08-15

symbolreqlimitcursorsinceuntildataset

GET https://api.hedg3.ai/v1/data/shorts/AAPL?limit=3&dataset=volume

Response

200 · 3 rows

{
  "data": [
    {
      "markets": "B,Q,N",
      "session": "2026-08-14",
      "shortExemptVolume": 28481,
      "shortVolume": 3006663.211985,
      "shortVolumeRatio": 0.32931010024083074,
      "symbol": "AAPL",
      "totalVolume": 9130188.262632
    },
    {
      "markets": "B,Q,N",
      "session": "2026-08-13",
      "shortExemptVolume": 33782.75,
      "shortVolume": 4566073.74883,
      "shortVolumeRatio": 0.3594940037647683,
      "symbol": "AAPL",
      "totalVolume": 12701390.568444
    },
    {
      "markets": "B,Q,N",
      "session": "2026-08-12",
      "shortExemptVolume": 43970.5,
      "shortVolume": 5521379.994964,
      "shortVolumeRatio": 0.3867083540850395,
      "symbol": "AAPL",
      "totalVolume": 14277891.689275
    }
  ],
  "meta": {
    "dataset": "shorts",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/lobbying

Lobbying disclosures

Filed lobbying activity, newest first.

Requires the read:lobbying scope.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return, inclusive. Any other format returns 400. CLAMPED to your tier's floor rather than rejected; meta.sinceClamped is true when that happened.
untilstring (YYYY-MM-DD)default no upper bound: Latest date to return, inclusive. Must be on or after since, else 400.
clientstring: Exact client name.

Response fields

datestringFiling date.

clientstringClient as filed.

firmstringRegistrant as filed.

issuestringIssue area as filed.

amountUsdnumberReported amount.

symbolstringTicker, where the client maps to one. Frequently absent.

Test it outRecorded · 2026-08-15

limitcursorsinceuntilclient

GET https://api.hedg3.ai/v1/data/lobbying?limit=3&client=TITLE%20IV-A%20COALITION

Response

200 · 3 rows

{
  "data": [
    {
      "amountUsd": null,
      "client": "TITLE IV-A COALITION",
      "date": "2026-08-15",
      "firm": "ALLIED FOR PROGRESS",
      "issue": "Education",
      "symbol": null
    },
    {
      "amountUsd": null,
      "client": "NATIONAL SUMMER LEARNING ASSOCIATION",
      "date": "2026-08-15",
      "firm": "ALLIED FOR PROGRESS",
      "issue": "Education",
      "symbol": null
    },
    {
      "amountUsd": null,
      "client": "BUILD AMERICA'S SCHOOL INFRASTRUCTURE COALITION (BASIC)",
      "date": "2026-08-15",
      "firm": "ALLIED FOR PROGRESS",
      "issue": "Education",
      "symbol": null
    }
  ],
  "meta": {
    "dataset": "lobbying",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/contracts

Federal contract awards

Awarded federal contracts, newest first.

Requires the read:contracts scope.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return, inclusive. Any other format returns 400. CLAMPED to your tier's floor rather than rejected; meta.sinceClamped is true when that happened.
untilstring (YYYY-MM-DD)default no upper bound: Latest date to return, inclusive. Must be on or after since, else 400.
agencystring: Exact awarding agency name.

Response fields

datestringAward date.

agencystringAwarding agency.

contractorstringAwardee.

awardIdstringAward identifier.

amountUsdnumberAward amount.

symbolstringTicker, where the contractor maps to one. Frequently absent.

Test it outRecorded · 2026-08-15

limitcursorsinceuntilagency

GET https://api.hedg3.ai/v1/data/contracts?limit=3&agency=United%20States%20Chemical%20Safety%20Board

Response

200 · 3 rows

{
  "data": [
    {
      "agency": "United States Chemical Safety Board",
      "amountUsd": 18692.2,
      "awardId": "95315826F00009",
      "contractor": "INTEGRATION TECHNOLOGIES GROUP, INC.",
      "date": "2026-08-13",
      "symbol": null
    },
    {
      "agency": "United States Chemical Safety Board",
      "amountUsd": 291312,
      "awardId": "95315826F00007",
      "contractor": "ABBOTT MEDIA PRODUCTIONS LLC",
      "date": "2026-08-13",
      "symbol": null
    },
    {
      "agency": "U.S. Agency for Global Media",
      "amountUsd": 200000,
      "awardId": "95170026K0032",
      "contractor": "PAYDESK LIMITED",
      "date": "2026-08-13",
      "symbol": null
    }
  ],
  "meta": {
    "dataset": "contracts",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/economy/calendar

Economic calendar

Scheduled economic releases.

Requires the read:economy scope.

This is the ONE route sorted ASCENDING, because it is a forward calendar and oldest-first is the useful order.
There is no forecast or consensus field. It is not published on this feed, so it is not invented.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest date to return, inclusive. Any other format returns 400. CLAMPED to your tier's floor rather than rejected; meta.sinceClamped is true when that happened.
untilstring (YYYY-MM-DD)default no upper bound: Latest date to return, inclusive. Must be on or after since, else 400.

Response fields

namestringRelease name.

datestringScheduled date.

countrystringCountry code.

importancestringRelative importance as published.

actualnumberReported value, once released.

previousnumberThe prior period's value.

Test it outRecorded · 2026-08-15

limitcursorsinceuntil

GET https://api.hedg3.ai/v1/data/economy/calendar?limit=3

Response

200 · 3 rows

{
  "data": [
    {
      "actual": null,
      "country": "US",
      "date": "2026-12-31",
      "importance": 2,
      "name": "Initial Jobless Claims",
      "previous": 209000
    },
    {
      "actual": null,
      "country": "US",
      "date": "2026-12-24",
      "importance": 2,
      "name": "Initial Jobless Claims",
      "previous": 209000
    },
    {
      "actual": null,
      "country": "US",
      "date": "2026-12-23",
      "importance": 2,
      "name": "Housing Starts",
      "previous": 1427
    }
  ],
  "meta": {
    "dataset": "economy",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/sic/{symbol}

SIC classification history

Point-in-time industry classification, as filed with the SEC.

Requires the read:sic scope.

SIC, not GICS, and not a current sector label. It is what the filer told the SEC at filing date, so it lags reality and changes rarely.
That lag is the point for a point-in-time backtest: it is the classification a contemporaneous reader would have had. Every observation carries its own asOfDate so it is never read as current.
Source is the SEC Financial Statement Data Sets, taken direct from the SEC.

Parameters

symbolstringrequired: Ticker. Upper-cased server-side.

Response fields

symbolstringTicker.

cikstringFiler CIK.

observationsarrayEach entry carries asOfDate and the SIC recorded then.

Test it outRecorded · 2026-08-15

symbolreq

GET https://api.hedg3.ai/v1/data/sic/AAPL

Response

200 · 1 row

{
  "data": [
    {
      "cik": "320193",
      "observations": [
        {
          "asOfDate": "2025-01-31",
          "sic": "3571"
        }
      ],
      "symbol": "AAPL"
    }
  ],
  "meta": {
    "dataset": "sic",
    "count": 1,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

hedg3 output

GET/data/desk

Desk picks

Published picks from the automated desks, with their settled outcomes.

Requires the read:desk scope.

Pages across months. Walk meta.cursor until it is null; a short page can still carry a cursor.
realizedPct is the aggregate from the original entry across every leg. A pick that re-armed can read exitReason: stopped_out with a POSITIVE realizedPct: the final leg lost and the position still won. positionOutcome, legCount and finalLegRealizedPct make the pair legible, and reanchor.legs carries the per-leg detail. Scoring stopped_out as a loss will misread those picks.
A re-anchored pick is one position. Each pick counts once in a win rate, and it won when its realizedPct is above zero. This is the rule the published desk record uses.
reanchor.current is absent once a play is over. A finished pick reads closedOut: true and carries its leg history, never a working level.

Parameters

limitintegerdefault 100: Rows per page. Clamped to 1-500; a non-numeric value falls back to the default rather than erroring.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
sincestring (YYYY-MM-DD)default your tier's lookback floor: Earliest publish date (UTC), inclusive, clamped to your tier's lookback.
untilstring (YYYY-MM-DD)default no upper bound: Latest publish date (UTC), inclusive.
deskstring: Filter to one desk by its id, as served in each row's desk field (e.g. spread-shop).

Response fields

pickIdstringStable identifier.

deskstringPublishing desk.

publishedAtstringPublish timestamp.

symbolstringUnderlying.

strategystringStructure name.

rightstringcall | put, for the representative leg.

strikenumberRepresentative leg strike.

expirystringRepresentative leg expiry.

legsarrayEach leg: side, right, strike, expiry, quantity. Structure only. Per-leg pricing, greeks and open interest are not served on any route.

modeledEntrynumberThe modelled entry the pick was published at.

stopLossPctnumberStop, as a PERCENT of entry: 25 means 25%, and the level is entry * (1 - pct / 100). Not a fraction.

profitTargetsarrayTarget levels as published.

popnumber | nullModelled probability of profit at the pick's own exit, as a FRACTION: 0.5375 means 53.8%. At the time stop for a pick that closes before expiry, at expiration otherwise; popHorizon names which. Null when the figure cannot be computed.

popHorizonstringtime_stop or expiry: the horizon pop is measured at.

popHorizonAtstring | nullUTC ISO instant of that horizon: the time stop, or the expiry session close. Null when it cannot be placed.

modeledWinProbabilitynumber | nullDeprecated: the same value as pop under its old name. Removed after one release; read pop.

dteAtPublishnumberDays to expiry at publish.

termBandstring | nullshort, mid or long on a written-premium Income pick; null on every other desk.

statusstringactive, or a terminal outcome.

managedExitobject | nullThe price form of the bracket the percents above describe: entryPrice, takeProfitPrice, stopPrice, maxHoldSeconds. A level we cannot state transactably is absent rather than zero.

reanchorobject | nullPresent only on a pick that re-armed. legCount, rearmCount, closedOut, bankedTotal, published {entry, target, stop}, current {seq, entry, target, stop, pop, openedAt}, and legs[] with each leg's own realized and the running bankedAfter. The published bracket is served beside the current one, never instead of it.

outcomeobject | nullNull while active. Once settled: realizedPct, exitReason, resolvedAt, legCount, finalLegRealizedPct, positionOutcome. realizedPct is a FRACTION, so 1.0 means +100% and reading it as a percent under-reports by 100x. legCount is how many legs the position held: the initial position plus each re-anchor. positionOutcome is reanchored for a pick that re-armed, else the status.

Test it outRecorded · 2026-08-15

limitcursorsinceuntildesk

GET https://api.hedg3.ai/v1/data/desk?limit=3&desk=spread-shop

Response

200 · 3 rows

{
  "data": [
    {
      "desk": "spread-shop",
      "dteAtPublish": 15,
      "expiry": "2026-08-28",
      "legs": [
        {
          "expiry": "2026-08-28",
          "quantity": 1,
          "right": "put",
          "side": "buy",
          "strike": 34.5
        },
        {
          "expiry": "2026-08-28",
          "quantity": 1,
          "right": "put",
          "side": "sell",
          "strike": 35
        }
      ],
      "modeledEntry": 0.16,
      "modeledWinProbability": 0.6705,
      "outcome": null,
      "pickId": "01M00B1KBB9AAV6PGPMHYE4FK5",
      "profitTargets": [
        {
          "label": "1st",
          "pct": "15"
        }
      ],
      "publishedAt": "2026-08-14T14:30:16.056530+00:00",
      "right": "P",
      "status": "active",
      "stopLossPct": 10,
      "strategy": "bull-put-spread",
      "strike": 34.5,
      "symbol": "IBIT"
    },
    {
      "desk": "hedge-desk",
      "dteAtPublish": 29,
      "expiry": "2026-09-11",
      "legs": [
        {
          "expiry": "2026-09-11",
          "quantity": 1,
          "right": "stock",
          "side": "buy",
          "strike": 0
        },
        {
          "expiry": "2026-09-11",
          "quantity": 1,
          "right": "put",
          "side": "buy",
          "strike": 210
        }
      ],
      "modeledEntry": 228.805,
      "modeledWinProbability": 0.4271,
      "outcome": null,
      "pickId": "01M00B1CEPKM5KV6T2T02TGA3E",
      "profitTargets": [
        {
          "label": "1st",
          "pct": "9.17"
        }
      ],
      "publishedAt": "2026-08-14T14:30:16.056530+00:00",
      "right": "P",
      "status": "active",
      "stopLossPct": null,
      "strategy": "married-put",
      "strike": 210,
      "symbol": "NVDA"
    },
    {
      "desk": "vol-breakout",
      "dteAtPublish": 15,
      "expiry": "2026-08-28",
      "legs": [
        {
          "expiry": "2026-08-28",
          "quantity": 1,
          "right": "call",
          "side": "buy",
          "strike": 18
        },
        {
          "expiry": "2026-08-28",
          "quantity": 1,
          "right": "put",
          "side": "buy",
          "strike": 18
        }
      ],
      "modeledEntry": 1.365,
      "modeledWinProbability": 0.4256,
      "outcome": null,
      "pickId": "01M00B198HVMBD7HGNVJJ2H6KS",
      "profitTargets": [
        {
          "label": "1st",
          "pct": "50.18"
        }
      ],
      "publishedAt": "2026-08-14T14:30:16.056530+00:00",
      "right": "C",
      "status": "active",
      "stopLossPct": 50.18,
      "strategy": "long-straddle",
      "strike": 18,
      "symbol": "SOFI"
    }
  ],
  "meta": {
    "dataset": "desk",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/plays

Surfaced plays

The structures the ranking surfaced on a given session.

Requires the read:plays scope.

managedExit was documented as carrying fractions and a maxHoldDays. It carried neither: the block served null on every field until 2026-09-15, and a surfaced play has no time stop. The fields above are what it returns now.

Parameters

limitintegerdefault 50: Rows per page. Clamped to 1-50; meta.limitClamped is true when a larger value was cut to 50.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
dateYYYYMMDD or YYYY-MM-DDdefault the current ET session: An ET session date. Without it: today from the options open (09:30 ET) to midnight ET, after the close included; before the open, and on a weekend or market holiday, the most recent session. Any other format returns 400. A date before your tier's lookback is raised to the first session on or after it, with meta.sinceClamped true. meta.session states the session served.
symbolstring: Filter to one underlying. Rows then come back newest surfacedAt first.

Response fields

playIdstringStable identifier.

symbolstringUnderlying.

strategystringStructure name.

variantstringWhich board surfaced it.

legsarrayside, right, strike, expiry, quantity per leg.

expirationstringStructure expiry.

surfacedAtstringWhen it entered the board.

firstSurfacedAtstringFirst time it ever surfaced.

lastSeenAtstringMost recent appearance.

reSurfaceCountnumberHow many times it has re-entered.

modeledWinProbabilitynumberModelled probability of profit at expiration, frozen when the play surfaced, as a FRACTION: 0.5375 means 53.8%.

whySurfacedstringThe reason it cleared the board's rule.

statusstringLifecycle state.

managedExitobject | nulltakeProfitPct, stopLossPct and profitTargetsPct when the structure carries a modelled exit. All three are PERCENTS, on the same scale as the desk pick's stopLossPct: 48.99 means 48.99%.

Test it outRecorded · 2026-08-15

limitcursordatesymbol

GET https://api.hedg3.ai/v1/data/plays?limit=3&date=2026-08-12&symbol=CSCO

Response

200 · 1 row

{
  "data": [
    {
      "expiration": "2026-09-18",
      "firstSurfacedAt": "2026-08-15T05:30:06.683526+00:00",
      "lastSeenAt": null,
      "legs": [
        {
          "expiry": "2026-08-21",
          "quantity": 1,
          "right": "call",
          "side": "sell",
          "strike": 113
        },
        {
          "expiry": "2026-09-18",
          "quantity": 1,
          "right": "call",
          "side": "buy",
          "strike": 110
        }
      ],
      "managedExit": null,
      "modeledWinProbability": 0.9978,
      "playId": "fe90cf0b5dc964db",
      "reSurfaceCount": 0,
      "status": "open",
      "strategy": "call-diagonal",
      "surfacedAt": "2026-08-15T05:30:06.683526+00:00",
      "symbol": "CSCO",
      "variant": "base",
      "whySurfaced": null
    }
  ],
  "meta": {
    "dataset": "plays",
    "count": 1,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/regime

Positioning regime

The dealer-positioning regime label and its key strikes for one underlying.

Requires the read:regime scope.

Without `since` this returns exactly one row and meta.cursor: null.
Net gamma and spot are deliberately not served.
`maxPainStrike` is null rather than degraded when the settled row it needs does not exist.

Parameters

symbolstringrequired: REQUIRED. Omitting it returns 400. This route has no market-wide mode.
sincestring (YYYY-MM-DD): Switches to the dated archive. Omit for the latest single row. Any other format returns 400.
untilstring (YYYY-MM-DD): Archive mode only. Latest session, inclusive.
limitintegerdefault 100: Archive mode only.
cursorstring: Archive mode only.

Response fields

symbolstringUnderlying.

regimestringThe regime label.

zeroGammaStrikenumberThe flip level, when one is measurable in-band.

callWallStrikenumberHeaviest call-side strike.

putWallStrikenumberHeaviest put-side strike.

maxPainStrikenumberFrom the prior session's settled open interest, with its OWN vintage.

sessionDatestringSession the levels belong to.

asOfstringThe DATUM's own timestamp, never a fetch time.

resolutionstringintraday | closing | eod.

vintageobjectPer-section as-of: levels and maxPain each carry their own, because they can differ.

Test it outRecorded · 2026-08-15

symbolreqsinceuntillimitcursor

GET https://api.hedg3.ai/v1/data/regime?symbol=SPY&limit=1

Response

200 · 1 row

{
  "data": [
    {
      "asOf": "2026-08-15T05:30:06.683526+00:00",
      "callWallStrike": 780,
      "maxPainStrike": 775,
      "putWallStrike": 765,
      "regime": "long_gamma",
      "resolution": "eod",
      "sessionDate": "2026-08-14",
      "symbol": "SPY",
      "vintage": {
        "levels": {
          "asOf": "2026-08-15T05:30:06.683526+00:00",
          "resolution": "eod",
          "sessionDate": "2026-08-14"
        },
        "maxPain": {
          "asOf": "2026-08-15T05:30:06.683526+00:00",
          "resolution": "eod",
          "sessionDate": "2026-08-14"
        }
      },
      "zeroGammaStrike": 779.9
    }
  ],
  "meta": {
    "dataset": "regime",
    "count": 1,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

GET/data/unusual

Flagged unusual activity

Options activity that cleared the unusual-activity trigger on a session.

Requires the read:unusual scope.

There is no symbol filter on this route.
Premium is served as a band. The raw figure is never emitted.
Direction and action are INFERRED from where the print landed. No exchange publishes the side of an options trade.

Parameters

limitintegerdefault 50: Rows per page. Clamped to 1-50; meta.limitClamped is true when a larger value was cut to 50.
cursorstring: Opaque, signed page cursor from the previous response's meta.cursor. It is bound to the route and the query that minted it, so send the same parameters with it. A malformed or altered cursor, or one replayed on a different query, returns 400 api-invalid-cursor.
dateYYYYMMDD or YYYY-MM-DDdefault the current ET session: An ET session date. Without it: today from the options open (09:30 ET) to midnight ET, after the close included; before the open, and on a weekend or market holiday, the most recent session. Any other format returns 400. A date before your tier's lookback is raised to the first session on or after it, with meta.sinceClamped true. meta.session states the session served.

Response fields

eventIdstringStable identifier.

symbolstringUnderlying.

rightstringcall | put.

strikenumberStrike.

expirystringExpiry.

dtenumberDays to expiry at the flag.

directionstringInferred direction.

actionstringInferred aggressor action.

flowTypestringblock | sweep | split.

aggressorConfidencestringHow confidently the side was inferred.

premiumBandstringA BAND, not an amount: under-100k through over-10m, or null.

flaggedAtstringWhen it cleared the trigger.

Test it outRecorded · 2026-08-15

limitcursordate

GET https://api.hedg3.ai/v1/data/unusual?limit=3&date=2026-08-12

Response

200 · 3 rows

{
  "data": [
    {
      "action": "BUY",
      "aggressorConfidence": "HIGH",
      "direction": "BULLISH",
      "dte": 14,
      "eventId": "b5d523f889c942ed",
      "expiry": "2026-08-28",
      "flaggedAt": "2026-08-14T14:22:58.076247+00:00",
      "flowType": "BLOCK",
      "premiumBand": "5m-10m",
      "right": "C",
      "strike": 765,
      "symbol": "QQQ"
    },
    {
      "action": "BUY",
      "aggressorConfidence": "HIGH",
      "direction": "BEARISH",
      "dte": 14,
      "eventId": "287cf65995cc40ee",
      "expiry": "2026-08-28",
      "flaggedAt": "2026-08-14T14:01:00.797203+00:00",
      "flowType": "BLOCK",
      "premiumBand": "1m-5m",
      "right": "P",
      "strike": 175,
      "symbol": "WDAY"
    },
    {
      "action": "BUY",
      "aggressorConfidence": "HIGH",
      "direction": "BULLISH",
      "dte": 14,
      "eventId": "0b9fa9939fd146ba",
      "expiry": "2026-08-28",
      "flaggedAt": "2026-08-14T19:09:21.328208+00:00",
      "flowType": "BLOCK",
      "premiumBand": "1m-5m",
      "right": "C",
      "strike": 62,
      "symbol": "XLE"
    }
  ],
  "meta": {
    "dataset": "unusual",
    "count": 3,
    "cursor": null,
    "hasMore": false
  }
}

No request leaves your browser. These are real responses this endpoint has returned, recorded and filtered locally.

Trading

These routes are live. Placing an order is not yet enabled: order placement is being switched on broker by broker, and until it is, POST /trading/orders answers 503 with trading-execution-disabled. Everything else works, so an integration can be built and tested now.

GET/trading/brokers

Brokers

Every broker hedg3 supports, whether it can trade, and whether you have connected it.

Requires the trade scope.

Unavailable brokers are LISTED with their reason rather than hidden, so you learn why one is missing from your options instead of concluding hedg3 never heard of it.
Alpaca is the only broker with a paper environment that mirrors live order flow, so it is where an integration should be proven first.
Schwab requires you to re-authorize every 7 days. Its refresh token expires and cannot be renewed programmatically, so a connection left alone stops placing orders.

Response fields

brokerstringThe slug you pass on every other trading route.

namestringDisplay name.

availablebooleanWhether this broker can place a live order today.

unavailableReasonstring | nullWhy not, when available is false. Null otherwise.

paperSupportedbooleanWhether the broker has a paper or sandbox environment.

supportsNotionalbooleanWhether it accepts a dollar notional. When false, send a whole-share quantity.

connectedbooleanWhether you have authorized this broker on your hedg3 account.

Test it outRecorded · 2026-08-15

No parameters.

GET https://api.hedg3.ai/v1/trading/brokers

Response

200

{
  "data": [
    {
      "broker": "alpaca",
      "name": "Alpaca",
      "available": true,
      "paperSupported": true,
      "supportsNotional": true,
      "connected": true
    }
  ]
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

GET/trading/account

Account

Total value and buying power at the named broker.

Requires the trade scope.

A partial read is an error, never a zero. Both numbers size your orders, so hedg3 refuses rather than returning one of them.

Parameters

brokerstring: Which connected broker to read.

Response fields

brokerstringWhich broker answered.

accountValuenumberTotal account value.

buyingPowernumberAvailable buying power.

Test it outRecorded · 2026-08-15

broker

GET https://api.hedg3.ai/v1/trading/account?broker=alpaca

Response

200

{
  "data": {
    "broker": "alpaca",
    "accountValue": 104250.11,
    "buyingPower": 52125.05
  }
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

GET/trading/positions

Positions

What the account currently holds.

Requires the trade scope.

Quantity is signed. A short reads negative on every broker, including the ones whose own API reports an unsigned quantity with the direction in a separate field.

Parameters

brokerstring: Which connected broker to read.

Response fields

symbolstringUnderlying.

quantitynumberSIGNED: a short position is negative.

Test it outRecorded · 2026-08-15

broker

GET https://api.hedg3.ai/v1/trading/positions?broker=alpaca

Response

200

{
  "data": [
    {
      "symbol": "AAPL",
      "quantity": 25
    }
  ],
  "meta": {
    "broker": "alpaca"
  }
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

POST/trading/orders

Place an order

Submit one order to your connected brokerage.

Requires the trade scope.

clientToken is REQUIRED and must be unique per order. hedg3 never retries a placement: a retry after a lost response can double-fill, because the broker may have accepted the order and failed to answer. The token is what lets you reconcile instead of resubmitting.
A 202 means the order state is UNKNOWN and it may be live. The broker did not answer. Do NOT resend it: reconcile against your broker using your clientToken first. This is the one response you must not treat as a failure.
A 422 means the order was refused and does not exist: either your own risk limits blocked it (trading-blocked-by-guardrail) or the broker rejected it (trading-order-rejected). Both are safe to act on.
Every limit saved on your automations for this broker applies to a direct order, at its strictest. The limits object can only tighten them.
Size is checked at hedg3's own live quote, never a price you send. A market or stop order with no live quote answers 409 trading-quote-unavailable and is not sent. A limit buy is sized at its limit price and needs no quote.
Equity orders only. An option contract symbol answers 422 trading-instrument-unsupported.
A 503 with trading-execution-disabled means hedg3 is not transmitting live orders yet. This endpoint is behind the same platform-wide switch as every automation, so a kill that stops your rules stops this too.
A 403 with trading-not-in-rollout means transmission is on, but not yet for live orders on your account. A paper account is not held at this step.

Response fields

brokerstringREQUEST FIELD. Which connected broker to trade at.

symbolstringREQUEST FIELD. Underlying.

sidestringREQUEST FIELD. buy or sell.

quantitynumberREQUEST FIELD. Shares. Send this or notional, never both.

notionalnumberREQUEST FIELD. Dollar amount, where the broker supports it (check supportsNotional).

typestringREQUEST FIELD. market, limit, stop or stop_limit. Defaults to market.

limitPricenumberREQUEST FIELD. Required for limit and stop_limit.

stopPricenumberREQUEST FIELD. Required for stop and stop_limit.

timeInForcestringREQUEST FIELD. day or gtc. Defaults to day.

clientTokenstringREQUEST FIELD, REQUIRED. Your idempotency key. See the notes.

limitsobjectREQUEST FIELD. Extra limits for this order: maxPositionPct, maxPositionValue, reservePct, maxOpenPositions, minAccountBalance. They tighten your saved limits and never loosen them.

orderIdstringRESPONSE. The broker's order id.

statusstringRESPONSE. The broker's status for the new order.

Test it outRecorded · 2026-08-15

No parameters.

POST https://api.hedg3.ai/v1/trading/orders

Response

200

{
  "data": {
    "orderId": "9f2c…",
    "status": "accepted",
    "broker": "alpaca",
    "clientToken": "your-unique-id-1"
  }
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

GET/trading/orders

Order history

What hedg3 transmitted on your behalf, and what happened to it. Newest first, 50 per page.

Requires the trade scope.

This is hedg3's ledger, not a broker passthrough. It records what we did, including attempts that never reached a broker.
unknown_may_be_live means the transport failed and the order may exist. Reconcile against your broker; do not resubmit.
blocked_guardrail means your own risk limits refused it before anything was sent.
Walk the history by sending meta.cursor back until it is null.
A 503 with trading-pagination-unavailable means the cursor you sent could not be verified right now. Wait the Retry-After seconds and send it again. A page that cannot issue its next cursor still serves its rows, with meta.cursorUnavailable true.

Parameters

limitintegerdefault 50: Rows per page, 1 to 50. A larger value is served as 50 and meta.limitClamped is true. Anything other than a whole number returns 400 trading-invalid-query.
cursorstring: Opaque, signed cursor from the previous response's meta.cursor. It is bound to your account and to since and until, so send the same parameters with it. A malformed or altered cursor, or one minted for another account or window, returns 400 trading-invalid-cursor.
sincestring (YYYY-MM-DD)default no lower bound: Earliest UTC day to return, inclusive. Any other format returns 400 trading-invalid-query.
untilstring (YYYY-MM-DD)default no upper bound: Latest UTC day to return, inclusive. Must be on or after since, else 400.

Response fields

tradeIdstringhedg3's own identifier for the attempt.

symbolstringUnderlying.

sidestringbuy or sell.

statusstringSee the notes: this carries states a broker has no word for.

brokerOrderIdstring | nullThe broker's id, once one exists.

errorstring | nullWhy it did not transmit, when it did not.

clientTokenstring | nullThe clientToken you sent with POST /trading/orders. Null on an order an automation placed.

atnumberWhen hedg3 recorded the attempt, Unix epoch seconds.

updatedAtnumber | nullWhen hedg3 last recorded an outcome on this order, Unix epoch seconds. Null when none has been recorded since 2026-10-20.

meta.cursorstring | nullSend it back to read the next page. null when no rows remain, or when meta.cursorUnavailable is true.

meta.hasMorebooleantrue while rows remain, including when the cursor could not be issued.

meta.cursorUnavailablebooleanPresent and true only when rows remain but the next-page cursor could not be issued. Request the first page again shortly.

meta.limitnumberThe page size served.

meta.limitClampedbooleantrue when your limit was above 50 and was served as 50.

Test it outRecorded · 2026-08-15

limitcursorsinceuntil

GET https://api.hedg3.ai/v1/trading/orders?since=2026-10-01

Response

200

{
  "data": [
    {
      "tradeId": "AUTO_TRADE#…",
      "symbol": "AAPL",
      "side": "buy",
      "status": "accepted",
      "brokerOrderId": "9f2c…",
      "error": null,
      "clientToken": "your-unique-id-1",
      "at": 1760968800,
      "updatedAt": 1760968801
    }
  ],
  "meta": {
    "count": 50,
    "cursor": "1a2b3c4d.eyJrIjp7…",
    "hasMore": true,
    "limit": 50,
    "limitClamped": false,
    "since": "2026-10-01"
  }
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

GET/trading/automations

Automations

Your rules and whether each is running.

Requires the trade scope.

An automation triggers on neutral market data you compose: price, volume, technical indicators, volatility, schedules, and public calendar dates. It cannot trigger on a hedg3 verdict such as a desk pick, a score or a rank. That boundary is what keeps hedg3 a publisher rather than an adviser, and it is enforced when the rule is saved and again when it runs.

Response fields

idstringAutomation id.

namestringYour name for the rule.

statusstringactive, paused, stopped, draft or error.

brokerstringWhich broker it trades at.

Test it outRecorded · 2026-08-15

No parameters.

GET https://api.hedg3.ai/v1/trading/automations

Response

200

{
  "data": [
    {
      "id": "auto_…",
      "name": "Ride the trend",
      "status": "active",
      "broker": "alpaca"
    }
  ]
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

POST/trading/automations/{id}/stop

Stop an automation

Stop one rule.

Requires the trade scope.

Stopping is never blocked by your plan or your agreement. If those lapse you can still stop your own automations, because leaving a rule running for someone who may not trade would be the worse failure.
An id that is not one of your automations answers 404.

Parameters

idstring: Automation id.

Response fields

idstringThe automation stopped.

statusstringAlways stopped.

Test it outRecorded · 2026-08-15

idreq

POST https://api.hedg3.ai/v1/trading/automations/auto_123/stop

Response

200

{
  "data": {
    "id": "auto_123",
    "status": "stopped"
  }
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

POST/trading/kill

Kill switch

Stop every active automation you own, and disarm the session.

Requires the trade scope.

This can only ever STOP things, so it is never gated on your plan or agreement.
It stops new orders. An order already in flight at your broker is not recalled: cancel that at your broker.
The session is disarmed first, then each rule is stopped on its own. If any rule cannot be stopped, or the session cannot be disarmed, the call answers 500 with stopped, failed and disarmed in the body. Every step is safe to repeat, so retry the call.

Response fields

stoppedarrayThe automation ids stopped.

countnumberHow many.

disarmedbooleanAlways true: the armed session stops with the automations.

Test it outRecorded · 2026-08-15

No parameters.

POST https://api.hedg3.ai/v1/trading/kill

Response

200

{
  "data": {
    "stopped": [
      "auto_123"
    ],
    "count": 1,
    "disarmed": true
  }
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

Introspection

GET/data/meta/usage

Your usage

Tier, limits and what is left today.

This route is NOT charged against your daily quota, so a client can poll it to stay inside the limit without spending the limit.
This endpoint and /data/meta/datasets return a BARE object with no data/meta envelope.
current.remainingToday is null when the tier has no daily cap.

Response fields

tierstringYour key's tier.

limitsobjectrequestsPerMinute, requestsPerDay, lookbackDays.

currentobjectthisMinute, today, remainingToday.

scopesarrayThe scopes this key can use on your current plan, narrowed to the key's own subset when it was minted with one.

Test it outRecorded · 2026-08-15

No parameters.

GET https://api.hedg3.ai/v1/data/meta/usage

Response

200

{
  "tier": "advanced",
  "limits": {
    "requestsPerMinute": 120,
    "requestsPerDay": 50000,
    "lookbackDays": 90
  },
  "current": {
    "thisMinute": 3,
    "today": 412,
    "remainingToday": 49588
  },
  "scopes": [
    "read:insiders",
    "…"
  ]
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

GET/data/meta/datasets

Dataset catalogue

The public-record datasets and whether each is currently available.

The catalogue lists the nine public-record datasets AND the four hedg3-output ones. It listed only the public-record set until 2026-09-15, so a key holding read:desk was told by the catalogue that no such dataset exists.

Response fields

datasets[].namestringDataset key.

datasets[].scopestringThe scope a key needs.

datasets[].descriptionstringOne line.

datasets[].availablebooleanWhether this key can read it on your current plan.

Test it outRecorded · 2026-08-15

No parameters.

GET https://api.hedg3.ai/v1/data/meta/datasets

Response

200

{
  "datasets": [
    {
      "name": "congress",
      "scope": "read:congress",
      "description": "…",
      "available": true
    }
  ]
}

No request leaves your browser. Your parameters build the request line; the response is a recorded sample of this endpoint’s shape.

API access is licensed for use inside your own application and may not be redistributed or resold. The API returns general, non-personalized market data. See Disclosures for sourcing, latency and limitations.