GET/markets
markets:readRetained public contract metadata. Filter by venue and asset, paginate with offset and limit (1–100, default 100).
version · asOf · cache · markets[] · pagination.nextOffset
HummingbirdαFind opportunities. Make informed decisions.
Alpha
API documentation
Discover a route, calculate the cost of your intended amount, then send the evidence to your own decision and execution system.
- Base URL
https://humarb.com/api/v1- Format
- JSON · SSE
- Access
- Read-only · API Pro
1. Make your first request
Verify your email, activate Pro, then create an API key with markets:read and funding:read in your account. Keep it in a server-side environment variable.
Manage API keysRead routes[].routeId from the response. Use that ID in the cost calculation below; do not build IDs from exchange symbols.
The API supplies data and calculations. It does not place, cancel or reconcile exchange orders, receive exchange private keys, or move funds. Your system owns execution and recovery if only one leg fills.
cURL
curl "https://humarb.com/api/v1/opportunities?asset=BTC&size=10000&hours=24&limit=5" \
-H "Authorization: Bearer $HUMMINGBIRD_API_KEY"2. Authentication & allowance
| Item | Contract |
|---|---|
| Authorization | Bearer <HUMMINGBIRD_API_KEY> |
| Pro allowance | 10,000 requests / UTC day; 60 / minute, shared by all keys. |
| Execution calculations | 10 requests / minute; up to 5 routes per request; also consumes the total allowance. |
| Keys & scopes | Up to 2 active keys. markets:read for markets; funding:read for all other endpoints. |
| Response headers | X-RateLimit-Remaining-DayX-Execution-RateLimit-Remaining-Minute (calculation requests) |
API access requires a verified email and an active paid plan. Revoked keys or expired access stop working. No free API trial; web research remains free during Alpha. Never put a key in client-side code, a URL or a shared repository.
3. Markets & funding routes
GET
markets:readGET/opportunities
funding:read · up to 5 candidates per scanRecheck Hummingbird Engine-selected pairs using current public books, equal base quantity, all four entry/exit fees and your entered costs. Only fresh, calculable positive executionPlan.netUsd results are returned, sorted by that amount. Enter your actual four fees; defaults remain unconfirmed assumptions, and positive net is not a fill or profit guarantee.
routes[].executionPlan · engineSelections · scan.positive · scan.engineSelected · scan.nextOffset
An empty page can have more candidates: follow scan.nextOffset within quota. Offset indexes scanned candidates, not positive results. Arithmetic-only positive results without a recorded Hummingbird Engine choice are excluded, as are unknown, negative and stale plans. engineSelections is recorded-choice metadata and can include unsampled or now-negative pairs. currentCostsRevalidated is true only for matching fresh positive routes in this response. A changed client plan is recalculation, not new model analysis. Discovery shares the 10/minute calculation allowance with POST execution-plans.
GET/routes
funding:readRead the retained raw universe for research and diagnostics. Includes negative or unverified observations, with positive values ordered first within each freshness/comparability tier. These stored scenarios do not include new public-book calculations.
version · asOf · assumptions · routes[] · pagination · policy · executable: false
| Query parameter | Meaning / default |
|---|---|
| asset / search | Exact asset (BTC) / substring search; search takes precedence. |
| venues | Comma-separated venue IDs; both legs must be in the selected set. |
| type / category | all | cex | dex / all | crypto | commodity | equity | fx | unclassified |
| offset / limit | Raw routes: default 0 / 100, maximum 100 rows. Opportunities: default 0 / 5, maximum 5 scanned candidates. nextOffset=null ends this snapshot's queue. |
| size / hours | USD budget per leg / holding hours. Defaults: 10000 / 24. |
| feeBps | Default `official`: each leg's official regular-user (non-VIP) taker fee for its venue and market kind; routes return the charged fee and its source per fill in feeBasis. A number (bps, 1 bp = 0.01%) applies one rate to all four fills. |
| longEntryFeeBps / longExitFeeBps shortEntryFeeBps / shortExitFeeBps | Override each fee independently, including zero. These are entered assumptions, not verified account fees. |
| basisPnlUsd / otherCostsUsd | Entered basis P&L / other costs, both default 0. A zero default does not establish that the cost is absent. |
| sameSettlement | true disables the default stablecoin-parity assumption. |
Monetary amounts and rates are decimal strings. Raw route APR uses one leg’s notional; current executionPlan.netReturnPct uses total entered capital and is not annualized. Raw routes read retained data. Opportunities may refresh public books but never funding or Hummingbird Engine. Multiple pairs per asset are considered; a five-candidate scan is not whole-market coverage. To apply structured venue fee profiles or custom capital, recalculate returned IDs with POST execution-plans and recheck positivity.
4. Calculate the intended trade amount
POST/execution-plans
funding:read · Content-Type: application/json · 32 KiBUses the retained funding snapshot and cached or refreshed public books for the exact two contracts. No model call or exchange order is created. A missing or stale input remains explicit.
Response envelope: version=1, calculationVersion, requestedAt, completedAt, refreshAfterMs, modelInvoked=false and results[]. Each result has routeId, status, route, plan and reasonCodes. Check each item; HTTP 200 may contain unavailable results.
| Plan field | How to use it |
|---|---|
| status / calculationReady / validUntil | ready, partial or unavailable. A complete calculation does not confirm execution or fee eligibility. Stop using expired results. |
| position | Equal base quantity, per-leg notionals, fullBudgetCovered and capitalUsd. Insufficient returned depth can reduce quantity. |
| prices / depth | Four entry/exit VWAPs, observed round-trip P&L and each leg’s top/1% depth within the returned book window. |
| fees / costs | Entered fee profiles and entry + exit fees, transfers, capital and other costs. Maker fills and rebates may be conditional. |
| funding / breakEven | Each leg’s declared schedule, settlement events and first nonnegative scenario time. Continuous funding is marked separately. |
| netUsd / netReturnPct | Scenario net amount / return on position.capitalUsd for the holding window, not annualized. |
| convergenceScenario / stressScenarios | Separate common-price exit and adverse-exit scenarios, not certain losses or forecasts. |
| sourceTimes / reasonCodes / limitations | Keep the source times and qualifications with the displayed result or trading rule. |
Slippage is already reflected in VWAPs: do not deduct it again. Funding holds the observed rate constant; future exit books use the observed reference. Fee profiles can be supplied as options.feeProfiles; see the Skill reference for the full schema, maker/taker modes and rebate conditions.
JSON
{
"routeIds": [
"<routeId from GET /routes>"
],
"assumptions": {
"notionalUsd": "10000",
"holdingHours": "24",
"longEntryFeeBps": "5",
"longExitFeeBps": "5",
"shortEntryFeeBps": "5",
"shortExitFeeBps": "5"
},
"options": {
"costs": {
"transferUsd": "0",
"otherUsd": "0",
"capitalCostUsd": "0"
},
"capitalUsd": "20000",
"adverseBps": [
"10",
"25",
"50"
]
}
}The ID above is a placeholder; use a returned 32-character route ID. Save the body as plan.json and enter your own fees, costs and capital. The zero costs in this example are assumptions.
cURL
curl "https://humarb.com/api/v1/execution-plans" \
-H "Authorization: Bearer $HUMMINGBIRD_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @plan.json5. Engine reports & settlement history
GET/routes/{routeId}/analysis
Returns a completed saved report matching the route and scenario query parameters. A different size or fee assumption may have no matching report (503 ASSESSMENT_NOT_READY). Repeated reads do not start Hummingbird Engine analysis.
route · assessment · assessment.completedAt · seenAt · historicalOnly · isCurrentSnapshot · sourceExpired
GET/assessments/{assessmentId}
Retrieve a saved record by its UUID. The response assessment field contains the saved route and assessment. A report may expire under retention or capacity limits; a missing record returns 404. The legacy retentionDays field is not an availability guarantee.
GET/history?routeId={routeId}&days=7
days supports 7 or 30. Returns {version, readOnly, value, cache}. A cold request advances bounded backfill and can return HTTP 202 with partial records and Retry-After. Check value.pending, value.status and each leg’s coverage, backfill and reasonCodes.
Ready means the source pages were traversed, not a complete account backtest. Missing events are never zero-filled. Lighter historical units remain unverified and are excluded from cash totals. Export the returned JSON in your own tools.
6. Subscribe to publication events
GET/events
funding:read · text/event-streamSSE notifications announce funding_cycle publications, not tick-by-tick prices or account trades. Each event has id, kind, at and data. Resume with Last-Event-ID or after (integer cursor). Only the latest 100 events are retained.
A connection lasts about 25 seconds; reconnect after 5 seconds, or Retry-After on errors. Every reconnect uses quota. If your cursor is outside retention, read a fresh route snapshot. Use a server-side client capable of sending the Authorization header.
cURL
curl -N "https://humarb.com/api/v1/events" \
-H "Authorization: Bearer $HUMMINGBIRD_API_KEY"7. Handle errors and stale data
| HTTP | Meaning | Action |
|---|---|---|
| 400 | Invalid ID, scenario, cursor or history window | Fix the request; read the error code. |
| 401 / 403 | INVALID_API_KEY / ENTITLEMENT_REQUIRED | Check the key, scopes and paid entitlement. |
| 404 | ROUTE_NOT_FOUND / ASSESSMENT_NOT_FOUND | Refresh route IDs; an old report may no longer be retained. |
| 413 / 415 | Calculation body too large / wrong content type | ≤ 32 KiB · application/json |
| 429 | API_QUOTA_EXCEEDED / EXECUTION_QUOTA_EXCEEDED | Respect Retry-After. Daily quota resets at 00:00 UTC. |
| 503 | API_UNAVAILABLE / ASSESSMENT_NOT_READY | Back off until background data or a matching report is published. |
Errors use {"error":"CODE"}. A successful HTTP status does not establish freshness or execution suitability: validate validUntil, status, reasonCodes, coverage and source times. Use decimal arithmetic for money and rates; do not turn null into zero.
8. Use the Skill online with your AI
Send this to your AI
Read https://humarb.com/developers/skill online and follow its instructions to connect to Hummingbird API. Help me find funding-arbitrage opportunities and compare net returns after costs, break-even time and exit risks. If a key is needed, guide me to configure HUMMINGBIRD_API_KEY securely in the runtime, never in chat. Analyze only; do not place trades.
No download. Your AI reads the Skill online; live data also needs an HTTP tool, a securely stored key and an active API plan. It will guide you if something is missing.