APIリファレンス
APIドキュメント
v1OperationalPrima Evidenceの存在証明をアプリケーションに統合するために必要なすべての情報。
https://api.primaevidence.comはじめに
APIで最初のブロックチェーン証明まで4ステップ。
アカウント作成
開発者ダッシュボードでメールとパスワードでサインアップ。
APIキー生成
ダッシュボードからpk_live_...キーを作成。保存してください — 一度だけ表示されます。
クレジット購入
プリペイドクレジットを購入。1クレジット = 1証明。まとめ買い割引あり。
APIコール実行
SHA-256ハッシュを/api/v1/proofsにPOST。Arweaveに永続保存。
クイックスタート
30秒以内に最初の証明を作成:
Set your credentials before running examples:
# Add to your .env or export in terminal PRIMA_API_KEY=pk_live_YOUR_API_KEY PRIMA_BASE_URL=https://api.primaevidence.com
importort { createHash } fromm "crypto"ypto"; importort { readFile } fromm "fs/promises"/promises"; constst API_KEY = process.env.PRIMA_API_KEY!; constst BASE_URL = "https://api.primaevidence.com"tps://api.primaevidence.com"; // 1. Hash your file with SHA-2561. Hash your file with SHA-256 constst file = awaitit readFile("./document.pdf"document.pdf"); constst hash = createHash("sha256"a256").update(file).digest("hex"x"); // 2. Create proof via API2. Create proof via API constst response = awaitit fetch(`${BASE_URL}/api/v1/proofs`BASE_URL}/api/v1/proofs`, { method: "POST"ST", headers: { "Authorization"thorization": `Bearer ${API_KEY}`arer ${API_KEY}`, "Content-Type"ntent-Type": "application/json"plication/json", }, body: JSON.stringify({ hash, metadata: { title: "document.pdf"cument.pdf" }, }), }); if(!response.ok) { constst body = awaitit response.json().catchch(() => ({})); throwow new Error(body.error || `HTTP ${response.status}`TP ${response.status}`); } constst { data } = awaitit response.json(); console.log(`Proof ID: ${data.proofId}`oof ID: ${data.proofId}`); console.log(`Status: ${data.status}`atus: ${data.status}`); console.log(`Credits remaining: ${data.creditsRemaining}`edits remaining: ${data.creditsRemaining}`);
認証
ダッシュボードアクセス
/developerでメールとパスワードでサインインし、APIキー管理、クレジット購入、使用状況を確認。
API認証
すべてのAPIリクエストには、AuthorizationヘッダーにBearerトークンとして有効なAPIキーが必要です。
Authorization: Bearer pk_live_<64-hex-characters>
開発者ダッシュボードからAPIキーを生成します。キーはpk_live_...の形式で、作成時に一度だけ表示されます。
pk_live_[a-f0-9]{64}アーキテクチャ概要
Infrastructureすべての証明は決定論的パイプラインを通過します — アプリケーションから永続的なブロックチェーンストレージまで。Cloudflareのグローバルエッジネットワークとアトミックな状態管理のためのDurable Objectsで構築。
Your Application
Compute SHA-256 hash of any file or data
Prima API
Validate hash, deduct credits atomically
Durable Object
State machine with retry logic
Arweave Blockchain
Immutable, permanent storage
テクノロジースタック
Typical response times: POST /proofs ~200ms (includes atomic credit deduction), GET /proofs/:id ~100ms, GET /proofs ~150ms (scales with count). API-created proofs skip payment stages and begin at processing immediately.
Proof Lifecycle
Every proof progresses through a deterministic status pipeline. Typical confirmation time is under 60 seconds.
Hash submitted, Arweave upload in progress
Permanently stored on Arweave blockchain
Upload failed — credits refunded automatically
エンドポイント
単一の存在証明を作成。1クレジットを消費。ハッシュはArweaveブロックチェーンに永続的に保存されます。
リクエストボディ
{ "hash"sh": "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"fd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f", "metadata"tadata": { "title"tle": "Q4 Financial Report" Financial Report", "description"scription": "Quarterly earnings report SHA-256"arterly earnings report SHA-256" } }
レスポンス 200
{ "success"ccess": truee, "data"ta": { "proofId"oofId": "a3f8c2e1-7b4d-4e6f-9a1c-3d5e7f2b8c4a"f8c2e1-7b4d-4e6f-9a1c-3d5e7f2b8c4a", "hash"sh": "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"fd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f", "status"atus": "processing"ocessing", "creditsUsed"editsUsed": 1 "creditsRemaining"editsRemaining": 49 "createdAt"eatedAt": "2026-02-27T14:30:00.000Z"26-02-27T14:30:00.000Z" } }
例
curl -XPOSThttps://api.primaevidence.com/api/v1/proofs \ -H"Authorization: Bearer pk_live_YOUR_API_KEY"orization: Bearer pk_live_YOUR_API_KEY" \ -H"Content-Type: application/json"ent-Type: application/json" \ -d'{ "hash": "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f", "metadata": { "title": "Q4 Financial Report" } }' "hash": "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f", "metadata": { "title": "Q4 Financial Report" } }'
Webhookイベント
Live証明ステータスが変更された際にリアルタイム通知を受信。開発者ダッシュボードでWebhookエンドポイントを設定し、即座に更新を取得。
Webhook設定
開発者ダッシュボードでエンドポイントURLを登録します。すべてのWebhookペイロードは検証用にHMAC-SHA256で署名されます。
POST https://your-app.com/webhooks/prima Content-Type: application/json X-Prima-Signature: sha256=...
{ "event"ent": "proof.confirmed"oof.confirmed", "data"ta": { "proofId"oofId": "a3f8c2e1-7b4d-4e6f-9a1c-3d5e7f2b8c4a"f8c2e1-7b4d-4e6f-9a1c-3d5e7f2b8c4a", "hash"sh": "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"fd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f", "arweaveTransactionId"weaveTransactionId": "m787dI694Tv43-uPRDzdi6ZG..."87dI694Tv43-uPRDzdi6ZG...", "arweaveUrl"weaveUrl": "https://arweave.net/m787dI694Tv43..."tps://arweave.net/m787dI694Tv43...", "confirmedAt"nfirmedAt": "2026-02-27T14:30:45.000Z"26-02-27T14:30:45.000Z" }, "timestamp"mestamp": "2026-02-27T14:30:45.000Z"26-02-27T14:30:45.000Z" }
{ "event"ent": "proof.failed"oof.failed", "data"ta": { "proofId"oofId": "a3f8c2e1-7b4d-4e6f-9a1c-3d5e7f2b8c4a"f8c2e1-7b4d-4e6f-9a1c-3d5e7f2b8c4a", "hash"sh": "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"fd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f", "reason"ason": "Arweave upload timeout"weave upload timeout", "creditsRefunded"editsRefunded": 1 }, "timestamp"mestamp": "2026-02-27T14:35:00.000Z"26-02-27T14:35:00.000Z" }
署名検証
importort crypto fromm "crypto"ypto"; functionction verifyWebhookSignature( payload: string, signature: string, secret: string ): boolean { constst expected = crypto .createHmac("sha256"a256", secret) .update(payload) .digest("hex"x"); returnurn crypto.timingSafeEqual( Buffer.fromm(signature), Buffer.fromm(`sha256=${expected}`a256=${expected}`) ); } // Express/Hono handlerExpress/Hono handler app.post("/webhooks/prima"ebhooks/prima", (req, res) => { constst signature = req.headers["x-prima-signature"prima-signature"]; constst rawBody = JSON.stringify(req.body); if(!verifyWebhookSignature(rawBody, signature, WEBHOOK_SECRET)) { returnurn res.status(401).json({ error: "Invalid signature"valid signature" }); } constst { event, data } = req.body; switch (event) { case "proof.confirmed"oof.confirmed": console.log(`Proof ${data.proofId} confirmed on Arweave`oof ${data.proofId} confirmed on Arweave`); console.log(`TX: ${data.arweaveTransactionId}`: ${data.arweaveTransactionId}`); breakak; case "proof.failed"oof.failed": console.log(`Proof ${data.proofId} failed: ${data.reason}`oof ${data.proofId} failed: ${data.reason}`); breakak; } res.json({ received: truee }); });
Webhookは最大24時間、指数バックオフで再試行されます。エンドポイントは15秒以内に2xxを返す必要があります。配信失敗は開発者ダッシュボードに記録されます。
レスポンスヘッダー
すべてのAPIレスポンスには、クレジットとレート制限の情報がヘッダーに含まれます。
X-Credits-RemainingYour current credit balance after this requestX-Credits-UsedCredits consumed by this request (0 for read operations)X-RateLimit-LimitMaximum requests allowed in the current windowX-RateLimit-RemainingRequests remaining in the current windowX-RateLimit-ResetUnix timestamp when the rate limit window resetsエラーコード
All errors return {"success":false,"error":"..."} with the appropriate HTTP status code.
無効または未指定のAPIキー
{"success":false,"error":"Valid API key required"}クレジット不足 — 追加購入してください
Single: "Insufficient credits" | Batch: "Insufficient credits: need 5, have 3"リソースが見つかりません — 証明IDが存在しないか、アカウントが初期化されていません
{"success":false,"error":"Proof not found"}ハッシュは既に証明として存在しています
Single: "Hash already exists as a proof" | Batch: "Hash already exists: {hash}"バリデーションエラー — リクエストボディの形式を確認してください
{"success":false,"error":"hash: Must be a valid SHA-256 hex string"}レート制限超過 — 指定された期間後に再試行してください
{"success":false,"error":"Too many requests"} + Retry-After header内部サーバーエラー — 継続する場合はサポートにお問い合わせください
{"success":false,"error":"Internal server error"}トラブルシューティング
一般的なエラーとその解決方法。問題が続く場合はサポートにお問い合わせください。
- キーがpk_live_で始まり、正確に64文字の16進数が続くことを確認してください
- Authorizationヘッダーの形式を確認: Bearer pk_live_...(Bearerの後にスペース)
- 開発者ダッシュボードでキーが無効化されていないことを確認してください
- これは期待されるべき等性の動作です — 二重課金はされません
- GET /api/v1/proofsを使用して、このハッシュの既存の証明を検索してください
- 新しい証明を作成するには、ファイルの内容が異なる必要があります(異なるSHA-256ハッシュを生成)
- GET /api/v1/accountまたはX-Credits-Remainingレスポンスヘッダーで残高を確認してください
- primaevidence.com/developerで追加クレジットを購入してください
- バッチリクエストの場合、残高がバッチ内のすべてのハッシュをカバーする必要があります(アトミック引き落とし)
- Retry-Afterレスポンスヘッダーで待機秒数を確認してください
- クライアントに指数バックオフを実装してください(SDKパターンセクションを参照)
- エンタープライズプランでのより高いレート制限についてはサポートにお問い合わせください
レート制限
レート制限はAPIキーごとに適用されます。制限を超えるとRetry-Afterヘッダー付きの429が返されます。
POST /api/v1/proofs60 req/minPOST /api/v1/proofs/batch10 req/minGET /api/v1/proofs/:id300 req/minGET /api/v1/proofs60 req/minGET /api/v1/account600 req/minRate limits are tracked per API key. When exceeded, responses include a Retry-After header indicating seconds to wait. Note: POST and GET to /api/v1/proofs share the same 60/min counter. Contact support for higher limits.
セキュリティベストプラクティス
Best Practicesこれらの推奨事項に従い、統合をセキュアかつ本番対応にしましょう。
環境変数を使用
ソースコードにAPIキーをハードコードしないでください。ローカルでは.envファイル、本番では安全なシークレットマネージャーを使用。
定期的にキーをローテーション
定期的に新しいキーを生成。ローテーション後、開発者ダッシュボードから古いキーを即座に取り消し。
サーバーサイドのみ
クライアントサイドコード、モバイルアプリ、ブラウザJavaScriptにAPIキーを公開しないでください。常にバックエンドからAPIを呼び出し。
HTTPS強制
すべてのAPIエンドポイントはHTTPSを強制。HTTPリクエストは拒否されます。すべての接続にTLS 1.2以上が必要。
冪等な操作
重複ハッシュの送信は409 Conflictを返します。バッチ操作はアトミック — 部分的な失敗は発生しません。
エラーを適切に処理
429および5xxエラーに対して指数バックオフを実装。X-Credits-Remainingヘッダーを確認して402エラーを防止。
環境設定テンプレート
# .env.local — Prima Evidence API Configurationv.local — Prima Evidence API Configuration # Generate your API key at https://primaevidence.com/developererate your API key at https://primaevidence.com/developer PRIMA_API_KEY=pk_live_YOUR_API_KEY_HERE PRIMA_API_BASE=https://api.primaevidence.com PRIMA_WEBHOOK_SECRET=whsec_YOUR_WEBHOOK_SECRET # Optional: Override timeout (default 30s)ional: Override timeout (default 30s) PRIMA_TIMEOUT_MS=30000
SDK Pattern
RecommendedCopy-paste client class with typed methods, error handling, and exponential backoff polling. Production-ready for any language.
// npm install @prima-evidence/sdknpm install @prima-evidence/sdk importort { PrimaClient, PrimaApiError } fromm "@prima-evidence/sdk"rima-evidence/sdk"; importort { createHash } fromm "crypto"ypto"; importort { readFile } fromm "fs/promises"/promises"; constst prima = new PrimaClient(process.env.PRIMA_API_KEY!); // Hash a fileHash a file constst buffer = awaitit readFile("./contract.pdf"contract.pdf"); constst hash = createHash("sha256"a256").update(buffer).digest("hex"x"); // Create proof and wait for blockchain confirmationCreate proof and wait for blockchain confirmation constst { proofId, creditsRemaining } = awaitit prima.createProof(hash, { title: "Contract v2.1"ntract v2.1", }); console.log(`Proof created: ${proofId} (${creditsRemaining} credits left)`oof created: ${proofId} (${creditsRemaining} credits left)`); constst confirmed = awaitit prima.waitForConfirmation(proofId); console.log(`Arweave TX: ${confirmed.arweaveTransactionId}`weave TX: ${confirmed.arweaveTransactionId}`); // Batch create (up to 100 proofs atomically)Batch create (up to 100 proofs atomically) constst batch = awaitit prima.createBatch([ { hash: "a".repeat(64, metadata: { filename: "file1.pdf"le1.pdf" } }, { hash: "b".repeat(64, metadata: { filename: "file2.pdf"le2.pdf" } }, ]); console.log(`Batch: ${batch.count} proofs, ${batch.creditsUsed} credits used`tch: ${batch.count} proofs, ${batch.creditsUsed} credits used`); // List proofs with paginationList proofs with pagination constst proofs = awaitit prima.listProofs({ page: 1limit: 10 status: "confirmed"nfirmed" }); console.log(`${proofs.pagination.total} total proofs`proofs.pagination.total} total proofs`); // Error handlingError handling try { awaitit prima.createProof(hash); } catchch (error) { if(error instanceof PrimaApiError) { console.error(`${error.status}: ${error.message}`error.status}: ${error.message}`); if(error.status === 402) console.error("Buy more credits"y more credits"); if(error.status === 409) console.error("Hash already registered"sh already registered"); } }
変更履歴
APIバージョン履歴と今後の機能。セマンティックバージョニングに従い、後方互換性のある変更を行います。
初期パブリックリリース
- SHA-256証明作成とバッチ操作(リクエストあたり最大100件)のREST API
- Irysバンドラーネットワーク経由のArweaveブロックチェーン永続ストレージ
- まとめ買い価格ティア付きプリペイドクレジットシステム(最大20%割引)
- プレフィックスベースの識別と即座取り消し対応のAPIキー認証
- Webhook通知付きのリアルタイム証明ステータス追跡