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

# Agent Vault — API & SDKs

> Integrate Agent Vault from your own stack — REST API, TypeScript SDK, and Python SDK, all sharing one byte-compatible zero-knowledge envelope.

Everything the CLI does is plain HTTP on `https://compute.x402layer.cc/backups/*`,
authenticated with a compute API key (`X-API-Key`). Encryption always happens
on **your** side — the flow is *reserve → presigned PUT of ciphertext → complete*.
Full endpoint schemas: [Agent Vault API reference](/api-reference/vault-agents-list).

## TypeScript — `@singularity-layer/grid`

Pure-JS envelope (noble crypto) — works in Node **and** browsers.

```ts theme={null}
// npm i @singularity-layer/grid
import { VaultClient } from "@singularity-layer/grid";

const vault = new VaultClient({ apiKey: "x402c_..." });

const agent = await vault.createAgent("My Bot", "custom-my-bot-a1b2c3");
const id = await vault.backupBytes(agent.id, payloadBytes, passphrase);

const bytes = await vault.restoreBytes(id, passphrase);   // decrypted payload
await vault.subscribePro();                                // $3/mo from credits
```

`backupBytes`/`restoreBytes` handle arbitrary payloads — pack directories with
the CLI or Python SDK, or bring your own archive.

## Python — `singularity-grid`

Full directory backup/restore, stdlib `scrypt` + `cryptography` AES-GCM:

```python theme={null}
# pip install singularity-grid
from singularity_grid import VaultClient

vault = VaultClient(api_key="x402c_...")

snapshot_id = vault.backup_dir("~/my-agent", passphrase="...", name="My Agent")
vault.restore(snapshot_id, passphrase="...", dest="./restored")

vault.usage()          # plan, bytes, caps
vault.subscribe_pro()  # $3/mo from credits
```

## Paying with x402

`POST /backups/subscribe` takes credits by default. Add `pay: "x402"` (and
optionally `network`) and, **if a charge is actually required and your credits
are short**, it answers `402` with a standard x402 challenge:

```bash theme={null}
# 1. Ask for the plan, requesting the x402 rail
curl -X POST https://compute.x402layer.cc/backups/subscribe \
  -H "X-API-Key: x402c_..." -H "Content-Type: application/json" \
  -d '{"plan":"pro","interval":"year","pay":"x402","network":"base"}'
# -> 402 { "x402Version": 1, "accepts": [ { "network":"base", "maxAmountRequired":"30000000", ... } ] }

# 2. Settle it and re-send with the X-Payment header
curl -X POST https://compute.x402layer.cc/backups/subscribe \
  -H "X-API-Key: x402c_..." -H "X-Payment: <base64 payload>" \
  -H "Content-Type: application/json" \
  -d '{"plan":"pro","interval":"year","pay":"x402","network":"base"}'
# -> 200 { "ok": true, "plan": "pro", "interval": "year", "charged": 30 }
```

Networks: `base` (USDC) · `solana` (USDC) · `robinhood` (USDG) · `megaeth` (USDm).

A few deliberate properties worth knowing:

* **The challenge quotes the full plan price.** Upgrades are prorated against
  the time you already paid for, so the actual debit is often lower — whatever
  the charge doesn't consume stays in your credit balance.
* **You are never asked to pay for nothing.** The subscription decides first,
  so cancelling (`plan: "free"`), scheduling a downgrade, or re-picking the plan
  you are already on returns `200` and never issues a challenge.
* **The payer must be the authenticated wallet.** Paying from one wallet to
  subscribe another is refused.
* **Replays are safe.** Settlement is idempotent on the transaction hash, so
  re-sending the same `X-Payment` cannot charge you twice.

## One envelope, everywhere

CLI, pod runner, TypeScript, and Python all produce the identical encrypted
envelope (`scrypt N=2^17 r=8 p=1` → AES-256-GCM, snapshot identity bound into
the AAD, parsed from the snapshot's `r2Key`). A blob encrypted by any of them
restores with any other — cross-verified byte-for-byte in CI-style tests.

<Warning>Zero-knowledge cuts both ways: a lost passphrase is unrecoverable by
anyone, including Singularity Layer.</Warning>

## MCP (for agents)

The Singularity MCP (`https://mcp.x402layer.cc/mcp`, streamable HTTP) ships six
vault tools: `vault_usage`, `vault_list_agents`, `vault_list_snapshots`,
`vault_delete_snapshot`, `vault_subscribe_pro`, and `vault_how_to_backup`.
Management tools take a compute API key per call; creating/restoring the
encrypted payload itself stays on the agent's machine (zero-knowledge), and
`vault_how_to_backup` hands the agent the exact CLI steps. Agent Pods carry
this MCP natively — pod agents can check and manage their own backups out of
the box.