Canonical: https://ohtrade.xyz/docs/ja/api.html
Language: ja
Updated: 2026-11-08

# 公開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.

```sh
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](https://ohtrade.xyz/docs/ja/agents.md) 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.

```sh
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](https://ohtrade.xyz/docs/ja/pnl.md) 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：新規注文のプレビューは圧力調整後の利益計算エクスポージャー C を `exposure` として返し、支払予算を予約しません。`minExposure` は署名した許容下限で、担保の最小単位を使い、想定元本以下です。画面の既定値は `minExposure = 0` です。API 利用者は自分の許容条件として非ゼロの下限に明示的に署名できます。約定値が下限未満なら新規注文を拒否します。0 の署名はこの下限のみ無効にし、担保・価格・整数容量・権限チェックは残ります。Intent v2 は 175 バイトのままで、オフセット 167 が `minExposure`、決済は 0 です。約定時に UTC 表から D を選び ppb で保存します。[損益](https://ohtrade.xyz/docs/ja/pnl.md)を参照してください。ローカル V11 実装は本番の版変更を示しません。
