API Reference
Canister ID: lyksb-qiaaa-aaaae-aec2a-cai
certify
Update call · Requires API key
Create a blockchain-anchored attestation receipt for a credential hash.
Parameters
| Name | Type | Description |
|---|---|---|
| apiKey | Text | Your API key (vnd_sk_...) |
| credentialHash | Blob (32 bytes) | SHA-256 hash of the credential |
| erasedAt | Int | Timestamp in nanoseconds |
| metadata | ?Blob | Optional metadata (max 16KB) |
| idempotencyKey | ?Text | Optional key to prevent duplicates |
Returns
Result<Receipt, Error>
On success, returns the full Receipt object with ID, Merkle proof, and anchor info.
certifyBatch
Update call · Requires API key
Create multiple attestation receipts in a single API call. Tier-based batch size limits apply. Each receipt is billed individually. Rate limit counts as 1 call (not per receipt).
Parameters
| Name | Type | Description |
|---|---|---|
| apiKey | Text | Your API key (vnd_sk_...) |
| requests | [CertifyRequest] | Array of certify requests (max: Free=10, Pro=100, Scale=500, Enterprise=2000) |
Returns
Result<[CertifyResponse], Error>
On success, returns an array of CertifyResponse objects, one per receipt created.
Batch Size Limits
| Tier | Max per batch |
|---|---|
| Free | 10 |
| Pro | 100 |
| Scale | 500 |
| Auditor | 100 (verification batches) |
| Enterprise | 2,000 |
Billing
Each receipt in the batch counts individually toward your quota. A batch of 100 receipts = 100 receipts billed. The API call itself counts as 1 toward your rate limit.
Example
// TypeScript SDK
const results = await canister.certifyBatch(apiKey, [
{
credentialHash: hash1,
erasedAt: BigInt(Date.now()) * 1_000_000n,
metadata: [],
idempotencyKey: ["batch-001-item-1"],
},
{
credentialHash: hash2,
erasedAt: BigInt(Date.now()) * 1_000_000n,
metadata: [],
idempotencyKey: ["batch-001-item-2"],
},
]);
// results: Array of { receiptId, status, ... }
console.log(`Created ${results.length} receipts`);
// dfx equivalent:
// dfx canister call <canister-id> certifyBatch '(
// "vnd_sk_live_...",
// vec {
// record { credentialHash = blob "\ab\cd..."; erasedAt = 1707350400000000000 : int; metadata = null; idempotencyKey = opt "key-1" };
// record { credentialHash = blob "\ef\01..."; erasedAt = 1707350400000000000 : int; metadata = null; idempotencyKey = opt "key-2" };
// }
// )' --network icterminateAgent
Update call · Requires API key
Create a termination receipt for an AI agent lifecycle event.
Parameters
| Name | Type | Description |
|---|---|---|
| apiKey | Text | Your API key |
| agentId | Text | Unique agent instance identifier |
| reason | TerminationReason | #taskComplete, #timeout, #error, #userRequested, #resourceLimit, #superseded, #other(Text) |
| finalStateHash | ?Blob | Optional hash of agent's final state |
| taskSummary | ?Text | Optional summary of what the agent accomplished |
| durationSeconds | ?Nat | Optional agent runtime in seconds |
| parentAgentId | ?Text | Optional ID of parent agent (if spawned) |
| customMetadata | ?Blob | Optional metadata (max 16KB) |
Returns
Result<TerminateAgentResponse, Error>
On success, returns receiptId, terminatedAt (nanosecond timestamp), and agentId.
verify
Query call · No authentication required
Verify an attestation receipt by ID. Returns the full receipt and validation status.
Parameters
| Name | Type | Description |
|---|---|---|
| receiptId | Text | The receipt ID to verify |
Returns
Result<VerifyPublicResponse, Error>
verifyBatch
Query call · No authentication required
Verify multiple receipts in a single query. Max batch size limited by rate limits.
Parameters
| Name | Type | Description |
|---|---|---|
| receiptIds | [ReceiptId] | Array of receipt IDs to verify |
Returns
[VerifyBatchItemPublic]
listReceipts
Update call · Requires API key
List your receipts with cursor-based pagination.
Parameters
| Name | Type | Description |
|---|---|---|
| apiKey | Text | Your API key |
| limit | Nat | Maximum number of receipts to return |
| cursor | ?ReceiptId | Optional receipt ID to paginate from |
Returns
Result<[Receipt], Error>
getUsage
Update call · Requires API key
Get your API key's current usage and quota.
Parameters
| Name | Type | Description |
|---|---|---|
| apiKey | Text | Your API key |
Returns
Result<UsageResponse, Error>
getStats
Query call · No authentication required
Get public statistics about the canister.
Returns
{ totalReceipts: Nat; totalBatches: Nat; pendingReceipts: Nat }
health
Query call · No authentication required
Health check endpoint.
Returns
{ status: Text; version: Text }
getCertifiedAccumulator
Query call · No authentication required
Get the current certified hash-chain accumulator for independent verification.
Returns
{ accumulator: Blob; certificate: ?Blob; batchCount: Nat }
Rate Limits
| Tier | Monthly Quota | Requests/minute | Overage |
|---|---|---|---|
| Free | 250 | 60 | Blocked until next period |
| Pro ($99/mo) | 3,000 | 600 | Sliding scale (<1¢ each) |
| Scale ($299/mo) | 12,000 | 6,000 | Sliding scale (<1¢ each) |
| Auditor ($1/mo) | 0 (verification only) | 600 | N/A |
| Enterprise | Custom | Custom | Custom |
Verification queries are free and not counted against your quota.
Receipt Object
{
id: Text, // Unique receipt ID
credentialHash: Blob, // SHA-256 hash (32 bytes)
erasedAt: Int, // Timestamp (nanoseconds)
createdAt: Int, // When receipt was created
apiKeyId: Text, // ID of the API key used
batchId: ?Nat, // Merkle batch ID (when anchored)
merkleProof: ?[Blob], // Proof path (when anchored)
merkleRoot: ?Blob, // Batch root (when anchored)
metadata: ?Blob // Your optional metadata
}