目次
CrestRate API リファレンス
通貨をまたいで受け取り・支払いを行う企業のための、複数ソース集約型のレートAPIです。レートをどちら側に有利にするかを選べ、スプレッドはAPIキーごとに設定でき、見積書はレートとスプレッドの両方をロックします。
- ベースURL —
https://api.crestrate.com。レートのエンドポイントはすべて/v1の下にあります（例：https://api.crestrate.com/v1/rate） - はじめての導入 — まずクイックスタートへ。コピーできる4つのコードで最初のリクエストが通ります
- 機械可読な仕様 — OpenAPI 3.1
- プラン・クォータ・レート制限 — 料金
- サービス稼働状況 — https://crestrate.com/ja/status
用途
ある通貨で価格を決め、別の通貨で決済するなら使えます。業種で対象を絞ってはいません。主な用途は次のとおりです。
- 越境EC — 商品価格を顧客の通貨に換算
- SaaS・サブスクリプション — 顧客ごとに現地通貨で請求
- 訪日客の消費 — ホテル、小売、免税店、POSシステムは円で価格を設定し、訪日客は香港ドル、人民元、米ドル、ユーロで支払い
- B2B輸出入 — 買い手の通貨で請求書を発行し、オファーの有効期間中は見積書でレートを固定
- プラットフォーム・マーケットプレイス — 購入者からの受け取りは
strategy=max、出品者への支払いはstrategy=min - 旅行・留学・ビザ代行 — 顧客の通貨で見積もり
- ゲーム・デジタル商品 — 地域別の価格設定
対応通貨
次の通貨はリアルタイムデータを提供しており、base と quote を自由に組み合わせられます。
| 通貨 | コード | 金額の最小単位 |
|---|---|---|
| 米ドル | USD |
0.01 |
| 日本円 | JPY |
1 |
| ユーロ | EUR |
0.01 |
| 香港ドル | HKD |
0.01 |
| 人民元 | CNY |
0.01 |
現在リアルタイムデータを提供できません： TWD、SGD、GBP、AUD、KRW、MYR、THB。データが安定し次第提供します。
それまでは、これらのコードを使ったリクエストは HTTP 422 currency_not_available を返し、supported に利用可能な通貨の一覧が入ります。まったく認識できないコードは HTTP 400 unsupported_currency を返します。リクエストの通貨コードは大文字・小文字を区別せず、レスポンスでは常に大文字です。
レートの選び方
リクエストのたびに、単一のフィードではなく、その時点で正常なすべてのソースを同時に使って価格を算出します。
- 各ソースのレート表を共通の基準に正規化し、指定された通貨ペアをクロスレートとして算出します
- データが古いソースと、その通貨ペアを扱っていないソースを先に除外します
- 利用可能な中で最も鮮度の高い階層（リアルタイム → 毎時 → 日次）のソースの中央値をアンカーとします。 これが現在の市場価格の最も信頼できる推定値です
- アンカーから障害しきい値を超えて乖離しているソースは、破損データとして除外します
- 残ったソースから
strategyに従ってレートを選びます。maxは最も高いもの、minは最も低いもの、medianは中央値に最も近いものです。 その後、両方向に制限をかけます。上限cap_rateを超えれば引き下げ、下限floor_rateを下回れば引き上げます - 最後に、お客様の立場の方向へスプレッドを適用します。受け取る側なら上乗せ、支払う側なら差し引きです
レスポンスには、最終レートがどのソースから来たか、他の各ソースがいくらを提示したか、除外されたソースとその機械可読な理由（excluded_code）が必ず含まれます。ソースは source_a のような安定した匿名IDで示されます。
有効なソースが足りない場合は、保証できない数字を返す代わりに HTTP 503 no_rate を返します。
レートをどちら側に有利にするか
同じ通貨ペアでも、受け取るときはレートが高いほど、支払うときは低いほど有利です。strategy でお客様の立場を指定してください。レスポンスの side に、どちらの立場で計算したかが示されます。
strategy |
side |
有利になる側 | 主な用途 |
|---|---|---|---|
max（デフォルト） |
charge |
受け取る側：最も高いレートを選び、同じ価格でより多く受け取れます | EC、SaaS、ホテル、B2B請求 |
min |
pay |
支払う側：最も低いレートを選び、同じ支払額をより少なく済ませます | マーケットプレイスの出品者への支払い、海外サプライヤーへの支払い |
median |
charge |
中立：全ソースの中央値に最も近いレート | 会計記帳、社内レポート |
strategy は大文字・小文字を区別せず、それ以外の値は HTTP 400 bad_request を返します。side はスプレッドの方向と端数処理の方向も決めます。
| 項目 | charge（受け取る側） |
pay（支払う側） |
|---|---|---|
| スプレッド | レートが上がり、顧客の支払いが増えます | レートが下がり、お客様の支払いが減ります |
payable の端数処理 |
通貨の最小単位に切り上げ | 通貨の最小単位に切り捨て |
gain_vs_mid |
payable - mid_payable（多く受け取れた額） |
mid_payable - payable（支払いを抑えられた額） |
両方向に保護があります。 選ばれたレートは鮮度アンカー anchor_rate と比較されます。上限 cap_rate を超えれば戻され（capped: true）、下限 floor_rate を下回れば引き上げられます（floored: true）。受け取る側では実勢レートを大きく上回らず、支払う側では大きく下回りません。相手が公開レートと照合しても説明がつきます。スプレッドはお客様が明示的に設定するもので、この制限の後に適用されます。
スプレッド
スプレッドは、選ばれたレートに上乗せする幅です。単位はベーシスポイント（bps）で、100 bps = 1% です。
| 項目 | 説明 |
|---|---|
| 設定場所 | ダッシュボードのAPIキー一覧です。キーごとに個別に設定します |
| 既定のスプレッド | そのキーがすべての通貨で使うスプレッドです |
| 通貨ごとの設定 | quote 通貨ごとに既定値を上書きできます。例：HKD は 120 bps、JPY は 200 bps。リアルタイムデータを提供している通貨のみ設定できます |
| 設定範囲 | 0〜1000 bps（0%〜10%）。0 は「スプレッドを加えない」という明示的な設定です |
| 反映タイミング | 保存するとすぐに反映され、次のリクエストから新しい値が使われます |
| 見積書 | スプレッドは見積書の作成時に固定されます。後から変更しても、発行済みの見積書には影響しません |
優先順位は次のとおりです（上ほど優先）。どれが使われたかはレスポンスの markup_source に示されます。
- そのキーの通貨ごとの設定 →
key_currency - そのキーの既定のスプレッド →
key_default - プラットフォームの既定値 →
platform
同一通貨のペア（例：USD → USD）は換算が発生しないため、スプレッドは適用されず、markup_source は none になります。
方向と端数処理は side に従うため、結果は常にお客様に有利です。 受け取る側：raw_rate × (1 + markup_bps/10000)、金額は切り上げ。支払う側：raw_rate × (1 - markup_bps/10000)、金額は切り捨て。
計算例（数値は説明用で、実際のレートではありません。比較しやすいよう、どちらの場合も選ばれたレートを 7.8000 とします）：1,000 米ドルの注文を香港ドルで決済し、スプレッドは 150 bps（1.5%）。
| ケース | スプレッドなし | スプレッド 150 bps | 差額 |
|---|---|---|---|
受け取る場合（strategy=max） |
レート 7.8000、顧客の支払い HK$7,800.00 | レート 7.9170、顧客の支払い HK$7,917.00 | HK$117.00 多く受け取り |
支払う場合（strategy=min） |
レート 7.8000、お客様の支払い HK$7,800.00 | レート 7.6830、お客様の支払い HK$7,683.00 | HK$117.00 支払いを削減 |
保存前にプレビューできます。 ダッシュボードでスプレッドを設定すると、値を調整するたびに、顧客の支払いがいくら増えるか、お客様の支払いがいくら減るかがその場で表示されます。
開示について。 スプレッドの開示が求められる地域（例：EUにおける消費者向け決済）では、お客様の顧客に対してスプレッドを開示してください。
見積書によるロック
見積書は、顧客に提示した価格を有効期限まで固定します。表示から支払いまでの間にレートが動いても、金額の食い違いは起きません。
POST /v1/quotesは、作成時点の最終レートrate、適用中のスプレッドmarkup_bps、決済金額payableを固定します- その後ダッシュボードでキーのスプレッドを変更しても、発行済みの見積書は変わりません
- 見積書の有効時間は
ttl_secondsです（現在は 900 秒、つまり 15 分）。値はハードコードせず、レスポンスから読み取ってください quote_idを保存し、顧客の支払い時にGET /v1/quotes/{quote_id}で取得してください。expires_atを過ぎると 404 になるため、新しい見積書を作成してください
ウェブサイトのデモ
トップページのライブデモは試用のためのものであり、組み込み用のAPIではありません。
- データは 1 時間遅れです。各ソースの 1 時間前の最新スナップショットで計算し、結果の横にデータ時刻を表示します
- すべてのリクエストで、操作不要の人間確認（Cloudflare Turnstile）を行います
- プラットフォームの既定スプレッドを使い、ネットワーク単位と全体でレート制限があり、混雑時は「混雑中」と表示されることがあります
- APIキーは受け付けず、どのアカウントの利用量としても計量されません
リアルタイムのデータが必要な場合は、ダッシュボードで無料のAPIキーを作成してください。
APIリファレンス
認証
すべての /v1 エンドポイントでAPIキーが必要です。匿名アクセスはありません。
| ヘッダー | 例 |
|---|---|
X-API-Key |
X-API-Key: <お客様のキー> |
Authorization |
Authorization: Bearer <お客様のキー> |
- どちらか一方を送ってください。両方ある場合は
X-API-Keyが使われます - キーの作成・失効はダッシュボードで行います。事前にメールアドレスの確認が必要で、1 アカウントが同時に持てる有効なキーは最大 10 個です。平文のキーは一度だけ表示されます
- 失効したキーは直ちに使えなくなります（HTTP 401
invalid_api_key） - APIはお客様のサーバーから呼び出してください。
/v1のレスポンスには CORS ヘッダーが付かず、ウェブページやモバイルアプリに埋め込んだキーは誰でも取り出せます GET /healthとGET /openapi.jsonはキー不要です
共通仕様
| 項目 | 説明 |
|---|---|
| レートと金額は必ず文字列 | JSONのnumberではありません。JSONのnumberはIEEE 754倍精度であり、0.05117904 のような値は解析時に精度が落ち、金額が狂います。Decimal（Python）/ BigDecimal（Java）/ decimal.js（JS）で解析してください。レートは小数点以下 8 桁です |
| 時刻 | 常にISO 8601のUTC文字列です（例：2026-09-14T10:38:01Z）。演算が必要な箇所では *_unix（Unix秒、小数）も併せて返します |
| パーセント | 文字列で、単位は % です（小数ではありません）。"0.1791" は0.1791%を意味し、17.91%ではありません |
| 通貨コード | ISO 4217。リクエストでは大文字・小文字を区別せず、レスポンスでは大文字です。上記「対応通貨」を参照してください |
| base / quote | base = 価格を決める通貨、quote = 決済通貨（受け取る場合は顧客の支払通貨、支払う場合はお客様が支払う通貨）。レートの意味は常に「base 1単位が quote いくらに相当するか」です |
| キャッシュと Cookie | レートのレスポンスには Cache-Control: no-store が付きます。APIが Cookie を設定することはありません |
レート制限と月間クォータ
各プランには、レート制限（一定の速度と短時間のバースト）と月間リクエストクォータがあり、料金ページに掲載しています。
- どちらもキー単位ではなくアカウント単位で数えます。 同一アカウントのすべてのAPIキーが、1 つのレート制限と 1 つの月間クォータを共有します。キーを増やしても上限は増えません。
X-Quota-*ヘッダーはアカウント全体の合計を示します - 月間クォータは各暦月の開始時（UTC）にリセットされます
- 認証と上限のチェックを通過したリクエストは、結果にかかわらずクォータに数えられます（400、404、422、503 を含む）。401、403、429 で拒否されたリクエストは数えられません
/v1エンドポイントへのHEADリクエストはGETとまったく同じように処理され（レート計算がすべて実行されます）、クォータとレート制限にも同じように数えられます- 存在しないパスは 404
not_foundを返し、計量されません
すべての /v1 レスポンス（エラーを含む）に次のヘッダーが付きます。
| ヘッダー | 意味 |
|---|---|
X-RateLimit-Limit |
最大バースト：連続して送れるリクエスト数 |
X-RateLimit-Remaining |
待たずに今すぐ送れるリクエスト数 |
X-RateLimit-Reset |
次のリクエスト枠が使えるようになる Unix 時刻（秒） |
X-Quota-Limit |
アカウントの月間クォータ。0 は無制限 |
X-Quota-Used |
アカウントが今月使ったリクエスト数（今回を含む） |
X-Quota-Remaining |
今月の残りリクエスト数。X-Quota-Limit が 0（無制限）のときは常に 0 なので、先に上限を確認してください |
X-Request-Id |
このリクエストのID。サポートへの問い合わせ時に添えてください |
Retry-After |
待つべき秒数。429 rate_limited のときだけ付きます |
リクエストをアカウントに結び付けられない場合（キーがない・無効、アカウントが停止中またはメール未確認、ボディが大きすぎる、内部エラー）、レート制限とクォータのヘッダーはどのアカウントとも無関係な中立の既定値になります。
上限に達したとき
| レスポンス | 意味 | 対処 |
|---|---|---|
429 rate_limited |
短時間にリクエストが多すぎる | Retry-After 秒待ってから再試行（ボディにも retry_after があります） |
429 quota_exceeded |
アカウントの月間クォータを使い切った。ハードブロックで、超過課金はなく、Retry-After も付きません |
再試行しないでください。アップグレード（upgrade_url は料金ページの絶対URL）するか翌月を待ってください。ボディに used と quota が入ります |
リクエストの処理順序
リクエストは次の順にチェックされ、最初に通らなかったチェックがレスポンスを決めます。
- ボディのサイズ：16 KiB を超える → 413
payload_too_large - APIキーがない → 401
api_key_required、無効または失効済み → 401invalid_api_key - アカウント停止 → 403
account_disabled、メールアドレス未確認 → 403email_not_verified - レート制限 → 429
rate_limited、月間クォータ → 429quota_exceeded - パラメータ → 400
bad_request/ 400unsupported_currency/ 422currency_not_available（この時点でクォータに数えられています） - 価格算出 → 有効ソース不足で 503
no_rate、データストアに一時的に接続できない場合は 503storage_unavailable
GET /v1/rate
単一の通貨ペアの最終レートを、全データソースの内訳付きで返します。
クエリパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
base |
はい | 価格を決める通貨。別名 from |
quote |
はい | 決済通貨。別名 to |
strategy |
いいえ | レートをどちら側に有利にするか：max（デフォルト、受け取る側）/ min（支払う側）/ median（中立）。大文字・小文字を区別しません |
同一通貨のペア（例：base=USD"e=USD）はレート 1.00000000 を返し、chosen_provider と anchor_tier は identity になります。
レスポンス：トップレベルのフィールド
| フィールド | 型 | 説明 |
|---|---|---|
base |
string | 価格を決める通貨 |
quote |
string | 決済通貨 |
rate |
string | 最終レート。金額計算にそのまま使うのはこれです。受け取る側（side=charge）は raw_rate × (1 + markup_bps/10000)、支払う側（side=pay）は raw_rate × (1 - markup_bps/10000) です。markup_bps が0のときは raw_rate と一致します |
raw_rate |
string | スプレッド適用前のレート。strategy に従って各ソースから選ばれ、上限または下限に達した場合は cap_rate / floor_rate に調整済みの値です |
mid_rate |
string | 有効ソースの中央値で、市場のミッドレートにほぼ相当します。市場からどれだけ高いかを測る基準に使えます |
low_rate |
string | 有効ソースの中で最も低いレート。strategy=min かつ下限未適用なら raw_rate と一致します |
high_rate |
string | 有効ソースの中で最も高いレート。strategy=max かつ上限未適用なら raw_rate と一致します |
markup_bps |
int | この呼び出しで実際に適用されたスプレッド（bps、100 bps = 1%）。同一通貨のペアでは常に 0 |
markup_source |
string | スプレッドの出どころ：key_currency（そのキーの通貨ごとの設定）/ key_default（そのキーの既定値）/ platform（プラットフォームの既定値）/ none（同一通貨のペアで、スプレッドなし） |
strategy |
string | 使われた選択戦略：max / median / min |
side |
string | この呼び出しがどちら側に有利か：charge（受け取る側。max と median）/ pay（支払う側。min）。スプレッドの方向と端数処理はこれに従います |
chosen_provider |
string | 最終レートがどのソースから来たか。source_a のような匿名ID。同一通貨のペアでは identity |
source_count |
int | 価格算出に使われた有効なソースの数（除外されたものは含みません） |
spread_vs_mid_pct |
string | 最終レートの mid_rate からの乖離（%、小数点以下 4 桁）。受け取る側では通常プラス、支払う側では通常マイナス |
anchor_rate |
string | 鮮度アンカー。外れ値の除外も上限・下限もこれを基準にします。利用可能な最も新しい階層の中央値です |
anchor_tier |
string | アンカーの出どころの階層：realtime / hourly / daily / all / identity。daily や all に下がった場合は、新しいソースがすべて使えず、市場から乖離している可能性があります |
anchor_notes |
string[] | より新しい階層がアンカーに使われなかった理由（英語）。通常は空配列 |
cap_rate |
string | null | 上限：anchor_rate に一定幅を加えた値。raw_rate がこれを超えることはありません。同一通貨のペアでは null |
capped |
bool | true は、選ばれたレートが上限を超えて引き下げられたことを示します。市場が動いているのに遅いソースが追いついていないサインで、アラートに値します |
floor_rate |
string | null | 下限：anchor_rate から同じ幅を引いた値。raw_rate がこれを下回ることはありません。同一通貨のペアでは null |
floored |
bool | true は、選ばれたレートが下限を下回って引き上げられたことを示します。strategy=min で多く見られます |
sources |
object[] | 除外されたものも含む、ソースごとの内訳。下表を参照 |
generated_at |
string | このレスポンスの生成時刻（ISO 8601 UTC） |
generated_at_unix |
float | 同上、Unix秒 |
レスポンス：sources[] の各要素
| フィールド | 型 | 説明 |
|---|---|---|
provider |
string | 安定した匿名のソースID（例：source_a） |
label |
string | 表示名（例：Source A） |
data_freq |
string | null | ソース自体のデータの更新頻度：realtime / hourly / daily |
rate |
string | null | このソースが示した base→quote のレート。null はこのソースがそのペアを扱っていないことを示します |
vs_anchor_pct |
string | null | anchor_rate からの乖離（%、プラスは高い） |
fetched_at |
string | 当社が取得した時刻（ISO 8601 UTC） |
age_seconds |
float | その取得からの経過秒数 |
source_time |
string | null | ソース自身が主張するデータの時刻。null はソースがこれを公開していないことを示します |
used |
bool | 今回の価格算出に使われたか |
chosen |
bool | 選ばれたソースかどうか |
excluded_code |
string | null | 除外理由の機械可読コード。使われた場合は null。監視ではこれで照合してください |
excluded_reason |
string | null | 人が読むための英語の除外理由。使われた場合は null。文言は変わることがあるため、解析しないでください |
excluded_code の値
excluded_code |
excluded_reason の例 |
意味 | 対処 |
|---|---|---|---|
missing_currency |
Source does not cover this currency pair |
そのソースがこのペアを扱っていない | 正常です。他のソースが補います |
snapshot_stale |
Snapshot is stale (9000s > 7200s) |
そのソースから長時間新しいデータを取得できていない | 他のソースが補います。続く場合は稼働状況ページを確認してください |
deviates_from_anchor |
Deviates 12.5% from the realtime tier anchor, beyond +/-5%; treated as a data fault |
ソースの値がアンカーから離れすぎている | そのソースのデータが破損している可能性が高く、お客様側での対応は不要です |
GET /v1/rates
複数の通貨ペアのレート表を 1 回で取得します。各行は GET /v1/rate の簡略版で、sources の内訳は含みません。
クエリパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
base |
いいえ | カンマ区切りの価格通貨（例：USD,EUR）。空の項目と重複は無視されます |
quote |
いいえ | カンマ区切りの決済通貨（例：JPY,HKD） |
省略した場合はサービスの既定の通貨グリッドが使われます。正確な行に依存する場合は、両方を明示的に指定してください。
一覧に認識できないコードが含まれるとリクエスト全体が 400 unsupported_currency、リアルタイムデータを提供していない通貨が含まれると 422 currency_not_available を返します。base の一覧全体が quote より先にチェックされます。同じ一覧の中では認識できないコードがリアルタイムデータを提供していない通貨より優先されますが、base の問題が常に先に報告されるため、base にリアルタイムデータを提供していない通貨、quote=ZZZ を指定すると 422 を返します。
各行にはお客様のキーのスプレッドではなく、プラットフォームの既定スプレッドが適用されます。 ご自身のスプレッドを適用するには
GET /v1/rateまたはGET /v1/convertを使ってください。
レスポンス
| フィールド | 型 | 説明 |
|---|---|---|
rows |
object[] | base × quote の組み合わせごとに 1 行 |
generated_at / generated_at_unix |
string / float | 生成時刻 |
rows[] の各要素
| フィールド | 型 | 説明 |
|---|---|---|
base / quote |
string | 通貨ペア |
final_rate |
string | プラットフォームの既定スプレッドを適用した最終レート |
raw_rate |
string | スプレッド適用前 |
mid_rate |
string | ソース間の中央値 |
chosen_provider |
string | 選ばれたソース（匿名ID） |
source_count |
int | 有効なソースの数 |
markup_bps |
int | 適用されたスプレッド（プラットフォームの既定値） |
spread_pct |
string | ミッドに対するプレミアム（%、小数点以下 3 桁） |
anchor_tier |
string | アンカーの階層 |
capped |
bool | 上限に達したか |
error |
string | null | null でない場合、その行にはレートがありません。base、quote、error のみが入ります。典型的な原因はそのペアの有効ソース不足です。行を使う前に必ず null をチェックしてください |
GET /v1/convert
価格通貨の金額を決済金額に換算します。金額は通貨の最小単位に丸められ（JPY は 1、USD・EUR・HKD・CNY は 0.01）、端数処理の方向は side に従います。受け取る側は切り上げ、支払う側は切り捨てなので、端数は常にお客様に有利です。
クエリパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
base / quote |
はい | GET /v1/rate と同じ（別名 from / to を含む） |
amount |
はい | 価格通貨での金額。10 進数の文字列で、0 より大きいこと。換算結果（payable、mid_payable）は決済通貨の最小単位に丸めた後、小数部を含めて最大 28 桁までで、これを超える金額は 400 bad_request を返します |
strategy |
いいえ | GET /v1/rate と同じ |
レスポンス
| フィールド | 型 | 説明 |
|---|---|---|
base / quote |
string | 通貨ペア |
amount |
string | 渡された金額（10 進数の文字列） |
payable |
string | 決済金額。受け取る側（side=charge）では顧客の支払額で切り上げ、支払う側（side=pay）ではお客様の支払額で切り捨て |
rate |
string | 使われた最終レート |
mid_rate |
string | 市場のミッドレート |
mid_payable |
string | ミッドレートでの金額（四捨五入）。比較用 |
gain_vs_mid |
string | お客様に有利な差額。大きいほど良い。受け取る側：payable - mid_payable（多く受け取れた額）。支払う側：mid_payable - payable（支払いを抑えられた額） |
markup_bps |
int | 適用されたスプレッド |
markup_source |
string | スプレッドの出どころ。GET /v1/rate と同じ |
side |
string | charge / pay。GET /v1/rate と同じ |
chosen_provider |
string | レートの出どころのソース（匿名ID） |
source_count |
int | 有効なソースの数 |
anchor_tier |
string | アンカーの階層 |
capped |
bool | 上限に達したか |
floored |
bool | 下限に達したか |
GET /v1/convertは換算するだけで、価格をロックしません。実際の注文にはPOST /v1/quotesを使ってください。
POST /v1/quotes
ロックされた見積書を作成します。レート、スプレッド、payable は ttl_seconds の間固定され、決済には payable を使います。
リクエストボディ（JSON オブジェクト、Content-Type: application/json、16 KiB 以下）
| フィールド | 必須 | 説明 |
|---|---|---|
base / quote |
はい | 通貨ペア。別名 from / to |
amount |
はい | 価格通貨での金額。0 より大きいこと。10 進数の文字列を推奨しますが、JSON の number も受け付けます |
reference |
いいえ | お客様自身の注文番号（最大 128 文字）。保存され、照合用にそのまま返されます |
strategy |
いいえ | レートをどちら側に有利にするか。GET /v1/rate と同じ |
ボディが正しい JSON でない、JSON オブジェクトでない、フィールドの型が違う場合は 400 bad_request を返します。
レスポンス（HTTP 201）
| フィールド | 型 | 説明 |
|---|---|---|
quote_id |
string | 見積書ID（小文字の 16 進数 32 文字）。後の照会や照合のために保存してください |
reference |
string | null | 渡された注文番号をそのまま返します |
base / quote |
string | 通貨ペア |
amount |
string | 価格通貨での金額 |
payable |
string | 決済金額、つまりロックされた値。有効期限まで変わりません。端数処理は side に従います |
rate |
string | ロックされた最終レート |
raw_rate |
string | スプレッド適用前のレート |
mid_rate |
string | 注文時点の市場のミッドレート（照合用） |
markup_bps |
int | 作成時に固定されたスプレッド。後でダッシュボードでスプレッドを変更しても、この見積書には影響しません |
strategy |
string | 選択戦略 |
side |
string | charge / pay。GET /v1/rate と同じ |
chosen_provider |
string | レートの出どころのソース（匿名ID）。紛争や照合の際の根拠になります |
source_count |
int | その時点の有効なソースの数 |
created_at / created_at_unix |
string / float | 作成時刻 |
expires_at / expires_at_unix |
string / float | 有効期限。過ぎるとそのIDでの照会は 404 になります |
ttl_seconds |
int | ロック時間（秒） |
見積書を保存できなかった場合は 503 storage_unavailable を返し、見積書は存在しません。リクエストを再試行してください。
GET /v1/quotes/{quote_id}
見積書を取得します。フィールドは作成時に返されたものとまったく同じで、1 つだけ追加されます。
| フィールド | 型 | 説明 |
|---|---|---|
expired |
bool | 期限切れかどうか。見積書は期限切れと同時に削除されるため、通常は 404 になります。このフィールドが true になるのは削除直前のごく短い間だけです |
quote_idが小文字の 16 進数 32 文字でない、または見積書が存在しない・期限切れ → 404not_found- 503
storage_unavailableは今は確認できないという意味で、見積書が期限切れになったことを意味しません。再試行してください
GET /v1/sources
現在どのソースがレートを供給しているか、それぞれの鮮度はどうかを返します。あるレートをどこまで信頼できるかの判断に使います。
レスポンス
| フィールド | 型 | 説明 |
|---|---|---|
sources |
object[] | 現在有効なソース |
source_count |
int | ソースの数 |
last_poll_at |
string | null | 最後に取得した時刻（ISO 8601 UTC） |
sources[] の各要素
| フィールド | 型 | 説明 |
|---|---|---|
provider |
string | 匿名のソースID。GET /v1/rate の sources[].provider と対応します |
label |
string | ソースの表示名 |
data_freq |
string | ソース自体のデータの更新頻度：realtime / hourly / daily |
last_fetch_at |
string | null | 当社がそのソースから最後に取得した時刻 |
last_fetch_age |
float | null | 最後の取得からの経過秒数 |
source_time |
string | null | ソース自身が主張するデータの時刻。null はソースがこれを公開していないことを示します |
source_age_seconds |
float | null | ソースのデータの経過秒数 |
currencies |
int | そのソースが現在扱っている対応通貨の数 |
この 2 つの時刻はまったく意味が違います。
last_fetch_atは当社がデータを取得した時刻なので、常に新しい値です。source_timeはソース自身がデータの時刻だと主張しているものです。日次ソースは通常 12〜36 時間遅れ、 週末には 80 時間を超える日次ソースもありますが、それは正常です。last_fetch_atだけで鮮度を判断すると大きく見誤ります。
GET /health
サービスのヘルスチェックです。APIキーは不要です。監視やロードバランサー向けです。
| フィールド | 型 | 意味 |
|---|---|---|
status |
string | ok / degraded。「今レートを出せるか」だけを表します |
sources_healthy |
int | 現在、新しく使えるデータを持つソースの数 |
last_updated_at |
string | null | 最も新しいソースデータを取得した時刻（ISO 8601 UTC） |
HTTP ステータス：ok なら 200、degraded なら 503。
このエンドポイントは意図的に単一のヘルスシグナルだけを返し、内部の取得状況や上流のエラー詳細は返しません。 ソースごとの鮮度は
GET /v1/sourcesか、稼働状況ページで確認してください。
GET /openapi.json
上記すべてのエンドポイントの OpenAPI 3.1 ドキュメントで、https://api.crestrate.com/openapi.json にあります。APIキーは不要で、ブラウザから取得でき（CORS 許可）、5 分間キャッシュされます。2 つの認証方式（X-API-Key と Bearer）の両方を宣言しているため、SDK ジェネレーターでそのまま使えます。
ウェブサイトの https://crestrate.com/openapi.json は、このアドレスへの HTTP 302 リダイレクトを返します。ツールにはAPIのアドレスを直接指定してください。
エラーレスポンス
エラーはすべてのエンドポイントで同じ形です。
| フィールド | 型 | 説明 |
|---|---|---|
error |
string | 機械可読なエラーコード。message ではなくこれで照合してください |
message |
string | 人が読むための英語の説明。文言は変わることがあります |
currency |
string | 問題の通貨コード（unsupported_currency、currency_not_available） |
supported |
string[] | リアルタイムデータを提供している通貨（currency_not_available） |
retry_after |
number | 待つべき秒数（rate_limited） |
used / quota |
int | 今月の使用リクエスト数 / 月間クォータ（quota_exceeded） |
upgrade_url |
string | 料金ページの絶対URL（quota_exceeded） |
| HTTP | error |
意味 | 再試行 |
|---|---|---|---|
| 400 | bad_request |
パラメータの欠落または不正：base/quote がない、amount がない・0 以下・数値でない・大きすぎる、不明な strategy、ボディが正しい JSON でない、reference が長すぎる |
不可。リクエストを修正してください |
| 400 | unsupported_currency |
認識できない通貨コード。currency が付きます |
不可 |
| 401 | api_key_required |
APIキーが送られていない | 不可。X-API-Key か Authorization: Bearer を送ってください |
| 401 | invalid_api_key |
キーが無効、または失効済み | 不可 |
| 403 | account_disabled |
アカウントが停止されている。サポートにご連絡ください | 不可 |
| 403 | email_not_verified |
アカウントのメールアドレスが未確認 | 確認後に可 |
| 404 | not_found |
見積書が存在しない・期限切れ、または存在しないパス | 不可 |
| 413 | payload_too_large |
リクエストボディが 16 KiB を超えている | 不可 |
| 422 | currency_not_available |
この通貨は現在リアルタイムデータを提供できない。currency と supported が付きます |
提供開始まで不可 |
| 429 | rate_limited |
レート制限を超えた。Retry-After ヘッダーと retry_after フィールドが付きます |
可。Retry-After の後で |
| 429 | quota_exceeded |
月間クォータを使い切った。used、quota、upgrade_url が付きます |
不可。アップグレードするか翌月まで待ってください |
| 500 | internal_error |
サーバー側の予期しないエラー | 可（バックオフして）。続く場合は X-Request-Id を添えてサポートへ |
| 503 | no_rate |
信頼できるレートを出すための有効なソースが足りない。message に各ソースの除外理由が入ります（匿名IDのみ） |
可（時間をおいて）。その間はお客様自身のレートで代替してください |
| 503 | storage_unavailable |
サービスが一時的に利用できない。何も保存されていません | 可（バックオフして） |
例：
{
"error": "currency_not_available",
"message": "Real-time data for GBP is temporarily unavailable. Supported: USD, JPY, EUR, HKD, CNY.",
"currency": "GBP",
"supported": ["USD", "JPY", "EUR", "HKD", "CNY"]
}
503 no_rate は意図的なものです。 出どころの怪しい価格を返すくらいなら、価格を返しません。呼び出し側は時間をおいて再試行するか、自前のバックアップレートにフォールバックしてください。0 として扱わないでください。
ベストプラクティス
strategy で正しい側を選んでください。 顧客から受け取るときはデフォルトの max、出品者やサプライヤーに支払うときは min、median は記帳専用です。選び間違えると、レート選択・スプレッド・端数処理がすべて相手側に有利に働きます。
レートは10進数型で解析し、浮動小数点は決して使わないでください。 すべてのレートと金額が JSON の文字列なのはまさにそのためです。
IEEE-754 倍精度で解析すると 0.05117904 は精度を失い、合計が少しずつずれていきます。
Decimal / BigDecimal / decimal.js / bcmath を使ってください。
受け取る前に必ず価格をロックしてください。 顧客が価格を見てから支払うまでに時間があり、その間にレートは動きます。
POST /v1/quotes はレート・スプレッド・金額を TTL が切れるまで固定し、後の照合に使う quote_id を返します。
GET /v1/convert は表示と見積もり専用です。注文には使わないでください。
rate_limited は再試行する価値があり、quota_exceeded はありません。 前者は一時的なので、Retry-After に従って待ってから再試行してください。
後者はその暦月の残り期間のハードブロックで、アカウントのすべてのキーに共通です。アップグレードするか、翌月のリセットを待ってください。
503 no_rate を決して 0 として扱わないでください。 これは「有効なソースが少なすぎて、責任を持てる価格を出せない」という意味です。
自前のバックアップレートにフォールバックするか、注文フローを一時停止してください。0 を掛けないでください。
通貨はお客様側でも検証してください。 リアルタイムデータを提供していない通貨を使ったリクエストもクォータに数えられます。呼び出す前に対応通貨の一覧と照合してください。
お客様側でキャッシュしてください。 レートは当社の最速のソースより速くは変わりません。30〜60 秒キャッシュするだけで、精度をほとんど損なわずに利用量を大幅に減らせます。
capped、floored、anchor_tier を監視してください。 capped: true や floored: true は、市場が動いているのに遅いソースが追いついておらず、当社が実勢レート側へ価格を戻したことを示します。
anchor_tier が daily や all に下がった場合は、最も新しいソースが一時的に使えない状態です。レートは引き続き使えますが、通常より鮮度が落ちます。
監視は文言ではなく error と excluded_code で照合してください。 message と excluded_reason は人が読むためのもので、言い回しが変わることがあります。
バージョニング方針
これは v1 で、バージョンはパスの一部（/v1）です。フィールドの追加は予告なく行うため、防御的に解析し、知らないキーは無視してください。
既存フィールドの削除や用途変更、フィールドの型の変更、エラーコードの意味や HTTP ステータスの変更は、90 日以上前の予告なしには行いません。 予告は、最近利用のあるすべてのお客様のアカウントのメールアドレスに送ります。
サポート
ご質問や、このドキュメントと異なる動作を見つけた場合は、該当リクエストの X-Request-Id を添えて [email protected] までメールでご連絡ください。