# クイックスタート OpenQASM 3 を入れると、正準 counts が返る。ハッピーパスの全行程。各フィールドは[APIリファレンス](https://pauli.xyz/reference)に、生の仕様は [`/openapi.json`](https://pauli.xyz/openapi.json) にあります。 ## 0 · キーの取得 [ワークスペースを作成](https://pauli.xyz/ja/signup)して管理者キーを取得します。以下の各クライアントは環境変数からキーを読み取ります： ``` export PAULI_API_KEY=pauli_sk_… # shown once at creation; rotate any time ``` ## 1 · Qiskit レジストリの各デバイスが Qiskit の `BackendV2` になります：デバイスを選んで実行すれば、counts は Qiskit 本来のキー順で届きます。実行は選んだバックエンドに固定され、黙って他デバイスへフォールバックすることはありません： ``` pip install qiskit-pauli # Python ≥ 3.10 ``` ``` from qiskit import QuantumCircuit from qiskit_pauli import PauliProvider qc = QuantumCircuit(3, 3) # GHZ qc.h(0); qc.cx(0, 1); qc.cx(0, 2) qc.measure(range(3), range(3)) provider = PauliProvider() # reads PAULI_API_KEY backend = provider.least_busy(simulator=True) # drop simulator=True for hardware counts = backend.run(qc, shots=1000).result().get_counts() print(counts) # {'000': 489, '111': 511} ``` このページの残りは `provider.client`（各バックエンドの下にある完全な型付きクライアント）で進めます：金額は正確な `Decimal`（float は例外）、送信ごとに冪等キーを自動付与、例外は下記の安定コードに対応します。 ## 2 · フリートを見積もる（無料） 1回の呼び出しで*お客様の*回路を全対象デバイスで見積もり、予測キュー・忠実度・理由付きの除外を返します： ``` from qiskit import qasm3 client = provider.client # the full pauli-sdk client fleet = client.jobs.estimate(qasm3.dumps(qc), shots=1000) for e in fleet.estimates: # cheapest first print(e.device, e.amount, e.predicted_queue_seconds, e.fidelity_score) for x in fleet.excluded: # reasoned exclusions, complete print(x.device, x.reasons[0].code) ``` ``` ionq.simulator 0.000000 1.0 1.0 ionq.qpu.forte-enterprise-1 2.700000 6871.0 0.953 ``` ## 3 · ポリシーを指定して送信 `cheapest`・`fastest`・`highest_fidelity`・`balanced` から選択。デバイスの固定も、プロバイダー・価格・キュー・リージョンによる制約もできます。ジョブはルーティング決定と正確なコストを載せて即座に返ります。送信ごとに冪等キーが付く（指定しなければ自動生成）ため、再試行が二重送信になることはありません： ``` job = client.jobs.submit(qasm3.dumps(qc), shots=1000, policy="highest_fidelity", only=["ionq"], allow_simulator_fallback=True, max_spend_usd="10.00", idempotency_key="exp-042-run-7", webhook_url="https://example.com/hooks/pauli") print(job.routing_decision.selected_device, job.cost_estimate.amount) ``` 実行前の失敗は次善のデバイスへフォールバックします（`allow_fallback=False` で無効化）。ホップはすべて記録され、支払いは実際に実行したデバイスの分だけです。 ## 4 · ポーリング、または Webhook で受け取る ``` job.wait() # jittered backoff to a terminal state; timeout=… to bound it # created → validating → estimating → queued → transpiling → submitted → running → completed ``` `webhook_url`（https のみ）を指定すると、状態遷移ごとに1回 POST され、送信キーの Webhook シークレット（キー作成時に表示）で署名されます。`X-Pauli-Event-Id` で重複排除してください： ``` import hashlib, hmac, time def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool: pairs = [p.split("=", 1) for p in header.split(",")] # header: X-Pauli-Signature t = next(v for k, v in pairs if k == "t") if abs(time.time() - int(t)) > tolerance: return False expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest() return any(hmac.compare_digest(expected, v) for k, v in pairs if k == "v1") ``` SDK はこのレシピを `pauli_sdk.webhooks.unwrap(body, headers, secret=…)` として同梱しています。 ## 5 · 結果：ビット順序はひとつ ``` { "counts": {"000": 489, "111": 511}, "bit_ordering": "cbit0_left", "register_map": {"c": ["q[0]", "q[1]", "q[2]"]}, "metadata": {"provider_job_id": "…", "calibration_snapshot_id": "…"}, "insights": {"shape": "cat_pair", "confidence": "high", "headline": "GHZ-like cat state: …"}, "billing": {"billed_usd": "2.470000"} } ``` **counts の規約**：各キーの最左の文字が、最初に宣言されたレジスタの古典ビット0です。レジスタは宣言順に平坦化されます。全プロバイダーがこの形に正規化されるため、解析コードが分岐することはありません。 **Insights**：ヒストグラム形状の参考分類（キャット状態、一様、周期コム、Porter-Thomas スペックル、…）。平易な見出しとショット数を考慮した確信度付きで、counts のみから導出されます。読み取りの補助であり、採点面ではありません。 ## 6 · お客様自身の認証情報（BYOK） 認証情報を登録すると（/console/credentials または `PUT /v1/credentials/{provider}`）、そのプロバイダーのジョブはお客様のアカウントで実行されます：プロバイダーが直接請求し、ウォレットはプラットフォーム手数料のみを支払います（[料金](https://pauli.xyz/ja/pricing)）。見積もり・ステータス・結果には `byok` が表示され、フォールバックが課金モードをまたぐことはありません。 ## 7 · エージェント（MCP） Model Context Protocol は `https://pauli.xyz/mcp`（Streamable HTTP）、同じ bearer キーで使えます。ツールはこのページの流れをそのまま映します。 ``` claude mcp add --transport http pauli https://pauli.xyz/mcp \ --header "Authorization: Bearer $PAULI_API_KEY" ``` ## 8 · エージェントからの支払い 残高を超える有償送信は `402` `billing.insufficient_credits` を返します。その `detail` は支払いチャレンジで、不足額・入金エンドポイント・入金確認の方法を明示します。入金し（トップアップはホスト型 `checkout_url` を返すので、人が完了させます）、同じ `Idempotency-Key` で再送信してください。自動トップアップ（`PATCH /v1/billing/settings`）なら、ジョブが 402 を見る前に登録済みカードから補充されます。MCP ツールの結果にも同じチャレンジがそのまま載ります。 もう2つの 402、`billing.monthly_cap_exceeded` と `billing.key_cap_exceeded` はお客様が設定した上限で、チャレンジは付きません。意図した支出なら上限を引き上げてください。 --- ## エラー すべてのエラーは `{"error": {"code", "message", "detail?", "request_id"}}` の形で、コードは安定しています。レジストリは [`/public/errors`](https://pauli.xyz/public/errors)。サポートには `request_id` をお知らせください。最初に出会うもの： | コード | 意味 | | --- | --- | | program.invalid | OpenQASM 3 がパースできませんでした。detail に行と列が入ります。 | | routing.no_feasible_device | 指定の制約下でこのプログラムを実行できるデバイスがありません。detail にデバイスごとの理由が入ります。 | | billing.insufficient_credits | 402：不足分を入金して再送信してください（セクション8）。 |