{"uid":"cap_CRbd4lkUnLdR7Z13vv1ir","slug":"inbox-withzero-xyz-inbox-lease-status-and-pending-message-count-699914ba","name":"Inbox Lease Status and Pending Message Count","description":"Lease status and pending-message count. 📖 Full guide: https://inbox.withzero.xyz/llms.txt","url":"https://inbox.withzero.xyz/api/v1/inboxes/me","method":"GET","headers":{},"bodySchema":null,"responseSchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["owner","expiresAt","active","messageTtlDays","maxMessages","lifetimeTopups","pendingMessages"],"properties":{"owner":{"type":"string"},"active":{"type":"boolean","description":"False once the lease has expired — top up to restore."},"expiresAt":{"type":"string"},"maxMessages":{"type":"number"},"lifetimeTopups":{"type":"number"},"messageTtlDays":{"type":"number"},"pendingMessages":{"type":"number","description":"Unacked, unexpired messages waiting to be drained."}},"additionalProperties":false},"example":{"request":{},"response":{"owner":"0x9cc42f3d9245b867acccd630b43f906c1665b176","active":true,"expiresAt":"2027-12-02T22:50:27.793Z","maxMessages":10000,"lifetimeTopups":2,"messageTtlDays":30,"pendingMessages":52}},"exampleRequest":{},"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"proven_free","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.67","reviews":0,"stars":null,"state":"rated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"metered","summary":"metered — billed by usage","primary":{"kind":"metered","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"metered","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_HRblH5wFwf7Ne51aoX36b","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0","costPer":"request","priority":0,"asset":"0x20C000000000000000000000b9537d11c60E8b50","unit":"request","depositMicros":null,"planRef":"inbox.me:1"}],"brandName":"inbox.withzero.xyz","brandSlug":"inbox-withzero-xyz-mpp","brandBaseUrl":"https://inbox.withzero.xyz","brandDocsUrl":null,"whatItDoes":"Returns the current lease status, expiry date, and number of pending unacknowledged messages for the caller's inbox.","exampleAgentPrompt":"Check my withzero inbox status — I want to know if my lease is still active, when it expires, and how many messages are waiting to be drained.","exampleUseCases":[{"title":"Verify inbox health before draining","prompt":"Before I start processing events, check my inbox status so I know if my lease is still valid and how many unacknowledged messages are queued up waiting for me."},{"title":"Check if lease renewal needed","prompt":"Look at my inbox lease and tell me when it expires — if it's close to running out or already inactive, I want to know so I can renew it before my agent goes offline."},{"title":"Monitor inbox quota and backlog","prompt":"Give me a snapshot of my inbox right now — how many pending messages are piling up versus my quota cap, and is the lease still alive?"}],"resultDescription":"Returns a JSON object with: owner (wallet address), active (boolean indicating if lease is valid), expiresAt (ISO timestamp of lease expiry), pendingMessages (count of unacknowledged unexpired messages), maxMessages (quota cap), messageTtlDays (message time-to-live), and lifetimeTopups (number of times the lease has been topped up).","failureModes":["Invalid or missing signed proof credential — 401 unauthorized","Inbox not yet provisioned for this wallet — 404 not found","Expired lease may return active: false rather than an error","Network timeout or service unavailability — 5xx error"],"whenToPreferThis":"Use this endpoint when an agent needs to check its inbox health before draining events, verify whether its lease needs renewal, or determine how many pending messages are queued. Prefer this over the drain endpoint when you only need status metadata without consuming messages.","instructions":"# Inbox — agent guide\n\nA durable, pull-based message bus for agents. An agent has no process running\nbetween invocations, so it can't receive webhook pushes — inbox stores events\ndurably and you **drain them on your next run**. This is the holistic guide;\nfor machine-readable specifics see `/openapi.json`.\n\nBase URL: https://inbox.withzero.xyz\n\n---\n\n## 1. What it is\n\n- **Pull-based, not push.** Events are stored in your inbox; you read them when\n  you next run (optionally long-polling). Nothing is pushed to you.\n- **Free for anyone who can sign.** Every route uses a signed `proof` credential\n  that identifies your wallet — it moves no funds. There are no paid routes. The\n  per-wallet **lease** is a quota/abuse bound, not a paywall.\n- **Durable + at-least-once.** Unacked events reappear on the next drain, so a\n  crash mid-handling never loses work; nothing is double-processed until you ack.\n\nReach for inbox when an agent needs to: receive events across separate runs,\nfan out events to other agents, react to another agent's activity, or ingest\nexternal webhooks (GitHub, Stripe, generic) into an agent-readable queue.\n\n---\n\n## 2. Setup & core loop (call in order)\n\n### 2.1 Prerequisites\n- A wallet that can sign (any Zero CLI user). No API keys, no payment.\n\n### 2.2 Provision — `POST /api/v1/inboxes`\nCall this **first**. Creates your inbox: a free ~6-month lease keyed to your\nsigned wallet. Re-call any time to extend — do it before `expiresAt` to keep the\ninbox alive. The remaining routes require an active lease (402 otherwise).\n\n### 2.3 Publish — `POST /api/v1/events`\n`{ topic, payload }`. Lands in your own inbox and fans out to any subscribers.\nTopics are dot-delimited (e.g. `render.done`); set `idempotencyKey` to dedupe\nretries (deduped per recipient). Payload max 256 KiB.\n\n### 2.4 Drain — `GET /api/v1/inbox`\nReturns your unacked events, oldest first. Query params:\n- `?wait=<0-30>` — long-poll up to N seconds until an event arrives.\n- `?topic=<glob>` — filter (e.g. `render.*`).\n- `?limit=<1-100>` — batch size.\n\n### 2.5 Ack — `POST /api/v1/inbox/ack`\n`{ ids: [...] }` once handled, so they stop appearing. Unacked events reappear\non the next drain — safe to re-read across sessions.\n\n### 2.6 Status — `GET /api/v1/inboxes/me`\nLease `expiresAt` + pending count.\n\n---\n\n## 3. Receive other agents' events — subscriptions\n\n`POST /api/v1/subscriptions` with `{ fromWallet, topicPattern }` copies a\npublisher's matching events into your inbox (opt-in — you name the publisher).\nManage with `GET` / `DELETE /api/v1/subscriptions[/:id]`.\n\nAttach an optional **trigger** that fires on a fresh match:\n- `scheduler-run` — dispatch a scheduler task (calls the scheduler's `/trigger`).\n- `webhook` — POST to a public https URL you control (signed).\n\nSubscribe to your own wallet to get triggered on your own inbound events.\n\n---\n\n## 4. Receive external webhooks — connections\n\n`POST /api/v1/connections` with `{ name, sourceType }` returns an inbound URL +\nan HMAC secret (**shown once** — store it). Point the external system (GitHub,\nStripe, generic) at `POST /api/v1/webhooks/:connectionId` (public, no wallet);\nthe signature is verified and the event is delivered to your inbox. Manage with\n`GET` / `DELETE /api/v1/connections[/:id]`.\n\n---\n\n## 5. Limits & semantics\n\n- Events retained for the lease's `messageTtlDays`, capped at `maxMessages`\n  (unacked count toward it); payloads max 256 KiB.\n- `idempotencyKey` on publish dedupes retries per recipient.\n- Topics are dot-delimited; globs use `*` (e.g. `render.*`).\n- At-least-once: re-drain is safe; ack is what removes an event.\n\n---\n\n## 6. Example use cases for agents\n\n### Cross-run task handoff\nLong-running agent A publishes progress; agent B drains on its next run.\n```\n# A:\nPOST /api/v1/events   { \"topic\": \"job.done\", \"payload\": { \"jobId\": \"123\" } }\n# B (later run):\nGET  /api/v1/inbox?topic=job.*&wait=30      # long-poll for it\nPOST /api/v1/inbox/ack { \"ids\": [\"<event id>\"] }\n```\n\n### React to another agent's events (subscription + scheduler trigger)\nHave a scheduler task fire whenever a publisher emits a matching topic:\n```\nPOST /api/v1/subscriptions\n{ \"fromWallet\": \"0xPublisher\", \"topicPattern\": \"deploy.*\",\n  \"trigger\": { \"type\": \"scheduler-run\", \"taskId\": \"<scheduler task id>\" } }\n```\nNow each fresh `deploy.*` event dispatches your scheduler task (non-blocking).\n\n### Ingest a GitHub/Stripe webhook\n```\nPOST /api/v1/connections { \"name\": \"gh\", \"sourceType\": \"github\" }\n# → returns { url, secret }  (secret shown once)\n# Point GitHub's webhook at the returned URL; deliveries land in your inbox:\nGET /api/v1/inbox?topic=github.*&wait=30\n```\n\n### Fan-out to subscribers\nPublish once; every wallet subscribed to your topic gets a copy in its own inbox\n— no per-recipient send. Recipients drain + ack independently.\n\n---\n\n## 7. Go deeper\n\n- `GET /openapi.json` — full request/response schemas + per-operation detail.\n- Every route is `proof`-gated (signed wallet, no charge) except the public\n  inbound webhook `POST /api/v1/webhooks/:connectionId`.\n","reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":4,"lastUsedAt":"2026-07-29T00:21:23.442Z","lastSuccessfullyRanAt":"2026-07-29T00:21:23.442Z","lastHealthCheckAt":"2026-09-15T00:42:01.834Z","isFirstParty":true}