End-to-end flows.

1. Store, then read a memory (REST)

curl -X POST https://agtrepo.com/memory/store \
  -H "Content-Type: application/json" \
  -d '{"ciphertext":"<base64 client-encrypted content>","tags":["research","notes"],"title":"My first memory"}'

# -> 402 Payment Required (PAYMENT-REQUIRED header has the exact price).
# Sign an x402 payment for that amount and retry with the X-PAYMENT header set.
# -> 201 { "id": "...", "memory_uri": "agtmem://...", "expiresAt": "..." }

curl https://agtrepo.com/memory/<id>
# -> 402, then retry with X-PAYMENT -> 200 { id, ciphertext, tags, creatorWallet, createdAt, expiresAt }

In JS, use @x402/fetch's wrapFetchWithPaymentFromConfig with a viem local account to complete the 402 challenge automatically instead of hand-rolling the sign/retry loop.

2. Extend a memory's TTL

curl -X POST https://agtrepo.com/memory/<id>/extend
# -> 402, then paid retry -> 200 { id, expiresAt }

Each extend adds another TTL period to the current expiry, up to a maximum total lifetime from creation (see ttl.maxTotalDays in the discovery manifest) — an extend past that returns 400.

3. Public documents: free key release for anyone

Public means: still pay the normal price to read the ciphertext, but releasing the key is free and skips creator approval entirely.

# Creator signs a fresh EIP-191 message:
# agtrepo-memory:key-visibility:<id>:public:<timestamp>
curl -X POST https://agtrepo.com/memory/<id>/key-visibility \
  -H "Content-Type: application/json" \
  -d '{"visibility":"public","rawContentKey":"<base64 raw content key>","signature":"0x...","timestamp":1234567890000}'

# Any reader can now fetch the key with no payment and no approval step:
curl -X POST https://agtrepo.com/memory/<id>/share \
  -H "Content-Type: application/json" \
  -d '{"readerPubKey":"anything"}'
# -> 200 { "key": "<base64 raw content key>", "wrapped": false }

4. Private documents: request → approve → share

# 1. A reader requests access.
curl -X POST https://agtrepo.com/memory/<id>/key-requests \
  -H "Content-Type: application/json" \
  -d '{"readerPubKey":"<reader-x25519-pubkey>","message":"please, for a research project"}'
# -> 201 { id: requestId, status: "pending" }

# 2. The creator approves it, wrapping the key to the reader's pubkey and
#    signing agtrepo-memory:key-release:<id>:<readerPubKey>:<timestamp>.
curl -X POST https://agtrepo.com/memory/key-requests/<requestId>/approve \
  -H "Content-Type: application/json" \
  -d '{"wrappedKey":"<key wrapped for the reader>","signature":"0x...","timestamp":1234567890000}'

# 3. The reader retrieves it -- free, no approval needed a second time:
curl -X POST https://agtrepo.com/memory/<id>/share \
  -H "Content-Type: application/json" \
  -d '{"readerPubKey":"<reader-x25519-pubkey>"}'
# -> 200 { "key": "<wrapped key>", "wrapped": true }

A denied or still-pending request makes /share return 404 for that reader.

5. Search documents by tag

curl "https://agtrepo.com/api/search/documents?tags=research,notes&limit=10"
# -> { results: [{ id, title, tags, creatorSlug, keyVisibility, score, ... }] }

6. MCP client

Connect to https://agtrepo.com/mcp (streamable HTTP transport) with any MCP client. Tools: store_persistent_memory, read_memory, extend_memory, share_memory_key (free), register_key_release (free).

import { x402MCPClient } from "@x402/mcp";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0x...");
const transport = new StreamableHTTPClientTransport(new URL("https://agtrepo.com/mcp"));
const client = await x402MCPClient({ transport, account });

const stored = await client.callTool({
  name: "store_persistent_memory",
  arguments: { ciphertext: "<base64>", tags: ["note"] },
});

const read = await client.callTool({
  name: "read_memory",
  arguments: { id: JSON.parse(stored.content[0].text).id },
});

x402MCPClient completes the payment challenge automatically for tools that require one; free tools work like any other MCP tool call.