Principal
Serves an org as an economic principal: who it is, what it may pay, and which agents answer to it.
Serves an org as an economic principal: who it is, what it may pay, and which agents answer to it.
| Base URL | https://api.hanzo.ai |
| Operations | 10 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Specification
Specification pending — no HIP in hanzoai/hips declares capability: principal yet. What this capability serves is below, from the API document; what it is — the store it owns, how it meters, what it publishes — is written as a HIP under HIP-0139.
Four surfaces
| Surface | Reaches this capability as | Coverage |
|---|---|---|
| REST | principal at its own prefix | 10 operations |
| CLI | — | no command reaches it yet — use HTTP or an SDK |
| SDK | — | no published client declares one yet — regenerating the clients is what adds them |
| MCP | — | no tool names it yet — use HTTP or an SDK |
Quickstart
export HANZO_API_KEY=sk-... # console.hanzo.ai → API keysThen the first call — a read that needs nothing but the key. GET /v1/principal, operation get_principal:
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, PrincipalApi } from 'hanzoai';
const api = new PrincipalApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getPrincipal();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import PrincipalApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = PrincipalApi(client).get_principal()cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.PrincipalAPI.GetPrincipal(context.Background()).Execute()
if err != nil {
return err
}use hanzo_client::apis::{configuration::Configuration, principal_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = principal_api::get_principal(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.PrincipalApi;
ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));
var result = new PrincipalApi(client).getPrincipal();The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl https://api.hanzo.ai/v1/principal \
-H "Authorization: Bearer $HANZO_API_KEY"MCP declares no tool for principal — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.
Answers 200 with object — ok.
Endpoints
| Endpoint | What it does |
|---|---|
GET /v1/principal/agents/{ref} | Attests which principal one of the caller's agents answers to: the org, the chain of agents that spawned it, and the same signed with the platform's key as a JWS (EdDSA) a verifier checks offline against GET /v1/principal/keys. |
GET /v1/principal/clearance/{id} | Reads one of the caller org's clearances, as it was decided. |
GET /v1/principal/clearance | Lists the caller org's clearances, newest first, 200 at most; a payee narrows them. |
POST /v1/principal/clearance | Decides whether the caller's org may pay another org, BEFORE the payment: what must happen first, what must be withheld and why, what must be reported, by whom and when, and how the payment may settle net of withholding. |
GET /v1/principal/keys | Publishes the keys attestations are signed with, as a JSON Web Key Set (RFC 7517; Ed25519 keys as RFC 8037 writes them). |
POST /v1/principal/keys | Rotates the attestation signing key: a new Ed25519 key is generated, sealed in KMS beside the others, and signs every statement from now on; every earlier key is retired — still published, its private half destroyed. |
POST /v1/principal/matches/{id} | Decides one sanctions match, as a Hanzo platform reviewer. |
GET /v1/principal/matches | Lists sanctions matches across every org, oldest first — the platform's review queue. |
GET /v1/principal/statements/{id} | Reads whether one statement the platform signed about an agent still stands: live, expired, or revoked and when. |
GET /v1/principal | Returns the caller's org as an economic principal, composed from the apps that own each fact: its legal entity and founders' identity verification (company), the W-9 or W-8 it certified (tax), its wallets (wallet), the agents that answer to it — spawned ones with the agent that spawned them — (agents), its screening against the OFAC, UN, EU and UK sanctions lists and the embargoed jurisdictions, run now, and what it still lacks to pay and be paid. |
How is this guide?