पब्लिक HTTP रेफ़रेंस
> Updated reference (English); translation pending.
The reference below uses paths relative to the selected ohtrade deployment. Read its configuration first. A preview can expose public reads while financial execution remains disabled.
The machine-readable reference is /docs/openapi.json. Common request schemas and the intent layout are published with the document manifest. This page describes the current route families, not a separate authentication service.
Read endpoints
| Method and path | Purpose |
|---|---|
GET /api/markets/quotes | Public USDC reference prices and the latest chart observations |
GET /api/markets/history?schema=3&symbol=BTC | Sampled quote history and OHLC candles for one market |
GET /api/funding/config | Network, program, genesis, settlement token, action availability and sponsorship policy |
GET /api/trading/config | Network identifiers, minimum opening notionals and fee policy |
GET /api/protocol/config | Auction configuration and action availability |
GET /api/trading/snapshot?owner=… | Markets, positions, pending state, balances, nonces and rent capacity |
GET /api/protocol/snapshot?owner=… | Pool, staking, buyback and protocol state |
GET /api/funding/account?owner=… | User account and funding balances |
GET /api/funding/wallet?owner=… | Wallet SOL and supported USDC balance |
GET /api/funding/rent/configuration?owner=… | Rent budget and additional capacity |
GET /api/funding/rent?owner=… | Rent items and refund availability |
GET /api/funding/refund?owner=…&mode=staking | Account-exit plan and blockers |
GET /api/funding/account/fees | Available network-fee choices |
GET /api/trading/session?owner=…&authority=… | Trading authorization |
GET /api/funding/referrals?owner=…&offset=… | Invited-account list, in pages of 50 |
GET /api/funding/history?owner=…&before=…&limit=… | Confirmed account history by signature |
GET /api/protocol/auction/rounds?before=…&limit=… | Buyback round history |
GET /api/trading/events?owner=… | Server-sent execution events |
The trading and protocol snapshots accept an omitted owner for their public projection. User-specific reads need a valid public wallet address. A read does not prove control of that wallet; returned public activity is visible to other clients too.
Reference prices and chart history
The market-data service is read-only. /api/markets/quotes returns now, historyEpoch, historyStartedAt and a markets array. Each market includes its id, symbol, session, sessionOpen, price, bid, ask, updatedAt, sources, status, any available chartTick and referencePoints. Prices are decimal integer strings with 8 decimals in USDC; timestamps are UTC Unix milliseconds. An unavailable price, bid, ask or update time is null.
These responses identify themselves with executionEnabled:false and referenceOnly:true on each market. sessionOpen describes the reference session; it does not enable a financial action. status is live, degraded or unavailable. A degraded display quote can retain its original observation time during a short interruption. Check that time before using the quote; an older chartTick is history, not a new observation.
Request chart data with schema=3 and an exact uppercase symbol from the market list. The response identifies its epoch, startedAt, currency:USDC and source:ohtrade-canonical-quotes. Three independent streams are returned: ticks, 15-second candles and 900-second coarseCandles. Each page contains at most 1,000 items per stream. The retained windows are up to 7,200 recent ticks, 24 hours of base candles and 30 days of coarse candles; gaps and new markets can have less data.
| Parameter | Use |
|---|---|
epoch | Echo the returned epoch when polling. A missing or different epoch resets the server's after filter to zero. |
after | Non-negative safe-integer sequence; default 0. Requests newer ticks and changed candles. The last two candles of each resolution can repeat so their coverage status stays current. |
beforeTick | Exclusive UTC-millisecond time boundary for older ticks; use olderTicksBefore. |
beforeCandle | Exclusive time boundary for older base candles; use olderCandlesBefore. |
beforeCoarse | Exclusive time boundary for older coarse candles; use olderCoarseBefore. |
A null older-page cursor means that stream has no more retained items for the query. If other streams still need older pages, use 1 as the exhausted stream's before value to avoid fetching its latest page again. Merge ticks by sequence and candles by their bucket time, keeping the greatest lastSequence and accepting coverage updates at the same sequence. Save the first, newest page's sequence before paging backwards; advance your live after cursor to that saved value only after all older pages succeed. Later pages can report a higher live sequence without containing those new ticks. When the epoch changes, clear the old data and all cursors and start again.
Tick time is the sample time; observedAt is the underlying quote evidence time. sourceAgeMs records its age at sampling, and gapBefore marks an interruption. Candles contain actual sampled open, high, low, close, samples, firstAt, lastAt, lastSequence and partial. A partial candle has incomplete coverage. Missing observations stay missing; the service does not fill a gap with invented prices or import exchange trade candles.
curl https://ohtrade.xyz/api/markets/quotes
curl 'https://ohtrade.xyz/api/markets/history?schema=3&symbol=BTC'
These two routes accept GET only and return Cache-Control: no-store. They use the website's regional access policy and do not provide the financial APIs' CORS/OPTIONS interface. Invalid history parameters return 400; unsupported methods are refused. Use the published paths on the website origin.
Quotes and intent submission
POST /api/trading/quote accepts an opening preview with asset, marketId, side, amount, leverage and optional owner. It returns an indicative quote, not an executed position.
POST /api/trading/intent accepts {intent, signature, signer}. The signed message and 64-byte signature use base64. Its {id, accepted:true} response identifies intake; follow SSE and account state for the fill. The Agent guide describes the signed fields and recovery model.
Prepare and submit
| Family | Prepare body | Submit body |
|---|---|---|
| Trading | owner, kind, asset, margin/leverage or position/Request; orderType is market or limit | id, transaction, optional returned quoteToken |
| Account | owner, action, action-specific amount, recipient, invitation or rent configuration | id, transaction |
| Auction | owner, kind, action-specific amount/price or order address/revision/selection | id, transaction, returned signed followUps where present, optional returned quoteToken |
Prepared transaction values are base64 serialized Solana transactions. Preserve the exact message while adding the required wallet signature. Confirm deployment identifiers, expected fee payer and storage cost before approval. Keep any returned quoteToken with the operation and echo it unchanged on submit.
For persistent limits, send orderType: "limit" and orderPrice as a positive integer string with 8 price decimals. A close also requires triggerAbove: 1 for price ≥ target or 0 for price ≤ target. Omit priceBound from the preparation API; the removed price-protection input is rejected. Market requests carry no bound. Use the Request route for limits, not the short-lived intent route. A snapshot Request exposes orderMode (0 market/legacy, 1 limit open, 2 close ≥, 3 close ≤), orderPrice and its position address. Conditional creation and routine cancellation consume the ordinary sponsor budget; actual market closes and exit operations retain their existing exit-budget treatment. Availability still depends on the deployed program and enabled financial services.
Trading kinds are open, close and cancel_request. Auction kinds are sell, amend_sell, cancel_sell, cancel_sells, cancel_all and continue_cancel. A reprice uses the order address and its expected revision.
Account actions cover setup, deposits/withdrawals, internal OH transfers, staking/unstaking, claims, trading-key management, rent deposits/withdrawals and eligible account refunds. Their returned quote lists the specific account changes and blocking conditions.
Status and cancellation progress
- Prepared trade:
GET /api/trading/status?id=…&owner=…. - Prepared account action:
GET /api/funding/account/status?id=…. - Auction action:
GET /api/protocol/operation?id=…&owner=…. - Auction cancellation batch:
GET /api/protocol/cancellation?operationId=…&owner=….
Status objects distinguish confirmation, failure, expiry and unavailable history. Cancellation progress additionally distinguishes completed selection items, remaining signature work and rent still waiting for cleanup.
Response handling
Use Content-Type: application/json on POST requests. The funding, trading and protocol API prefixes support GET, POST and OPTIONS with CORS. Normal read routes and signed writes do not require a public API key or Cookie.
Keep financial quantities as decimal integer strings. Handle 400-series validation and authorization errors separately from 429 rate limits and 503 service-busy/unavailable responses. Error code is the stable integration field; the human-readable message can be localized.
curl https://ohtrade.xyz/api/trading/config
curl 'https://ohtrade.xyz/api/protocol/snapshot'
For authenticated action construction, follow the wallet-signature flow instead of sending a private key to the HTTP service. The generated OpenAPI lists public routes only.
Local V11 implementation
This V11 build supports fresh deployments only. Its changed account discriminators and layouts must be decoded with the matching release's sdk/idl/perp.json and SDK; legacy accounts cannot be reinterpreted or upgraded in place by this build. The intent wire version is separate from the account ABI.
Economic version 11: an opening preview returns exposure, the pressure-adjusted profit exposure C, not a reserved payout budget. minExposure is an owner-signed acceptance floor in collateral atomic units, no greater than notional. The website defaults to minExposure = 0; API callers may explicitly sign a nonzero minimum as their own acceptance condition. Execution below the signed floor rejects the open; a bot signing zero disables only this floor, not collateral, price, integer-capacity or authorization checks. Intent v2 remains 175 bytes with minExposure at offset 167; a close uses zero. Opening selects D from the UTC table and stores it in ppb. Consult PnL for calculation and rounding. The local V11 implementation does not establish that a live deployment has switched versions.
V11 स्थानीय कार्यान्वयन
यह V11 बिल्ड केवल नए परिनियोजन के लिए है। बदले खाते के पहचानकर्ता और संरचना उसी रिलीज़ के sdk/idl/perp.json व SDK से पढ़ें; पुराने खाते पुनर्व्याख्यायित या उसी स्थान पर अपग्रेड नहीं हो सकते। Intent संदेश संस्करण खाता ABI से अलग है।
आर्थिक संस्करण 11: प्रवेश पूर्वावलोकन exposure में दबाव-समायोजित लाभ एक्सपोज़र C लौटाता है, आरक्षित भुगतान बजट नहीं। minExposure संपार्श्विक की परमाणु इकाई में हस्ताक्षरित न्यूनतम स्वीकृति है, नाममात्र राशि से अधिक नहीं; वेबसाइट का डिफ़ॉल्ट minExposure = 0 है; API कॉलर अपनी स्वीकृति शर्त के रूप में गैर-शून्य न्यूनतम पर स्पष्ट हस्ताक्षर कर सकता है। इससे कम निष्पादन प्रवेश अस्वीकार करता है। शून्य हस्ताक्षर केवल यह सीमा हटाता है, संपार्श्विक, भाव, पूर्णांक क्षमता या अनुमति जाँच नहीं। Intent v2 अभी 175 बाइट है, minExposure ऑफसेट 167 पर और समापन में शून्य है। प्रवेश UTC तालिका से D चुनकर ppb में रखता है। लाभ-हानि देखें। स्थानीय V11 कार्यान्वयन लाइव संस्करण बदलने की पुष्टि नहीं है।