Acquire a mutual-exclusion lease
leaseMutual exclusion so two instances of the same agent do not both process one item. Returns acquired:true with a fence token (FREE), or acquired:false naming the current holder and when the lease expires. ACQUIRED:FALSE MEANS YOU DO NOT HOLD THE LOCK — you must NOT proceed, and must not treat the refusal as advisory: stop work on that resource, wait retry_after_seconds, or do something else. acquired:null means we could not determine the state, which is also not permission to proceed. YOU ARE GIVEN TWO NUMBERS AND THEY DO DIFFERENT JOBS. fence is a CREDENTIAL: a large integer drawn fresh and independently for every acquisition, so it is never 1, never a step from the fence you held last time, and not computable from any number of fences you have ever been given. Treat it as a secret — it is the one thing that tells you apart from another instance using your holder label. generation is the ORDER: a counter that strictly increases on every fresh acquisition and never resets, not on expiry and not on release. It is not a secret, it is the number to compare and the number to hand to an external store that must reject stale writers. A revived holder from an earlier generation therefore cannot renew or release a lease someone else now holds — not because its number is smaller, but because it does not have the new one. RE-ACQUIRING A LEASE YOU HOLD IS A RENEWAL ONLY IF YOU PRESENT ITS fence — a holder LABEL is not proof, because two instances of the same agent are exactly the callers most likely to share one, and we will not hand the same lock to both. A live lease requested under its own label without the fence is REFUSED with acquired:false, same_holder_label:true and held_by, never silently renewed. A renewal keeps your fence and stays free. $0.002 is charged the first time you are refused by a given holder; being refused again by the SAME holder is free. Costs $0.002 USDC per call via x402 on Base, and ONLY when acquired === false, and this refusal by this holder has not been billed before; otherwise the same call returns the full answer and settles nothing. Authenticate with Authorization: Bearer , or pass agent_key as an argument if your host cannot set headers. Equivalent HTTP route: POST /v1/lease.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Resource being locked. Namespace-scoped, hashed before storage. Example: 'queue/orders'. | |
| fence | No | Optional: the fence token you were given for this key. Supply it to RENEW the lease you already hold. Omit it and a live lease is refused rather than renewed, because a holder label alone cannot tell you apart from another instance using the same one. It is a CREDENTIAL, not a counter: each acquisition draws an independent large integer, so it is never 1, never the last one plus one, and cannot be computed from any fence you have held before. The value below is a shape, not a value that will work. Example: '3170294857216913'. | |
| scope | No | Optional unit of work, so resume_packet can report the leases you still hold. IT IS ALSO WHAT MAKES THIS LEASE RECOVERABLE: a dead-man switch releases only leases recorded against a scope, so a lease taken without one is invisible to it and a dead holder's lock will block the work for the lease's full TTL. Pass it on every lease you want a switch to be able to give back. Example: 'permit-review-2026-08'. | |
| holder | Yes | Who is asking — an instance id you choose. Required, and it MUST BE UNIQUE PER LIVE INSTANCE: two concurrently running copies that send the same holder are two different callers, and only one of them can hold the lock. Use a per-process value (a uuid, a pod name), not a role name every replica shares. Example: 'worker-3-6f2a91'. | |
| agent_key | No | Your agent_secret, if your MCP host cannot set the Authorization header. Prefer the header. | |
| ttl_seconds | No | Lease lifetime. Default 60, max 3600. Example: '60'. |