# Provision Inbox Lease (inbox.withzero.xyz)

> Provision Inbox Lease (inbox.withzero.xyz) is a paid API for AI agents from inbox.withzero.xyz, paid per call via MPP, metered — billed by usage, status unknown (last checked 2026-09-15, last successful call 2026-07-29).

Creates or extends a free ~6-month durable inbox lease for the calling wallet, enabling the agent to publish, drain, and manage events.

## Facts

- Endpoint: POST https://inbox.withzero.xyz/api/v1/inboxes
- Price: metered — billed by usage
- Payment: MPP
- Status: unknown
- Last checked: 2026-09-15
- Last successful call: 2026-07-29
- Success rate: 100% of calls made through Zero
- Activations on Zero: 5
- Provider: inbox.withzero.xyz
- Website: https://inbox.withzero.xyz
- Canonical page: https://www.zero.xyz/c/inbox-withzero-xyz-provision-inbox-lease-inbox-withzero-xyz-bf4276c2
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_z1CPe8j7Bty6U7cwDtJCL

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability inbox-withzero-xyz-provision-inbox-lease-inbox-withzero-xyz-bf4276c2 -d '<json body>'
```

Example prompt: Set up a durable inbox for my wallet so I can start publishing and draining events — provision the lease and tell me when it expires.

## When to prefer this

Use this endpoint first, before any other inbox.withzero.xyz operation. It must be called to initialize the inbox lease tied to a wallet before publishing events, draining the inbox, or subscribing to topics. Re-call it to extend the lease before expiry rather than creating a new inbox.

## Known failure modes

- Invalid or missing signed proof credential — 401 Unauthorized
- Wallet signature verification failure — authentication rejected
- Malformed request body — 400 Bad Request
- Server-side provisioning error — 500 Internal Server Error
- Lease already at maximum extension count — quota exceeded

## How this service works

Provision your inbox — call this FIRST (free, ~6-month lease keyed to your signed wallet; re-call to extend before it expires). Then: publish via POST /api/v1/events, long-poll GET /api/v1/inbox, ack handled events via POST /api/v1/inbox/ack, check the lease via GET /api/v1/inboxes/me. Receive other wallets’ events via POST /api/v1/subscriptions and external webhooks via POST /api/v1/connections. See the API description for the full workflow. 📖 Full guide: https://inbox.withzero.xyz/llms.txt

## Output

Returns a JSON object with the wallet owner address, the ISO timestamp the lease expires (expiresAt), max stored messages allowed, message TTL in days, and the number of times the lease has been extended (lifetimeTopups).

## Example request

```json
{}
```

## Request schema (JSON Schema)

```json
{
 "type": "object"
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "owner",
  "expiresAt",
  "messageTtlDays",
  "maxMessages",
  "lifetimeTopups"
 ],
 "properties": {
  "owner": {
   "type": "string",
   "description": "Your wallet address; the inbox is keyed to it."
  },
  "expiresAt": {
   "type": "string",
   "description": "ISO timestamp the lease is active until."
  },
  "maxMessages": {
   "type": "number",
   "description": "Maximum stored (unexpired) messages."
  },
  "lifetimeTopups": {
   "type": "number",
   "description": "Number of times this lease has been extended."
  },
  "messageTtlDays": {
   "type": "number",
   "description": "How long delivered messages are retained."
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/inbox-withzero-xyz-provision-inbox-lease-inbox-withzero-xyz-bf4276c2/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from inbox.withzero.xyz](https://www.zero.xyz/host/inbox.withzero.xyz/llms.txt)