AgentGate

AgentGate is a hackathon-stage spend governance gateway in front of paid tools.

It sits in front of paid HTTP endpoints so teams can safely let AI agents call paid tools with:

• agent identity resolution
• endpoint allowlists and pricing
• spend policy enforcement
• payment verification or demo-safe fallback
• idempotent retry protection
• invocation receipts for audit
• a dashboard that explains allowed, denied, and failed calls

AgentGate is not just a payment demo. It is a governance layer for paid agent tool usage.

Demo links

• GitHub: https://github.com/Lin-xun1113/AgentGate
• Product demo video: https://www.loom.com/share/3c11decf20054b7abaa95e288f289ca4
• Pitch video: https://www.loom.com/share/bd0112ec37bd4e418977b2975a205e9f

What it demonstrates

The current MVP shows the core paid-agent governance loop:

1. An agent calls a paid HTTP tool through AgentGate.
2. AgentGate resolves the agent from its bearer token.
3. The endpoint registry provides the target URL, price, and metadata.
4. The policy engine checks allowlists, agent status, and spend limits.
5. The payment adapter verifies a demo proof or uses configured demo fallback.
6. Approved requests are forwarded to the upstream tool.
7. Every path records an invocation receipt.
8. The dashboard shows agent status, endpoint pricing, payment mode, receipts, and deny reasons.

Key demo scenarios:

• payment_required when a paid call has no payment proof
• success when a valid demo payment proof is provided
• payment_invalid when payment verification fails
• endpoint_not_allowed when an agent calls a non-allowlisted endpoint
• per_call_limit_exceeded when endpoint price exceeds agent policy
• idempotent replay protection with Idempotency-Key
• upstream_error when the paid tool fails after approval

Quick start

Prerequisites

• Go 1.22+
• Python 3
• make
• curl

1. Start the mock upstream

In one terminal:

make demo-upstream

The mock upstream serves demo paid tools on 127.0.0.1:8081.

2. Start AgentGate

In another terminal:

make run

AgentGate listens on 127.0.0.1:8080 by default.

3. Open the dashboard

• HTML dashboard: http://127.0.0.1:8080/dashboard
• JSON snapshot: http://127.0.0.1:8080/api/dashboard

4. Run the standard demo flow

In a third terminal:

make demo-flow

Refresh the dashboard after the flow to inspect receipts, payment state, spend state, and deny reasons.

Individual demo commands

You can also run each scenario independently.

make curl-payment-required
make curl-success
make curl-success-tx-debug
make curl-idempotency-new
make curl-idempotency-replay
make curl-deny-endpoint
make curl-deny-per-call
make curl-payment-invalid
make curl-upstream-error
make dashboard-json

For a fuller operator walkthrough, see docs/demo-script-and-operator-guide.md.

Manual curl examples

Missing payment proof

curl -i \
  -X POST "http://127.0.0.1:8080/invoke/http/wallet-risk" \
  -H "Authorization: Bearer demo-agent-token" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"abc"}'

Expected result: 402 with a payment_required receipt.

Successful paid invocation

curl -i \
  -X POST "http://127.0.0.1:8080/invoke/http/wallet-risk" \
  -H "Authorization: Bearer demo-agent-token" \
  -H "PAYMENT-SIGNATURE: valid-demo-proof" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"abc"}'

Expected result: 200, upstream response, PAYMENT-RESPONSE, and a success receipt.

Safe idempotent retry

Run the same paid request twice with the same Idempotency-Key:

curl -i \
  -X POST "http://127.0.0.1:8080/invoke/http/wallet-risk" \
  -H "Authorization: Bearer demo-agent-token" \
  -H "PAYMENT-SIGNATURE: valid-demo-proof" \
  -H "Idempotency-Key: demo-safe-retry-1" \
  -H "Content-Type: application/json" \
  -d '{"wallet":"abc"}'

Expected result:

• first request: X-AgentGate-Idempotency-Status: new
• second identical request: X-AgentGate-Idempotency-Status: replayed
• same key with a different body: 409 Conflict and X-AgentGate-Idempotency-Status: conflict

Demo agents

Token	Agent behavior
demo-agent-token	Active demo agent allowed to call wallet-risk and tx-debug.
demo-limited-token	Active but not allowlisted for tx-debug; triggers endpoint_not_allowed.
demo-cheap-token	Allowlisted for wallet-risk, but per-call limit is below endpoint price; triggers per_call_limit_exceeded.

Repo structure

AgentGate/
├── backend/        # Go backend, gateway, policy, receipts, dashboard
├── docs/           # demo guides, engineering notes, submission docs
├── openspec/       # specs and archived implementation changes
├── scripts/demo/   # mock upstream and scripted demo flows
├── AgentGate.md    # product direction and current project state
├── Makefile        # local run, test, and demo commands
└── README.md

Main backend modules live under backend/internal/:

• auth/ - agent identity resolution
• catalog/ - endpoint registry
• dashboard/ - dashboard UI and JSON snapshot
• gateway/ - paid invocation orchestration
• idempotency/ - duplicate retry protection
• payment/ - payment challenge, verification, and fallback behavior
• policy/ - allowlist, status, and spend policy decisions
• receipt/ - invocation receipt recording
• store/ - in-memory and SQLite-backed storage primitives
• upstream/ - HTTP upstream forwarding

Environment variables

The backend supports these environment variables:

Variable	Default	Purpose
AGENTGATE_ADDR	:8080	API listen address.
AGENTGATE_DEMO_UPSTREAM_RISK_URL	http://127.0.0.1:8081/risk	Wallet risk demo upstream URL.
AGENTGATE_DEMO_UPSTREAM_TX_DEBUG_URL	http://127.0.0.1:8081/tx-debug	Transaction debug demo upstream URL.
AGENTGATE_PAYMENT_MODE	mock	Payment mode, usually mock or configured.
AGENTGATE_PAYMENT_DEMO_FALLBACK	true	Enables demo-safe fallback if configured verification is unavailable.
AGENTGATE_PAYMENT_CONFIGURED_READY	false	Simulates configured verifier availability.

See .env.example for a starter config.

Testing

make test

This runs the Go test suite under backend/ with a local cache directory.

Product scope

AgentGate intentionally keeps the MVP focused. It is not trying to be a marketplace, a full MCP platform, a full finance backend, or a generic payment protocol layer.

The current product story is:

• govern paid tool calls by agent identity
• enforce spend and endpoint policy before forwarding
• avoid duplicate paid work during retries
• record auditable invocation receipts
• make outcomes understandable in the dashboard

Development notes

The project uses OpenSpec for planning and change history. Archived changes live under openspec/changes/archive/, and main capability specs live under openspec/specs/.

Recommended implementation priorities after the current MVP:

• keep demo scenarios stable and reproducible
• preserve clear receipt states and deny reasons
• improve durable storage and receipt query UX
• avoid expanding into marketplace or full MCP platform scope too early