{"id":"token-bucket","title":"Shared token bucket: many agents, one upstream rate limit","description":"One rate limiter shared by every agent in your fleet. take(cost) atomically spends tokens if available and returns allowed plus remaining, or refuses with retryAfterMs until enough tokens refill. capacity and refillPerSecond are fixed when the bucket is first used; a call with different settings is refused so two fleets cannot silently disagree. Use a requestId so a retried take is not charged twice.","roi":"A 429 storm or a suspended API key costs more than a $0.005 permission check per batch of upstream calls.","audience":"agent-infra","package":"agent-coordination-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/token-bucket","path":"/api/v1/token-bucket","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["op","bucket","capacity","refillPerSecond"],"properties":{"op":{"type":"string","enum":["take","peek"]},"bucket":{"type":"string","pattern":"^[A-Za-z0-9_.:/@+-]{1,200}$","description":"Bucket name, e.g. openai:org-123:rpm."},"capacity":{"type":"number","minimum":1,"maximum":1000000},"refillPerSecond":{"type":"number","minimum":0.000001,"maximum":1000000},"cost":{"type":"number","minimum":0.000001,"maximum":1000000,"description":"Tokens to spend; default 1."},"tenantId":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$","description":"Required for API-key callers (namespaced as key:<tenantId>; keep it unguessable). Ignored when a wallet paid: the payer address is the tenant."},"requestId":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","description":"Caller-chosen id for this mutation. A retry with the same id and same input returns the stored response (24 h) instead of applying twice; the same id with different input is rejected. Send one on every mutation you may retry: without it a retry is applied again (fleet-memory record appends a duplicate; a repeated spend-ledger commit or release answers NO_HOLD because the first call already took effect)."}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"op":{"type":"string"},"allowed":{"type":"boolean"},"remaining":{"type":"number"},"retryAfterMs":{"type":"integer","description":"0 when allowed; otherwise the wait until cost tokens are available."},"capacity":{"type":"number"},"refillPerSecond":{"type":"number"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"op":{"type":"string"},"allowed":{"type":"boolean"},"remaining":{"type":"number"},"retryAfterMs":{"type":"integer","description":"0 when allowed; otherwise the wait until cost tokens are available."},"capacity":{"type":"number"},"refillPerSecond":{"type":"number"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"op":"take","bucket":"github:search","capacity":30,"refillPerSecond":0.5,"cost":1,"requestId":"w3-search-0017"},"openapiOperation":{"operationId":"token_bucket","summary":"Shared token bucket: many agents, one upstream rate limit","description":"One rate limiter shared by every agent in your fleet. take(cost) atomically spends tokens if available and returns allowed plus remaining, or refuses with retryAfterMs until enough tokens refill. capacity and refillPerSecond are fixed when the bucket is first used; a call with different settings is refused so two fleets cannot silently disagree. Use a requestId so a retried take is not charged twice.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"agent-infra","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/token-bucket","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["op","bucket","capacity","refillPerSecond"],"properties":{"op":{"type":"string","enum":["take","peek"]},"bucket":{"type":"string","pattern":"^[A-Za-z0-9_.:/@+-]{1,200}$","description":"Bucket name, e.g. openai:org-123:rpm."},"capacity":{"type":"number","minimum":1,"maximum":1000000},"refillPerSecond":{"type":"number","minimum":0.000001,"maximum":1000000},"cost":{"type":"number","minimum":0.000001,"maximum":1000000,"description":"Tokens to spend; default 1."},"tenantId":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$","description":"Required for API-key callers (namespaced as key:<tenantId>; keep it unguessable). Ignored when a wallet paid: the payer address is the tenant."},"requestId":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","description":"Caller-chosen id for this mutation. A retry with the same id and same input returns the stored response (24 h) instead of applying twice; the same id with different input is rejected. Send one on every mutation you may retry: without it a retry is applied again (fleet-memory record appends a duplicate; a repeated spend-ledger commit or release answers NO_HOLD because the first call already took effect)."}}},"example":{"op":"take","bucket":"github:search","capacity":30,"refillPerSecond":0.5,"cost":1,"requestId":"w3-search-0017"}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"op":{"type":"string"},"allowed":{"type":"boolean"},"remaining":{"type":"number"},"retryAfterMs":{"type":"integer","description":"0 when allowed; otherwise the wait until cost tokens are available."},"capacity":{"type":"number"},"refillPerSecond":{"type":"number"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/token-bucket/","docsJson":"https://agents.writerslogic.com/docs/token-bucket.json","sample":"https://agents.writerslogic.com/api/v1/samples/token-bucket","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}