DocsSDKs

SDKs

1. Overview

Arkova provides official SDKs for TypeScript and Python. Both wrap the REST Verification API with typed interfaces.

Tip
SDKs are the recommended way to integrate. They handle authentication, retries, error parsing, and type safety.

2. TypeScript SDK

Installation

bash
npm install @arkova/sdk

Initialize

typescript
import { ArkovaClient } from '@arkova/sdk';

const arkova = new ArkovaClient({
  apiKey: process.env.ARKOVA_API_KEY!,
  // baseUrl: 'https://app.arkova.ai/api/v1' (default)
});

Verify a Credential

typescript
const result = await arkova.verify('ARK-2026-00091');

if (result.verified) {
  console.log(`Status: ${result.status}`);
  console.log(`Issuer: ${result.issuer_name}`);
  console.log(`Anchored: ${result.anchor_timestamp}`);
  console.log(`Network block: ${result.bitcoin_block}`);
}

Batch Verify

typescript
const results = await arkova.verifyBatch([
  'ARK-2026-00091',
  'ARK-2026-00092',
  'ARK-2026-00093',
]);

for (const r of results) {
  console.log(`${r.record_uri}: ${r.status}`);
}

Submit an Anchor

typescript
const anchor = await arkova.anchor({
  fingerprint: 'a1b2c3d4e5f6...64-char-hex',
  label: 'Bachelor of Science',
  credentialType: 'DIPLOMA',
  metadata: {
    issuer: 'University of Michigan',
    issuedDate: '2026-01-15',
  },
});

Check Usage

typescript
const usage = await arkova.usage();
console.log(`Verifications this month: ${usage.verify_count}`);
console.log(`Remaining quota: ${usage.remaining}`);

Error Handling

typescript
import { ArkovaError } from '@arkova/sdk';

try {
  await arkova.verify('ARK-INVALID');
} catch (err) {
  if (err instanceof ArkovaError) {
    console.log(err.status);  // 404
    console.log(err.code);    // "not_found"
    console.log(err.message); // "Credential not found"
  }
}

3. Python SDK

Installation

bash
pip install arkova

Initialize

python
from arkova import ArkovaClient

client = ArkovaClient(api_key="ak_live_...")

Verify a Credential

python
result = client.verify("ARK-2026-00091")

if result.verified:
    print(f"Status: {result.status}")
    print(f"Issuer: {result.issuer_name}")
    print(f"Network block: {result.bitcoin_block}")

Batch Verify

python
results = client.verify_batch([
    "ARK-2026-00091",
    "ARK-2026-00092",
])

for r in results:
    print(f"{r.record_uri}: {r.status}")

Submit an Anchor

python
anchor = client.anchor(
    fingerprint="a1b2c3d4e5f6...64-char-hex",
    label="Bachelor of Science",
    credential_type="DIPLOMA",
    metadata={
        "issuer": "University of Michigan",
        "issued_date": "2026-01-15",
    },
)

Error Handling

python
from arkova import ArkovaError

try:
    client.verify("ARK-INVALID")
except ArkovaError as e:
    print(e.status)   # 404
    print(e.code)     # "not_found"
    print(e.message)  # "Credential not found"

4. Common Patterns

Webhook Verification

typescript
import { verifyWebhookSignature } from '@arkova/sdk';

app.post('/webhook', (req, res) => {
  const isValid = verifyWebhookSignature(
    req.body,
    req.headers['x-arkova-signature'],
    process.env.WEBHOOK_SECRET!
  );
  if (!isValid) return res.status(401).send('Invalid signature');
  // Process event...
});

Retry Logic

Note
Both SDKs automatically retry on 429 (rate limit) and 503 (service unavailable) with exponential backoff. No manual retry logic needed.

Type Safety

Tip
The TypeScript SDK exports all response types. Import VerificationResult, AnchorResult, UsageResponse etc. for full IntelliSense support.