API Documentation

ProceedGate is a cost control API for AI agents. It blocks retry storms, enforces budgets, and gives you a kill switch before costs spiral.

Base URL

All endpoints are relative to this base URL.

Authentication

Authenticated endpoints require an API key sent as a Bearer token:

Authorization: Bearer pg_ws_your_api_key_here

Get an API key by signing up for free or subscribing to a paid plan.

The demo endpoint (/v1/demo/check) requires no authentication.

Quickstart

Try the API in 30 seconds — no signup needed:

curl -X POST https://governor.proceedgate.dev/v1/demo/check \
  -H "Content-Type: application/json" \
  -d '{
    "action": "llm_call",
    "task_hash": "my-test-task",
    "step_hash": "step-1"
  }'

Run it 11+ times in 60 seconds to trigger storm detection (HTTP 429).

POST /v1/governor/check

The main decision endpoint. Checks if an agent action should proceed, require payment friction, or be blocked.

Request

{
  "policy_id": "retry_friction_v1",
  "action": "tool_call",
  "actor": {
    "id": "agent:my-bot",
    "project": "my-project"
  },
  "context": {
    "attempt_in_window": 7,
    "window_seconds": 30,
    "confidence": 0.32,
    "tool": "web_scrape",
    "task_hash": "sha256:...",
    "step_hash": "sha256:..."
  },
  "idempotency_key": "unique-request-id"
}

Response — 200 (Allowed)

{
  "allowed": true,
  "decision_id": "dec_...",
  "proceed_token": "<jwt>",
  "expires_in_seconds": 45,
  "reason_code": "none",
  "policy": {
    "policy_id": "retry_friction_v1",
    "friction_required": false
  }
}

Response — 402 (Friction Required)

Returned when the agent should pay a micro-fee to continue (x402 protocol):

Header	Example
x402-price	0.004 USDC
x402-recipient	0x...
x402-chain	Base

{
  "allowed": false,
  "decision_id": "dec_...",
  "reason_code": "retry_friction",
  "policy": {
    "friction_required": true,
    "friction_price": "0.004 USDC",
    "explain": "attempt 7 in 30s window; free<=3"
  },
  "redeem": {
    "method": "POST",
    "url": "/v1/governor/redeem",
    "requires_header": "x402-tx-hash"
  }
}

Response — 429 (Storm Detected)

Hard block when loop detection identifies a retry storm (>10 identical requests/minute):

{
  "allowed": false,
  "reason_code": "loop_detected",
  "zone": "storm",
  "message": "Retry storm detected. Blocked for safety."
}

POST /v1/demo/check

No authentication required. Rate limited to 10 requests per minute per pattern.

curl -X POST https://governor.proceedgate.dev/v1/demo/check \
  -H "Content-Type: application/json" \
  -d '{"action": "scrape", "task_hash": "demo-1", "step_hash": "demo-1"}'

Use this to test storm detection without signing up.

POST /v1/governor/redeem

Submit an on-chain payment to unlock a blocked decision.

Request

// Headers:
x402-tx-hash: 0x...

// Body:
{
  "decision_id": "dec_..."
}

Response — 200

{
  "ok": true,
  "decision_id": "dec_...",
  "proceed_token": "<jwt>",
  "expires_in_seconds": 45,
  "receipt": {
    "tx_hash": "0x...",
    "paid_price": "0.004 USDC",
    "paid_chain": "base"
  }
}

POST /v1/billing/free

Create a free workspace. No payment required.

curl -X POST https://governor.proceedgate.dev/v1/billing/free \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response — 201

{
  "ok": true,
  "workspace_id": "ws_free_...",
  "api_key": "pg_ws_...",
  "plan": "Free",
  "credits": 2000
}

Free tier: 2,000 checks, 14-day trial, 1 project, 3-day log retention.

POST /v1/billing/subscribe

Create a paid subscription invoice. Returns a USDC payment address.

{
  "plan": "pro",
  "months": 6,
  "chain": "base",
  "email": "[email protected]"
}

Plans: starter ($19/mo), pro ($49/mo), scale ($99/mo). See pricing.

GET /.well-known/jwks.json

Standard JWKS endpoint exposing the public key(s) used to sign proceed tokens.

curl https://governor.proceedgate.dev/.well-known/jwks.json

Loop Detection

ProceedGate tracks request patterns and applies a 3-zone model:

Zone	Count	Behavior
Safe	≤ 5	Always allowed
Gray	6–10	AI decides based on behavioral signals
Storm	> 10	Hard block (429)

Behavioral Signals (Gray Zone)

Signal	Description
timing.interval_cv	Coefficient of variation. <0.15 = bot-like, >0.4 = human-like
timing.requests_per_sec	Request rate in the window
backoff_detected	True if intervals increase consistently (agents backing off get +3 threshold leniency)
cost_window_usd	Total USD spent in the window
similar_pattern_count	Similar-but-not-identical patterns grouped under the same action

Response Headers

Header	Description
X-Proceedgate-Zone	safe, gray, or storm
X-Proceedgate-Loop-Detected	true when blocked
X-Proceedgate-AI-Decided	true if AI model made the decision

Proceed Token (JWT)

Signed with ES256 (P-256). Verify via JWKS. Claims:

Claim	Description
iss	Issuer (API origin)
aud	agent-cost-governor
sub	Actor ID
jti	Decision ID
pol	Policy ID
act	Action
task	context.task_hash
step	context.step_hash
ctx	context.context_hash (when provided)
iat, exp	Issued at / Expiration

Policy Pack v1

retry_friction_v1

Applies economic friction after free attempts in a time window.

• Free attempts: 3
• Base price: 0.001 USDC, growth: 1.8x, max: 0.02 USDC

low_confidence_loop_v1

Charges more when confidence is low (agent is guessing).

• Threshold: 0.45
• Base price: 0.002 USDC, max: 0.05 USDC

Node.js SDK

npm install @proceedgate/sdk

import { ProceedGate } from '@proceedgate/sdk';

const gate = new ProceedGate({
  apiKey: 'pg_ws_...',
  baseUrl: 'https://governor.proceedgate.dev'
});

const decision = await gate.check({
  action: 'web_scrape',
  taskHash: 'scrape-product-list',
  stepHash: 'page-1'
});

if (decision.allowed) {
  // proceed with the action
} else {
  console.log('Blocked:', decision.reason_code);
}

MCP Server

Use ProceedGate as an MCP tool in Claude, Cursor, or any MCP-compatible AI:

npx @proceedgate/mcp-server --api-key pg_ws_...

Exposes check, balance, and status as MCP tools.