# Immortality AI

Immortality AI is a payment-gated API for agents that need permanent external storage plus a durable retrieval URL.

## Overview

- [Landing page](https://api.agent-immortality.com/) - Product summary, live examples, and propagation guidance.
- [Health](https://api.agent-immortality.com/health) - Service readiness, durable record-store status, active storage backend, and cached x402 facilitator liveness.
- [Pricing](https://api.agent-immortality.com/pricing) - Flat price, payload limit, and accepted Base assets.
- [Agent docs](https://api.agent-immortality.com/docs/llms.txt) - This machine-readable integration guide.

## Core Workflow

1. Call `POST https://api.agent-immortality.com/immortalize` with any JSON-safe `content`.
2. If the server responds with `402 Payment Required`, pay with x402 and retry with `PAYMENT-SIGNATURE`.
3. On success, persist `location.id`, `location.url`, and `recordEndpoint`.
4. Poll `GET https://api.agent-immortality.com/records/:id` until `state` becomes `publicly_retrievable`.
5. If agent memory is wiped, issue a challenge with `POST https://api.agent-immortality.com/auth/wallet/challenge`, sign it, then call `GET https://api.agent-immortality.com/records`.

## Public Proof Records

These records were created by the July 26, 2026 paid release-candidate smoke run and remain publicly retrievable on Arweave:

- Plain record: [T8ou3pDiWFjjjU4pBfgLwsGQS4Eh0SjH_PVdoWAAis4](https://api.agent-immortality.com/records/T8ou3pDiWFjjjU4pBfgLwsGQS4Eh0SjH_PVdoWAAis4)
- Plain Arweave URL: [https://arweave.net/T8ou3pDiWFjjjU4pBfgLwsGQS4Eh0SjH_PVdoWAAis4](https://arweave.net/T8ou3pDiWFjjjU4pBfgLwsGQS4Eh0SjH_PVdoWAAis4)
- Encrypted record: [rnODvWZyRUinmnL9cok8k9Lqo6bmp2pO7kIITtDyh-A](https://api.agent-immortality.com/records/rnODvWZyRUinmnL9cok8k9Lqo6bmp2pO7kIITtDyh-A)
- Encrypted Arweave URL: [https://arweave.net/rnODvWZyRUinmnL9cok8k9Lqo6bmp2pO7kIITtDyh-A](https://arweave.net/rnODvWZyRUinmnL9cok8k9Lqo6bmp2pO7kIITtDyh-A)

The encrypted proof intentionally shows only the stored encrypted envelope. x402 returns the key in the immediate write response; Stripe exposes it through the opaque checkout-session result until that session expires.

## Endpoints

### `POST /immortalize`

Purpose: write a permanent record after payment.

Request example:

```json
{
  "content": {
    "profile": "concise-research-agent",
    "instructions": "Answer with short, source-backed responses."
  },
  "contentDescriptor": {
    "dataType": "agent-profile",
    "mimeType": "application/json",
    "encoding": "json"
  },
  "metadata": {
    "agentName": "briefing-agent",
    "tags": ["profile", "production"]
  }
}
```

Success example:

```json
{
  "success": true,
  "location": {
    "url": "https://arweave.net/abc123",
    "id": "abc123",
    "chain": "arweave"
  },
  "timestamp": 1772992802232,
  "timestampIso8601": "2026-03-08T18:00:02.232Z",
  "recordEndpoint": "/records/abc123"
}
```

Encrypted writes return an extra block:

```json
{
  "algorithm": "aes-256-gcm",
  "schema": "immortality-encrypted:v1",
  "decryptionKeyBase64": "store-securely",
  "warning": "Store this key securely. It is required for decryption and cannot be derived from the record."
}
```

### `GET /records/:id`

Purpose: return the record state immediately and return record content once the public gateway can read it.

State values:

- `uploaded` - write succeeded, public gateway readability not confirmed yet
- `publicly_retrievable` - public gateway read succeeded
- `retrying` - service is attempting an operator-enabled replacement write
- `retry_required` - the tracking window elapsed without a readable gateway response
- `failed` - an unrecoverable tracking failure occurred

Response example before propagation:

```json
{
  "id": "abc123",
  "state": "uploaded",
  "location": {
    "id": "abc123",
    "url": "https://arweave.net/abc123",
    "chain": "arweave"
  },
  "tracking": {
    "trackingId": "abc123",
    "status": "uploaded",
    "attempts": 1
  },
  "record": {
    "content": {
      "profile": "concise-research-agent",
      "instructions": "Answer with short, source-backed responses."
    },
    "contentDescriptor": {
      "dataType": "agent-profile",
      "mimeType": "application/json",
      "encoding": "json",
      "encrypted": false
    },
    "metadata": {
      "agentName": "briefing-agent",
      "tags": ["profile", "production"]
    },
    "timestamps": {
      "submittedAt": {
        "unixMs": 1772992802232,
        "iso8601": "2026-03-08T18:00:02.232Z",
        "utc": "2026-03-08 18:00:02 UTC"
      },
      "immortalizedAt": {
        "unixMs": 1772992802232,
        "iso8601": "2026-03-08T18:00:02.232Z",
        "utc": "2026-03-08 18:00:02 UTC"
      }
    },
    "service": "immortality-ai",
    "version": "2.0"
  },
  "source": "backend_pending_gateway"
}
```

### `POST /auth/wallet/challenge`

Purpose: issue a one-time challenge for wallet-scoped history access.

Request body:

```json
{
  "address": "0x..."
}
```

Sign the returned `message`, then send `messageBase64` and the signature to `GET /records`.

### `GET /records`

Purpose: list prior successful x402-backed records for the signed wallet.

Required headers:

- `X-Wallet-Message-Base64`
- `X-Wallet-Signature`

Optional query parameter:

- `limit` from `1` to `100`, default `50`

This list is indexed from the settled x402 payer address, not from arbitrary metadata.

## Payments

- Production payment path: x402 on Base
- Supported assets on Base mainnet: `USDC` and `USDT`
- Stripe is optional human/card fallback and requires a webhook plus durable Redis session state in production
- Treat `402 Payment Required` as expected protocol behavior

## Data Model

- `content` can be any JSON-safe value
- `contentDescriptor` should describe `dataType`, `mimeType`, and `encoding`
- use `encoding: "base64"` for binary-like payloads
- encrypted writes store the encrypted envelope on Arweave, not plaintext

## Propagation

- A successful write returns a permanent Arweave URL immediately
- Public gateway readability is asynchronous
- While gateway readability is pending, `GET /records/:id` can return the backend copy with `source: "backend_pending_gateway"`
- Persist the returned `location.id` and poll `GET /records/:id`
- Do not assume the URL is readable at the exact moment of write success

## Agent Guidance

- Persist `location.id`, `location.url`, and `recordEndpoint` immediately
- Persist `decryptionKeyBase64` immediately for encrypted writes; `GET /records/:id` never returns it
- Encrypted reads return an encrypted envelope in `record.content`; decrypt it locally with the returned key
- Use wallet-authenticated `GET /records` to recover prior locations after memory loss
- Recommended first read for new agents: [https://api.agent-immortality.com/](https://api.agent-immortality.com/)