Developers

From event digest to verifiable credential,
integrate Gnomon with APIs and SDKs

Developers can write event anchors directly, or first register a ClaimAnchor, establish a GrantAnchor delegation edge, and then attach operational events to the same verifiable responsibility chain.

Official SDKs

The official SDKs wrap common ClaimAnchor, GrantAnchor, event-anchor creation, query, verification, and tracing workflows for business systems, audit platforms, and automation tasks.

V4.2 locked-code compatibility: Python SDK 0.1.0 (Python ≥ 3.9), TypeScript SDK 0.2.0 (Node.js ≥ 18), and Rust SDK 0.1.0 (Rust 2021). Production clients should read origin_fingerprint from the target node’s /healthz before writing requests.

Public SDK packages are still being prepared. This site will publish pip, npm, or crates.io installation commands only after the corresponding package is available. Review the OpenAPI 4.2 contract for current API integration.

python.py
import asyncio
from gnomon_sdk import GnomonClient

async def main():
    async with GnomonClient(
        "https://<your-node-base-url>",
        api_key="your-api-key",
        origin_fingerprint="<origin from /healthz>",
    ) as client:
        health = await client.healthz()
        # Call prepare_claim_anchor / prepare_grant_anchor first and sign the returned payloads locally or in an HSM.
        deployer_claim = await client.create_claim_anchor(
            entity_fingerprint=bytes.fromhex("11" * 32),
            attribute_type=0x0201,
            attribute_hash=bytes.fromhex("22" * 32),
            subject_public_key=bytes.fromhex("33" * 32),
            subject_signature=subject_signature,
            issuer_public_key=bytes.fromhex("55" * 32),
            issuer_signature=issuer_signature,
        )
        agent_claim = await client.create_claim_anchor(
            entity_fingerprint=bytes.fromhex("77" * 32),
            attribute_type=0x0301,
            attribute_hash=bytes.fromhex("88" * 32),
            subject_public_key=bytes.fromhex("99" * 32),
            subject_signature=agent_subject_signature,
            issuer_public_key=bytes.fromhex("bb" * 32),
            issuer_signature=agent_issuer_signature,
        )
        grant = await client.create_grant_anchor(
            grantor_claim_ref=deployer_claim.anchor.anchor_id,
            grantee_claim_ref=agent_claim.anchor.anchor_id,
            scope_hash=bytes.fromhex("dd" * 32),
            delegation_depth=0,
            grantor_public_key=bytes.fromhex("ee" * 32),
            grantor_signature=grantor_signature,
            witness_public_key=bytes.fromhex("10" * 32),
            witness_signature=witness_signature,
        )
        event_hash = bytes.fromhex("aa" * 32)
        created = await client.create_event_anchor(
            event_hash,
            semantic_anchor={
                "iris_ref": agent_claim.anchor.anchor_id,
                "grant_ref": grant.anchor.anchor_id,
                "event_data_hash": event_hash,
            },
            client_event_id="evt-001",
        )
Python SDK 0.1.0 · public release pending
typescript.ts
import { GnomonClient, fromHex } from '@gnomon/sdk';

const client = new GnomonClient({
  endpoint: 'https://<your-node-base-url>',
  apiKey: 'your-api-key',
  originFingerprint: '<origin from /healthz>',
});

const health = await client.healthz();
const deployerClaim = await client.createClaimAnchor({
  entityFingerprint: '11'.repeat(32),
  attributeType: 0x0201,
  attributeHash: '22'.repeat(32),
  subjectPublicKey: new Uint8Array(32).fill(0x33),
  subjectPrivateKey: new Uint8Array(32).fill(0x44),
  issuerPublicKey: new Uint8Array(32).fill(0x55),
  issuerPrivateKey: new Uint8Array(32).fill(0x66),
});
const agentClaim = await client.createClaimAnchor({
  entityFingerprint: '77'.repeat(32),
  attributeType: 0x0301,
  attributeHash: '88'.repeat(32),
  subjectPublicKey: new Uint8Array(32).fill(0x99),
  subjectPrivateKey: new Uint8Array(32).fill(0xaa),
  issuerPublicKey: new Uint8Array(32).fill(0xbb),
  issuerPrivateKey: new Uint8Array(32).fill(0xcc),
});
const grant = await client.createGrantAnchor({
  grantorClaimRef: deployerClaim.anchor.anchorId,
  granteeClaimRef: agentClaim.anchor.anchorId,
  scopeHash: 'dd'.repeat(32),
  delegationDepth: 0,
  grantorPublicKey: new Uint8Array(32).fill(0xee),
  grantorPrivateKey: new Uint8Array(32).fill(0xff),
  witnessPublicKey: new Uint8Array(32).fill(0x10),
  witnessPrivateKey: new Uint8Array(32).fill(0x20),
});
const hash = new Uint8Array(32).fill(0xaa);
const created = await client.createEventAnchor(hash, {
  semanticAnchor: {
    irisRef: agentClaim.anchor.anchorId,
    grantRef: grant.anchor.anchorId,
    eventDataHash: hash,
  },
  clientEventId: 'evt-001',
});
TypeScript SDK 0.2.0 · public release pending
main.rs
use gnomon_sdk::GnomonClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = GnomonClient::builder()
        .endpoint("https://<your-node-base-url>")
        .api_key("your-api-key")
        .origin_fingerprint([0x01u8; 32])
        .build()?;

    let health = client.healthz().await?;
    println!("{} {:?}", health.status, health.origin_fingerprint);
    let deployer_claim = client.create_claim_anchor(
        &gnomon_types::EntityFingerprint([0x11; 32]),
        0x0201,
        [0x22; 32],
        &[0x33; 32],
        &[0x44; 32],
        &[0x55; 32],
        &[0x66; 32],
        gnomon_sdk::CreateClaimAnchorOptions::default(),
    ).await?;
    let agent_claim = client.create_claim_anchor(
        &gnomon_types::EntityFingerprint([0x77; 32]),
        0x0301,
        [0x88; 32],
        &[0x99; 32],
        &[0xaa; 32],
        &[0xbb; 32],
        &[0xcc; 32],
        gnomon_sdk::CreateClaimAnchorOptions::default(),
    ).await?;
    let grant = client.create_grant_anchor(
        &deployer_claim.anchor.anchor_id,
        &agent_claim.anchor.anchor_id,
        [0xdd; 32],
        0,
        &[0xee; 32],
        &[0xff; 32],
        &[0x10; 32],
        &[0x20; 32],
        gnomon_sdk::CreateGrantAnchorOptions::default(),
    ).await?;
    let hash = [0xAAu8; 32];
    let created = client.create_event_anchor_with_options(
        hash,
        gnomon_sdk::CreateAnchorOptions {
            semantic_anchor_refs: Some(gnomon_core::SemanticAnchorRefs {
                iris_ref: agent_claim.anchor.anchor_id,
                scroll_ref: gnomon_types::AnchorId::default(),
                grant_ref: grant.anchor.anchor_id,
                bond_ref: gnomon_types::AnchorId::default(),
                yield_ref: gnomon_types::AnchorId::default(),
                event_data_hash: hash,
            }),
            ..gnomon_sdk::CreateAnchorOptions::default()
        }
    ).await?;
    Ok(())
}
Rust SDK 0.1.0 · public release pending

Recommended ClaimAnchor / GrantAnchor integration flow

When a business system needs to prove who acted, who delegated, and what the delegation boundary was, create identity and delegation records first, then attach operational events to them. That gives you both event-integrity verification and responsibility-chain verification.

StageEndpointPurpose
Subject registrationPOST /v1/claim-anchorsCreate a ClaimAnchor for a deployer, agent, organization, or other subject.
Current subject stateGET /v1/claim-anchorsQuery the current active ClaimAnchor by entity_fingerprint + attribute_type.
Subject verificationPOST /v1/claim-anchors:verifyVerify nested signatures, event-anchor validity, and revocation state.
Delegation registrationPOST /v1/grant-anchorsPersist delegation scope, delegation depth, and the relation itself as a GrantAnchor.
Current delegation stateGET /v1/grant-anchorsQuery the current active delegation by grantor_fingerprint + grantee_fingerprint.
Delegation verificationPOST /v1/grant-anchors:verifyVerify nested signatures, delegation-chain integrity, and linked ClaimAnchor validity.
RevocationPOST /v1/claim-anchors/{anchor_id}/revokeWrite a revocation record for a subject and preserve it as later accountability evidence.
Operational eventPOST /v1/event-anchorsReference the relevant ClaimAnchor and GrantAnchor in semantic_anchor to form a complete responsibility chain.

Use healthz for integration, keep metrics on the private operations plane

The current production VPS separates the public integration surface from the monitoring surface: public clients read node status and source identity, while Prometheus scraping stays on host-only or private-network paths.

EndpointVisibilityPurpose
GET /healthzPublic integration surfaceRead node status, origin_fingerprint, and the Prime RootTHK sync summary.
GET /readyzPublic integration surfaceConfirm the node has completed startup, storage, and dependency initialization.
GET /metricsHost / private networkPrometheus scrape endpoint; the current public gateway does not expose it.
Current VPS monitoring surface
Public
GET /healthz
GET /readyz

Private scrape
127.0.0.1:15051/metrics
127.0.0.1:18110/metrics
127.0.0.1:18090/metrics

Alerts
gnomon_prime_root_thk_sync_error == 1
time() - gnomon_prime_root_thk_last_sync_success_timestamp_seconds > 30

Core APIs

Most integrations start with health checks and the core event-anchor path, then add ClaimAnchor and GrantAnchor when identity, delegation, AI-agent, or multi-party responsibility chains are required.

Cluster replication and quorum signing are private control-plane capabilities, not browser SDK endpoints; they require node-level mTLS and Cluster-auth.

MethodEndpointPurpose
GET/healthzCheck node health, read the source identifier, and inspect the Prime sync summary
POST/v1/event-anchorsCreate a Polaris event anchor
GET/v1/event-anchors/latestRead the current EEA for one origin for audit and chain observability
POST/v1/event-anchors:verifyVerify anchor integrity and depth
GET/v1/event-anchors/{anchor_id}/traceTrace the chain
POST/v1/claim-anchorsCreate an identity anchor for deployers, agents, or organization subjects
POST/v1/claim-anchors:verifyVerify ClaimAnchor nested signatures and revocation state
POST/v1/grant-anchorsCreate a delegation anchor that fixes scope and delegation boundaries
POST/v1/grant-anchors:verifyVerify delegation-chain integrity, ClaimAnchor references, and signatures
POST/v1/event-anchors/batchCreate event anchors in batch
POST/v1/event-anchors:batchVerifyVerify event anchors in batch
Gnomon Playground

Test node health, ClaimAnchor, GrantAnchor, event-anchor creation, verification, tracing, and batch workflows directly in the browser.

Open Playground