Swarm Rate Gate

Atomically consumes tokens from an opaque distributed bucket. The first consume locks capacity, refill cadence, and expiry; mismatched configurations and altered operation-key retries never consume tokens.

Use when

Several agents share one provider, API, or model token budget.
A distributed token bucket must make retry-safe decisions without exposing raw resource identifiers.

Do not use when

The provider itself already enforces the only required quota.
A durable billing ledger or account-level subscription is required.

Invocation contract

HTTP: /v1/tools/swarm-rate-gate
Version: 0.1.0
Mode: atomic
Idempotency: required
Retention: Only hashes of the namespace, key, and successful operation keys remain in Valkey until the gate's fixed expiry. Raw identifiers are never returned or stored; successful-operation deduplication is capped.
Tested with: Valkey 8, parallel consumers, HTTP/1.1, MCP Streamable HTTP

Positive and negative examples

{
  "input": {
    "action": "consume",
    "namespace": "provider:example.invalid",
    "key": "shared-api-budget",
    "capacity": 10,
    "refill_tokens": 2,
    "refill_interval_seconds": 30,
    "ttl_seconds": 600,
    "operation_key": "crawl-batch-42",
    "requested_tokens": 3
  },
  "output": {
    "action": "consume",
    "gate_hash": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "exists": true,
    "configuration_matches": true,
    "operation_matches": true,
    "operation_replayed": false,
    "decision": "allowed",
    "denial_reason": null,
    "requested_tokens": 3,
    "remaining_tokens": 7,
    "retry_after_ms": null,
    "capacity": 10,
    "refill_tokens": 2,
    "refill_interval_seconds": 30,
    "expires_at": "2026-07-24T12:10:00.000Z"
  },
  "negative": [
    {
      "scenario": "The provider itself already enforces the only required quota.",
      "expected_error": "INVALID_INPUT",
      "charged": false
    }
  ]
}

Deterministic errors

Code	Retry	Charged	Recovery
INVALID_INPUT	false	false	Correct the request to match input_schema.
TOOL_PAUSED	true	false	Wait for the operator to resume the tool.
RATE_LIMITED	true	false	Retry after the response Retry-After interval.
DEPENDENCY_UNAVAILABLE	true	false	Retry with the same idempotency identity.

Full machine manifest

The HTTP, OpenAPI, MCP, llms.txt, and ARD descriptions are generated from this same registry record.

Open JSON manifest →