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.
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 pendingimport { 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 pendinguse 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 pendingRecommended 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.
| Stage | Endpoint | Purpose |
|---|---|---|
| Subject registration | POST /v1/claim-anchors | Create a ClaimAnchor for a deployer, agent, organization, or other subject. |
| Current subject state | GET /v1/claim-anchors | Query the current active ClaimAnchor by entity_fingerprint + attribute_type. |
| Subject verification | POST /v1/claim-anchors:verify | Verify nested signatures, event-anchor validity, and revocation state. |
| Delegation registration | POST /v1/grant-anchors | Persist delegation scope, delegation depth, and the relation itself as a GrantAnchor. |
| Current delegation state | GET /v1/grant-anchors | Query the current active delegation by grantor_fingerprint + grantee_fingerprint. |
| Delegation verification | POST /v1/grant-anchors:verify | Verify nested signatures, delegation-chain integrity, and linked ClaimAnchor validity. |
| Revocation | POST /v1/claim-anchors/{anchor_id}/revoke | Write a revocation record for a subject and preserve it as later accountability evidence. |
| Operational event | POST /v1/event-anchors | Reference 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.
| Endpoint | Visibility | Purpose |
|---|---|---|
GET /healthz | Public integration surface | Read node status, origin_fingerprint, and the Prime RootTHK sync summary. |
GET /readyz | Public integration surface | Confirm the node has completed startup, storage, and dependency initialization. |
GET /metrics | Host / private network | Prometheus scrape endpoint; the current public gateway does not expose it. |
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.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /healthz | Check node health, read the source identifier, and inspect the Prime sync summary |
| POST | /v1/event-anchors | Create a Polaris event anchor |
| GET | /v1/event-anchors/latest | Read the current EEA for one origin for audit and chain observability |
| POST | /v1/event-anchors:verify | Verify anchor integrity and depth |
| GET | /v1/event-anchors/{anchor_id}/trace | Trace the chain |
| POST | /v1/claim-anchors | Create an identity anchor for deployers, agents, or organization subjects |
| POST | /v1/claim-anchors:verify | Verify ClaimAnchor nested signatures and revocation state |
| POST | /v1/grant-anchors | Create a delegation anchor that fixes scope and delegation boundaries |
| POST | /v1/grant-anchors:verify | Verify delegation-chain integrity, ClaimAnchor references, and signatures |
| POST | /v1/event-anchors/batch | Create event anchors in batch |
| POST | /v1/event-anchors:batchVerify | Verify event anchors in batch |