> For the complete documentation index, see [llms.txt](https://k4k3ru.gitbook.io/k4k3ru-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k4k3ru.gitbook.io/k4k3ru-docs/api/market-hub/search-carry-routes.md). # Search Funding Carry Routes `MarketHub.Carry.Search` compares estimated Funding income across `spot-perp`, `perp-spot`, and `perp-perp` routes. This contract requires a release containing Carry; publication of this reference does not announce production availability. The method uses HTTPS JSON-RPC and costs zero ticks. Authentication is optional: anonymous requests use an IP/method quota; verified signed requests use an account/method quota. See [rate limits](#optional-authentication-and-rate-limits). ## Request ```json { "id": "1", "method": "MarketHub.Carry.Search", "params": { "symbol": "BTC/USDC", "baseAsset": "BTC", "quantity": "0.1", "holdingPeriodMinutes": 1440 } } ``` | Parameter | Requirement | | ---------------------------- | -------------------------------------------------------------------------- | | `assetClass` | Defaults to `crypto`, the only supported class. | | `symbol` | Required canonical symbol, maximum 32 characters. | | `baseAsset` | Required; must match the symbol base. | | `quantity` | Required positive decimal string in base units. | | `holdingPeriodMinutes` | Required integer from 1 to 43,200 inclusive; no default. | | `minimumEstimatedFundingBps` | Optional signed decimal string, defaults to `0`; inclusive threshold. | | `routeFamilies` | Defaults to all three families; `spot-spot` is rejected. | | `sourceFilter` | Optional Spread-compatible category, liquidity-model and AMM-chain filter. | Decimal strings are bounded to 128 characters; exponential and fraction syntax are not accepted. Unknown fields are rejected. Symbols must match exactly after normalization; stablecoin parity and wrapped-asset aliases are not applied. Negative thresholds include routes with estimated Funding payments. Omitting `minimumEstimatedFundingBps` includes nonnegative estimated Funding routes. Set it only when a different threshold is needed. For example, a route with `2.998685` bps is excluded by `"3"`; comparison does not round it to 3. Get and Subscribe do not accept this search filter. Copy a returned candidate's `route` into [Get](/k4k3ru-docs/api/market-hub/get-carry-snapshot.md) or [Subscribe](/k4k3ru-docs/api/market-hub/carry-subscribe.md), together with the symbol, base asset, quantity and holding period. A route ID alone is not a request selector. ## Calculation and eligibility Buy and sell entry prices use quantity-specific retained pool-state quotes for AMMs, and fresh depth VWAP for order-book venues. Carry retains AMM fee/price-impact calculations; [Spread](/k4k3ru-docs/api/market-hub/get-spread-snapshot.md#evaluation) uses AMM pool mids instead. A fresh BBO fallback for an order-book venue must cover the requested quantity. A leg with insufficient quantity is excluded. Each Perp requires a fresh latest estimated Funding rate and positive Mark Price. Missing or stale Funding, missing Mark Price and absent depth are not treated as zero. ``` periodFundingRate = currentEstimatedRate * holdingPeriodMinutes / intervalMinutes legFundingAmount = direction * quantity * markPrice * periodFundingRate routeFundingAmount = sum(legFundingAmount) fundingBps = routeFundingAmount / buyEntryQuoteAmount * 10000 annualizedRate = routeFundingAmount / buyEntryQuoteAmount * 525600 / holdingPeriodMinutes entrySpread = sellEntryQuoteAmount - buyEntryQuoteAmount entrySpreadBps = entrySpread / buyEntryQuoteAmount * 10000 ``` Direction is -1 for buying a Perp and +1 for selling a Perp, under the normalized positive-rate convention that longs pay shorts. Spot contributes zero Funding. Each Perp retains its own rate, interval and Mark Price. The Funding model holds rates and Mark Prices constant and prorates time linearly; it does not predict the number or value of actual upcoming Funding settlements. Settled rates are not substituted for estimates. Annualization is a decimal simple rate: `0.1095` means 10.95%, not APY or margin ROI. Decimal outputs round to 18 fractional places. Funding receive age is limited to 120 seconds. Price data is limited to 5 seconds (10 seconds for Hyperliquid). Freshness uses receive/observation time, not assumed synchronization of venue clocks. An entry price difference may be negative even when estimated Funding is positive. Entry difference and Funding are separate; neither their sum nor a net-profit estimate is returned. ## Result fields | Wire key | Meaning | | ----------------------------------- | --------------------------------------------------------------------------------- | | `ac`, `s`, `ba`, `qa`, `q` | Asset class, symbol, base asset, quote asset and quantity. | | `hpm`, `mefb`, `rf`, `sourceFilter` | Normalized holding period, Funding threshold, route families and source filter. | | `emc`, `erc`, `prc` | Fresh market views, evaluated directed routes and routes with both legs priced. | | `ferc` | Priced routes whose Funding inputs could also be evaluated, before the threshold. | | `er` | Eligible routes sorted by estimated Funding bps descending. | | `ts` | Evaluation time as Unix microseconds. | Each route includes `route`, a fixed selector that can be passed directly to [Get](/k4k3ru-docs/api/market-hub/get-carry-snapshot.md) or [Subscribe](/k4k3ru-docs/api/market-hub/carry-subscribe.md). It also has `id`, `f`, `b`, and `s`: route identifier, family, buy leg and sell leg. Legs use the Spread fields `v`, `mt`, `sd`, `ba`, `bai`, `qa`, `qai`, `vs`, `pid`, `c`, `n`, `q`, `vwap`, `qam`, `lc`, `bv`, and `ts` for market identity, quantity, pricing and provenance. Optional identity fields may be absent. Each route additionally contains: * `entrySpread`: `amount`, `bps`, and quote `asset`. * `fundingEstimate`: `amount`, `bps`, `annualizedRate`, `referenceNotional` (buy entry quote amount), quote `asset`, `holdingPeriodMinutes`, and `model: "constant-rate-linear"`. * `buyFunding` / `sellFunding`: present only for a Perp leg; each contains `kind`, `rate`, `intervalMinutes`, `fundingTimestamp`, `receivedTimestamp`, `markPrice`, and signed `estimatedAmount`. Timestamps are Unix microseconds. * `assessment`: execution feasibility, trading fees and exit cost are `not_evaluated`. Spot-short borrowing availability and cost are `not_evaluated` for `perp-spot`, and `not_applicable` for the other families. For example, the reverse direction explicitly carries this assessment: ```json { "f": "perp-spot", "assessment": { "executionFeasibility": "not_evaluated", "tradingFees": "not_evaluated", "borrowAvailability": "not_evaluated", "borrowCost": "not_evaluated", "exitCost": "not_evaluated" } } ``` `perp-spot` assumes Spot shorting. Selling pre-owned Spot inventory does not by itself establish the assumed new short hedge. Borrow availability, borrowing interest, fees, gas, transfers, collateral and exit execution are not verified or included. These are market-data estimates, not execution instructions or profit guarantees. Lending carry and dated futures are outside this contract. ## Errors * `invalid_parameter`: malformed or unsupported parameters. * `not_found`: no route has both price and Funding inputs sufficient for evaluation. * `rate_limit_error`: Gateway's public Search limit is exceeded. * `unexpected`: an unmapped internal error. A successfully evaluated population with no threshold-qualified route returns an empty `er` array rather than `not_found`. ## Optional authentication and rate limits Without `auth`, Gateway permits 3 requests per rolling 60 seconds per IP and method. With a valid signed `auth`, the first 3 requests are free and requests 4 through 60 cost 100 credits each per authenticated account and method; the 61st request is rate limited. Search and Get have separate quotas; API keys and IPs belonging to the same account share the authenticated quota. Anonymous requests cost zero ticks. Invalid supplied authentication is rejected rather than falling back to the anonymous quota. Use the normal API-key signature over the actual method, params, current timestamp and a unique nonce on each request. Merely attaching an API key does not enable the account quota. An exhausted quota returns HTTP 429, JSON-RPC `rate_limit_error` and `Retry-After: 60`. These counters are currently local to each Gateway process; restarts reset them and multiple Gateway instances do not share a global counter. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://k4k3ru.gitbook.io/k4k3ru-docs/api/market-hub/search-carry-routes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.