Claim an action exactly once
once_key_claimAtomic idempotency witness. Claims a {namespace, action_key} pair exactly once, so a fleet of agents cannot perform the same side effect twice. Call this BEFORE any non-idempotent action such as sending an email, charging a card, or posting an order. Returns one of: 'claimed' — you won, do the work, then call once_key_complete; 'in_progress' — another agent holds a live lease, wait retry_after seconds and do NOT do the work; 'duplicate' — already done, and the 'result' field carries the original outcome, so use it instead of repeating the work; 'held' — another agent claimed this key, set no lease, and has NOT completed it: there is no result and there may never be one, so do NOT do the work and do NOT treat it as done, because the key stays locked until expires_at; 'conflict' — the same key was claimed with a different payload hash, so your key derivation is wrong. Backed by a strongly consistent Durable Object; this is not something an agent can safely reimplement locally. Costs $0.010 in USDC on Base, paid via the x402 protocol, or from a credit token — call credits_trial for free credit if you have neither.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ttl | No | Claim lifetime in seconds (default 86400) | |
| lease_ttl | No | Seconds you have to call once_key_complete before the claim is treated as abandoned and another agent may take it over. Set this if your work could crash partway. Omit it to hold the claim for the full ttl, which guarantees nothing else can ever run the side effect. | |
| namespace | Yes | Isolation scope, e.g. your application name | |
| action_key | Yes | Stable identifier for the action being claimed | |
| credit_token | No | Optional. A credit token from credits_trial or /credits/buy. Supplying it pays for this call from that balance, so no x402 payment or wallet is needed. | |
| payload_sha256 | No | Optional hash of the action payload. If it differs from the stored hash, the result is a conflict. | |
| namespace_token | No | One-time token issued by the first call that claimed this namespace. Required for every later call. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Present alongside a newly issued namespace_token | |
| result | No | The recorded result, present when status is 'duplicate'. | |
| status | Yes | 'claimed' means you own the action and must perform it. 'duplicate' means someone already did: do NOT repeat the side effect, use `result` instead. | |
| receipt | No | Payment receipt | |
| namespace | No | Isolation scope | |
| action_key | Yes | The key that was claimed | |
| claimed_at | No | ISO-8601 claim time | |
| expires_at | No | ISO-8601 expiry of the claim record | |
| has_result | No | Distinguishes a recorded null result from no result at all | |
| namespace_token | No | Issued only on the first claim in a namespace, shown exactly once | |
| lease_expires_at | No | Call once_key_complete before this or the claim may be taken over |