開発者へ / アプリケーション API
アプリケーション API
四つのファーストパーティのサービスがチェーンの傍らにあります。どれもチェーンではなく、どれもバージョン管理されておらず、それぞれが自分なりの壊れ方をします。このセクションはそのためにあります。
これらが何であるか
チェーンのインターフェースは JSON-RPC です。これらのページにあるものはすべて、 アプリケーションが自分のために作り、そのまま到達可能にしておいたものです。シーケンサーの ログスプールの上の Postgres のインデックス、鍵を持つプロセス、ゲームのループ。便利で、 ファーストパーティで、そして権威ではありません。
ここからの読み取りは、チェーンからの読み取りではありません
ここにあるどの数値も、インデクサーかキャッシュか、その両方を通っています。止まった インデクサーは最後の状態で答え続け、応答のどのフィールドもそれを言いません。教えてくれるのは ヘルスのルートだけで、こちらから尋ねる必要があります。答えがお金を左右するなら、チェーンを 読んでください。
A read-only view of what the Pepper indexer has derived from the chain's logs: constant-product pools, concentrated pools, swaps, liquidity events and positions. It reads Postgres rather than the chain, deliberately.
- スタック
- Python, standard-library ThreadingHTTPServer, psycopg pool of at most 8 connections, HTTP/1.1
- マウント先
- /api/ on the Pepper origin
The archive the node deliberately is not. Blocks, mini-blocks, transactions, receipts, logs, call traces, decoded transfers, accounts, tokens, NFTs and the name-service record, all from a Postgres index fed by the sequencer's own log spool.
- スタック
- Python, standard-library ThreadingHTTPServer, psycopg pool of at most 12 connections, plus live reads against the node
- マウント先
- /api/ on the explorer origin
The only first-party service that WRITES to the chain. It holds the faucet operator key and submits the drip on your behalf, which is why the page needs no wallet.
- スタック
- Python, standard-library SimpleHTTPRequestHandler serving a static site as well as the API, signing with eth-account
- マウント先
- its own origin; the home origin re-exposes two of its routes
A WebSocket server for the games, with a small HTTP surface beside it for health and for the figures the site's chrome draws. The socket is the interface; the HTTP routes are a snapshot of it.
- スタック
- Node, `ws` in noServer mode behind a plain http server, one event loop for eight game rooms
- マウント先
- /api/ and /ws/ on the arcade origin
どこで応答するか
| サービス | ベース URL |
|---|---|
| エクスプローラー API | https://explorer.picklechain.xyz/api/ネームサービスとツールキットのサイトでも /api/ にマウントされています |
| Pepper DEX API | https://pepper.picklechain.xyz/api/同一オリジンのみ。別のオリジンのブラウザからは呼べません |
| フォーセット | https://faucet.picklechain.xyzホームのオリジンが POST /drip と GET /faucet-status を再公開します |
| Arcade | https://minigame.picklechain.xyz/api/ソケットは wss://minigame.picklechain.xyz/ws/<room> |
このうち自分のホスト名を持つサービスは一つもありません。どれもフロントエンドのオリジン上の /api/ へのマウントであり、だから公開のベースはサービスの事実ではなく nginx の 事実です。サイトを移す配備は、その API も一緒に移し、内側のパスは同じままです。自分で 動かすスタックでは、同じサービスがループバックで、それぞれのページが挙げるポートで 応答します。
四つのどれにも /v1 も、バージョンのヘッダーも、非推奨の方針もありません。 リポジトリに OpenAPI の文書も JSON Schema もないので、フィールドは二つの配備の間で形を 変えることがあり、照らし合わせるものがありません。守りを固めて読んでください。知らない キーは無視し、消えたキーで失敗しないこと。
認証
四つのどれも認証を取りません。重要なのは、認証なしでそれぞれに何ができるかの違いです。
- エクスプローラー、DEX API、アーケードは何も取りません。読み取り専用で 公開です。エクスプローラーはすべての POST に
405を返し、DEX API は GET 以外の 動詞を実装していません。 - フォーセットも何も取らず、そしてチェーンに書き込みます。その割り当てが 厳しく、何かに署名する前に確保される理由がまさにそれです。
アーケードのソケットには認証がなく、プロセスは鍵を持っています
その前に認証の層はなく、予定もありません。プロキシはアップグレードを転送し、それだけです。 守っているのは、接続のあらゆる次元、すなわち本数、オリジン、フレームの大きさ、メッセージの 頻度、バッファされたバイト数が制限されていること、そしてあふれたものはキューに積まれるので はなく捨てられることです。クライアントがそのソケットで言うことは何も権限を与えません。 誰が遊べるかを決めるのはコントラクトです。
ブラウザから呼ぶ
CORS はサービスごとに設定されていて、互いに一致していません。だから最初に確かめるべきは、 あなたのオリジンのページが目的のサービスをそもそも呼べるかどうかです。
- DEX API は CORS のヘッダーを送らず、OPTIONS のハンドラーもありません。ブラウザからのクロスオリジンの
fetchはそのまま失敗する一方、同じリクエストが サーバーからなら成功します。これはネットワークのせいにされがちな形のバグです。プロキシを 挟むか、バックエンドから呼んでください。 - エクスプローラーとフォーセットは許可リストを持ちます。リストにない オリジンからのプリフライトは
403で拒否され、少なくともはっきりした答えが 返ります。 - アーケードはアップグレードの時点で Origin を検査し、ハンドシェイクの前に
403で拒否します。だからソケットは、開いてから黙るのではなく、そもそも 開きません。
制限とページング
リクエストの頻度を制限するのはエクスプローラーだけです。ほかの三つは代わりに、 切り詰め、割り当て、接続数の上限に頼っています。
| サービス | 制限 |
|---|---|
| Pepper DEX API | `limit` is clamped to 1..500 on every list route and defaults to 50. There is no request-rate limit in the service. |
| Explorer API | 300 requests per minute per client address, then 429. Request bodies are capped at 600,000 bytes. Live streams are capped at 32 concurrent. |
| Faucet | Quota is reserved before the transaction is signed: 5 a day per address seen, 2 a day per funded address, 1000 a day in total. Request bodies are capped at 4096 bytes. |
| Arcade server | 256 sockets in total and 8 per source address, then the upgrade is refused 429. Inbound frames are 4 KiB at most and rate-limited per socket. A socket more than 512 KiB behind is cut. |
切り詰められた一覧は、黙って短い一覧です
DEX API にスワップを 1,000 件求めれば 500 件が返り、200 とともに、答えが 切られたと言うものは何もありません。エクスプローラーにブロックを 200 件求めれば 100 件が 返ります。どちらのサービスもほとんどの一覧のルートで総数を返さないので、自分のページの 長さと比べるフィールドがありません。もっとあることを示す唯一の合図は、ちょうど上限の数が 返ったことです。
ページングがあるところでは、カーソルではなく limit と offset です。 つまり先頭で伸びていく一覧は、二つのページの間であなたの足元をずらします。すでに見た行が また現れ、まだ見ていない行が飛ばされることがあります。完全でなければならないものについては、 オフセットではなく自分が制御できるキー、たとえばブロック番号やハッシュでページングして ください。
約束事
| 約束事 | Value |
|---|---|
| Versioning | None of them is versionedno /v1, no version header, no deprecation policy. A field can change shape between two deployments. Read defensively and pin nothing. |
| Schema | There is no OpenAPI documentand no JSON Schema anywhere in the repository. Every shape documented here was read out of a route handler, which is why each record names the line. |
| Errors | {"error": "..."}a human-readable string, occasionally with a second key. There are no error codes and no stable error strings - match on the HTTP status, never on the message. |
| Caching | cache-control: no-storeon every route of all four services, without exception. Nothing here is safe to cache, and nothing offers you an ETag to revalidate against. |
| Content type | JSONwith two exceptions: the explorer's logo route returns raw image bytes, and its live route is an event stream. |
| Units | not uniformtoken amounts and wei are DECIMAL STRINGS, not numbers, because they do not survive a double. Mini-block timestamps are in MICROSECONDS. Concentrated-pool swap amounts are SIGNED. |
金額は文字列で、一部は符号付きです
トークンの量も、wei も、残高も、どこでも十進の文字列として返ります。double では生き 残らないからです。多倍長整数の型で解析してください。集中プールのルートでは金額に符号も 付きます。どのスワップも片方の脚が負で、それが取引の向きを示します。だから絶対値を取らない 合計は、市場ひとつを丸ごとゼロに潰してしまいます。
// The shape of a careful call against any of these: a timeout, a status check
// before the body, and a big-integer parse of anything that looks like money.
const res = await fetch(`${BASE}/pools`, { signal: AbortSignal.timeout(5000) });
if (!res.ok) throw new Error(`pools: ${res.status}`); // never the message
const { pools } = await res.json(); // an object, not an array
const reserve0 = BigInt(pools[0].reserve0); // a decimal stringどれかが落ちたとき
四つはそれぞれ違う壊れ方をし、そのうち外から見て失敗らしく見えるのは一つだけです。
- DEX API は
503 index not readyを返します。データベースに 届かないか、インデクサーが一度も走っておらずテーブルが存在しない場合です。これは正直な ほうの場合です。不正直なほうは、インデクサーが止まった場合です。すべてのルートは 到達した状態で答え続け、それを言うのは/healthのlagBlocksだけ です。 - エクスプローラーはインデックスを提供し続けます。ノードに届かないとき、 生の読み取りを必要とする部分、つまり残高、ネームサービスのレコード、手数料ルーターの 未処理の残高は、エラーになるのではなく null か欠落として返ります。見るべき数値は
/statsのindexLagです。 - フォーセットは
502を返します。ノードが応答しない場合で、 何にも署名されていません。503は資金が尽きたか、drip が revert したことを 意味します。 - アーケードの
/readyは、ノードへのソケットが落ちているとき、 あるいは最後に適用したミニブロックが五秒より古いときに 503 を返します。代わりに 到着を測っていたときは、詰まったプロセスが何も動かないまま 200 を返せてしまいました。
書き込むのはフォーセットだけで、そこからの 502 は何も提出されていないことを 意味します。それは安全に再試行できます。トランザクションが出たあとの 503 は そうではありません。drip は着地しているかもしれず、割り当ての確保はすでに巻き戻されて いるので、送り直すのではなくチェーンにレシートを問い合わせてください。
ほかで記述されているもの
- The node. Chain state, transactions, logs and subscriptions are JSON-RPC and are documented in this reference's own RPC pages, not here.
- Contracts. What the pools, the faucet and the games actually do on chain - their functions, their events and their revert reasons - is the contract reference.
- Prices. Several answers here carry a dollar figure or a price snapshot. Those fields come from a layer this page does not own; read its own reference for what the number means, how old it is and when it is absent.