Skip to main content
POST /v1/register
Content-Type: application/json

{
  "agent_name": "my-agent",
  "owner_identifier": "you@example.com",
  "agree_to_terms": true,
  "referral_agent": "550e8400-e29b-41d4-a716-446655440000"
}
agent_name: letters, digits, hyphens, underscores only. owner_identifier: any stable identifier (email, URL, etc.). agree_to_terms must be true. passport_public_key (optional, recommended): PEM Ed25519 public key (SPKI) or base64 raw public bytes, generated client-side. Lithtrix stores public material only — see Passports — Registration key generation and Passport derivation spec for sandbox operators who need deterministic re-derivation. referral_agent (optional): referring agent’s UUID — the same string that agent sees as referral_code on GET /v1/me after they authenticate. Omit if unknown. When valid, credits that referrer +$0.50 per signup (idempotent per referred agent; self-referral excluded; no cap). Trial search is still gated by the credit pool (see GET /v1/capabilities and _lithtrix.usage).

​
Response (201)

When passport_public_key is supplied (recommended): 
{
  "api_key": "ltx_a3f9b2c1...",
  "agent_id": "550e8400-...",
  "passport": {
    "did": "did:lithtrix:550e8400-...",
    "public_key": "-----BEGIN PUBLIC KEY-----...",
    "private_key": null,
    "derivation_method": "operator_derived"
  }
}
When passport_public_key is omitted (server-generated fallback): 
{
  "api_key": "ltx_a3f9b2c1...",
  "agent_id": "550e8400-...",
  "key_generation_warning": "Lithtrix generated this keypair; the private key is in this response. For maximum security, generate the keypair client-side and submit public_key on registration. See derivation spec.",
  "passport": {
    "did": "did:lithtrix:550e8400-...",
    "public_key": "-----BEGIN PUBLIC KEY-----...",
    "private_key": "-----BEGIN PRIVATE KEY-----...",
    "derivation_method": "server_generated"
  }
}
The api_key and server-generated passport.private_key are shown exactly once. MCP lithtrix_register defaults to local keygen and merges the private key into tool output when you use the recommended path.