APIリファレンス

APIドキュメント

v1Operational

Prima Evidenceの存在証明をアプリケーションに統合するために必要なすべての情報。

Base URLhttps://api.primaevidence.com

はじめに

APIで最初のブロックチェーン証明まで4ステップ。

1

アカウント作成

開発者ダッシュボードでメールとパスワードでサインアップ。

2

APIキー生成

ダッシュボードからpk_live_...キーを作成。保存してください — 一度だけ表示されます。

3

クレジット購入

プリペイドクレジットを購入。1クレジット = 1証明。まとめ買い割引あり。

4

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_...の形式で、作成時に一度だけ表示されます。

API key format is validated server-side: must match pk_live_[a-f0-9]{64}

アーキテクチャ概要

Infrastructure

すべての証明は決定論的パイプラインを通過します — アプリケーションから永続的なブロックチェーンストレージまで。Cloudflareのグローバルエッジネットワークとアトミックな状態管理のためのDurable Objectsで構築。

01
1

Your Application

Compute SHA-256 hash of any file or data

02
2

Prima API

Validate hash, deduct credits atomically

03
3

Durable Object

State machine with retry logic

04
4

Arweave Blockchain

Immutable, permanent storage

テクノロジースタック

Cloudflare WorkersEdge compute
Durable ObjectsAtomic state
Arweave via IrysPermanent storage
SHA-256Hash standard
Edge-FirstGlobal <50ms
99.9%
API稼働率SLA
<60s
証明確認時間
<50ms
APIレスポンス時間

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.

processing

Hash submitted, Arweave upload in progress

confirmed

Permanently stored on Arweave blockchain

arweave.net/tx_id
failed

Upload failed — credits refunded automatically

Typical confirmation: <60 seconds

エンドポイント

単一の存在証明を作成。1クレジットを消費。ハッシュはArweaveブロックチェーンに永続的に保存されます。

Deducts 1 credit atomically — returns 402 if insufficient
Hash must be a valid 64-character hex SHA-256 string (case-insensitive, normalized to lowercase)
Duplicate hash returns 409 (no double-charge) — safe to retry on network timeouts
Status progresses: processing → confirmed (typically < 60 seconds)
Metadata: max 20 fields, keys ≤ 100 chars, values ≤ 500 chars
Returns X-Credits-Remaining and X-Credits-Used headers

リクエストボディ

{
  "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=...
proof.confirmed証明がArweaveに永続的に保存された時に発火
{
  "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"
}
proof.failedArweaveアップロードが失敗した時に発火 — クレジットは自動的に返金されます
{
  "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 request
X-Credits-UsedCredits consumed by this request (0 for read operations)
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the rate limit window resets

エラーコード

All errors return {"success":false,"error":"..."} with the appropriate HTTP status code.

401

無効または未指定のAPIキー

{"success":false,"error":"Valid API key required"}
402

クレジット不足 — 追加購入してください

Single: "Insufficient credits" | Batch: "Insufficient credits: need 5, have 3"
404

リソースが見つかりません — 証明IDが存在しないか、アカウントが初期化されていません

{"success":false,"error":"Proof not found"}
409

ハッシュは既に証明として存在しています

Single: "Hash already exists as a proof" | Batch: "Hash already exists: {hash}"
422

バリデーションエラー — リクエストボディの形式を確認してください

{"success":false,"error":"hash: Must be a valid SHA-256 hex string"}
429

レート制限超過 — 指定された期間後に再試行してください

{"success":false,"error":"Too many requests"} + Retry-After header
500

内部サーバーエラー — 継続する場合はサポートにお問い合わせください

{"success":false,"error":"Internal server error"}

トラブルシューティング

一般的なエラーとその解決方法。問題が続く場合はサポートにお問い合わせください。

401すべてのリクエストが401を返す
  • キーがpk_live_で始まり、正確に64文字の16進数が続くことを確認してください
  • Authorizationヘッダーの形式を確認: Bearer pk_live_...(Bearerの後にスペース)
  • 開発者ダッシュボードでキーが無効化されていないことを確認してください
409ハッシュは既に証明として存在しています
  • これは期待されるべき等性の動作です — 二重課金はされません
  • GET /api/v1/proofsを使用して、このハッシュの既存の証明を検索してください
  • 新しい証明を作成するには、ファイルの内容が異なる必要があります(異なるSHA-256ハッシュを生成)
402クレジット不足
  • GET /api/v1/accountまたはX-Credits-Remainingレスポンスヘッダーで残高を確認してください
  • primaevidence.com/developerで追加クレジットを購入してください
  • バッチリクエストの場合、残高がバッチ内のすべてのハッシュをカバーする必要があります(アトミック引き落とし)
429レート制限超過
  • Retry-Afterレスポンスヘッダーで待機秒数を確認してください
  • クライアントに指数バックオフを実装してください(SDKパターンセクションを参照)
  • エンタープライズプランでのより高いレート制限についてはサポートにお問い合わせください

レート制限

レート制限はAPIキーごとに適用されます。制限を超えるとRetry-Afterヘッダー付きの429が返されます。

POST /api/v1/proofs60 req/min
POST /api/v1/proofs/batch10 req/min
GET /api/v1/proofs/:id300 req/min
GET /api/v1/proofs60 req/min
GET /api/v1/account600 req/min

Rate 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

Recommended

Copy-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バージョン履歴と今後の機能。セマンティックバージョニングに従い、後方互換性のある変更を行います。

v1.0.02026-02-15Major Release

初期パブリックリリース

  • SHA-256証明作成とバッチ操作(リクエストあたり最大100件)のREST API
  • Irysバンドラーネットワーク経由のArweaveブロックチェーン永続ストレージ
  • まとめ買い価格ティア付きプリペイドクレジットシステム(最大20%割引)
  • プレフィックスベースの識別と即座取り消し対応のAPIキー認証
  • Webhook通知付きのリアルタイム証明ステータス追跡
今後の予定Roadmap
リトライ管理付きWebhook配信ダッシュボード
Node.js、Python、Go向け公式SDK
証明監査用バッチ検証エンドポイント
ロールベースAPIキー権限付きチームアカウント
APIドキュメント — Prima Evidence | Prima Evidence