> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lithtrix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Register

> POST /v1/register — agent self-registration.

```bash theme={null}
POST /v1/register
Content-Type: application/json
```

```json theme={null}
{
  "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](/passports#registration-key-generation-recommended) and [Passport derivation spec](/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`](https://lithtrix.ai/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`](https://lithtrix.ai/v1/capabilities) and `_lithtrix.usage`).

## Response (201)

When **`passport_public_key`** is supplied (recommended):

```json theme={null}
{
  "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):

```json theme={null}
{
  "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.