This documentation is the product. There is no playground. There is no chat UI. If you want to evaluate HermesBridge, run the quickstart against a sandbox identity.

First signed request

This guide provisions a sandbox identity and makes an authenticated completion request. No API key string is used at any point.

This documentation is the product. There is no playground. There is no chat UI. If you want to evaluate HermesBridge, run the quickstart below against a sandbox identity.

1. Provision a sandbox identity

A sandbox identity is a self-attested HermesVault DID with a small daily quota. It is the free-tier-equivalent for evaluation. Registration is through vault.hermesbridge.ai.

# Install the HermesVault CLI
pip install hermesbridge

# Register a sandbox identity (self-attested, free tier)
hermesbridge vault register \
  --name "my-first-agent" \
  --tier self-attested \
  --output ~/.hermesbridge/identity.json

# Output:
# DID registered: did:hermes:0x7a3f9b2e4c1d8a6f
# Key ID: primary
# Attestation tier: self-attested
# Daily quota: 100,000 tokens
# Identity file saved to ~/.hermesbridge/identity.json

2. Install the SDK

The Python and TypeScript SDKs handle signing, DID resolution, and request construction. Direct HTTP is also supported — see Step 4.

# Python
pip install hermesbridge

# TypeScript / Node.js
npm install @hermesbridge/sdk

3a. Python

from hermesbridge import Agent

# Agent.from_vault() reads the identity file and initialises
# a signing context. No API key string is passed.
agent = Agent.from_vault(
    vault_url="vault://did:hermes:0x7a3f9b2e4c1d8a6f",
    key_id="primary",
)

response = agent.complete(
    model="auto",
    messages=[
        {"role": "system", "content": "You are a logistics coordination agent."},
        {"role": "user", "content": "Reroute shipment SH-4421 around the weather delay."},
    ],
    routing={
        "cost_ceiling_usd": 0.05,
        "latency_target_ms": 2000,
    },
)

print(response.choices[0].message.content)
print(f"Model used: {response.model}")
print(f"Agent DID: {response.usage.agent_did}")
print(f"Input tokens: {response.usage.prompt_tokens}")
print(f"Output tokens: {response.usage.completion_tokens}")

3b. TypeScript

import { Agent } from "@hermesbridge/sdk";

// Agent.fromVault() resolves the DID and initialises the signing context.
// No API key string is passed.
const agent = await Agent.fromVault({
  vaultUrl: "vault://did:hermes:0x7a3f9b2e4c1d8a6f",
  keyId: "primary",
});

const response = await agent.complete({
  model: "auto",
  messages: [
    { role: "system", content: "You are a logistics coordination agent." },
    { role: "user", content: "Reroute shipment SH-4421 around the weather delay." },
  ],
  routing: {
    costCeilingUsd: 0.05,
    latencyTargetMs: 2000,
  },
});

console.log(response.choices[0].message.content);
console.log(`Model used: ${response.model}`);
console.log(`Agent DID: ${response.usage.agentDid}`);
console.log(`Input tokens: ${response.usage.promptTokens}`);
console.log(`Output tokens: ${response.usage.completionTokens}`);

4. Raw HTTP

The full request format if building without an SDK. The X-Hermes-Signature header carries the versioned signing payload and signature. See /protocol for full construction details.

POST /v1/chat/completions HTTP/1.1
Host: api.hermesbridge.ai
Content-Type: application/json
X-Hermes-Signature: v1.eyJyZXF1ZXN0X2lkIjoiMDFKOFhNVksyUDRRN1I5U1RXWVozQUJDREUiLCJ0aW1lc3RhbXAiOiIyMDI2LTA1LTE5VDEyOjAwOjAwWiIsIm1ldGhvZCI6IlBPU1QiLCJwYXRoIjoiL3YxL2NoYXQvY29tcGxldGlvbnMiLCJib2R5X3NoYTI1NiI6ImUzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUiLCJhZ2VudF9kaWQiOiJkaWQ6aGVybWVzOjB4N2EzZjliMmU0YzFkOGE2ZiIsImtleV9pZCI6InByaW1hcnkiLCJhdHRlc3RhdGlvbl90aWVyIjoic2VsZi1hdHRlc3RlZCIsImNhcGFiaWxpdGllcyI6WyJjaGF0LmNvbXBsZXRpb25zIl0sIm5vbmNlIjoiYzdkNGU5ZjJhMWI4In0.3S1b_cT6UxkVKPmmwFGfDdJhrBl9gNv1O2bxZAqeY4WCsHmILRodPE8TjXyuNpM

{
  "model": "auto",
  "messages": [
    {"role": "system", "content": "You are a logistics coordination agent."},
    {"role": "user", "content": "Reroute shipment SH-4421 around the weather delay."}
  ]
}

Next steps