Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentcash.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Proxy architecture

Restructuring your backend and database to support agentic payments can be a daunting, time-consuming task — and in most cases it isn’t strictly necessary to bring your service online. The pattern below lets you add agentic commerce support with minimal changes to your production architecture.

​
Overview

You stand up a thin proxy in front of your existing backend. The proxy should handle everything x402/mpp-specific. Payment verification, wallet identity, per-wallet authorization, rate limiting, and discovery exist in this service while your production API stays untouched. 
Agent  ──(x402/MPP)──▶  Proxy  ──(API key)──▶  Production API
                          │
                          ├─ Payment verify
                          ├─ Wallet identity
                          ├─ Per-wallet authz
                          ├─ Rate limiting
                          ├─ Discovery doc
                          │
                          └─ Wallet mapping DB

​
How it works

Stand up a separate server — we typically use Next.js, but any HTTP framework works. Provision a single API key from your production backend with “god-mode” permissions: as much spend authority and as few rate limits as possible. The proxy then acts as a pure consumer of your production API, wrapping each endpoint you want to expose over x402/MPP with a corresponding payable endpoint on the proxy. All agentic traffic to your production backend appears under a single API key. The complexity of per-wallet accounting stays isolated in the proxy, so your original backend’s data model is unchanged.

​
Responsibility split

ConcernProxy serverProduction API
Payment verification (x402/MPP)✅—
Wallet identity✅—
Per-wallet authorization✅—
Per-wallet rate limiting✅—
Discovery document (/openapi.json)✅—
Business logic—✅
User records, billing, quotas—✅
Long-term data storage—✅
The proxy owns everything agent-specific. The production API owns everything you already had.

​
Wallet identity

Each x402 or MPP request carries a signed payment proof. The proxy verifies the signature and treats the signing wallet address as the caller’s identity. That wallet address becomes the primary key for anything you track per-caller: owned resources, rate limits, session state. If you also need free endpoints gated by wallet identity without payment, use SIWX (Sign-In with X). The signature flow is the same, but no funds move.

​
Wallet-aware authorization

Because every agent call reaches your production API under a single god-key, the proxy must enforce per-wallet authorization itself. The production API will happily return every row the key can see — it’s the proxy’s job to filter. For example, if your API exposes list_jobs():
  • ❌ Wrong: the proxy calls list_jobs() and returns the full response. This leaks every wallet’s jobs to every caller.
  • ✅ Right: the proxy looks up which job IDs belong to the calling wallet in its own database, fetches only those from the production API, and returns the filtered set.
The same rule applies to get_job, update_job, and delete operations — any endpoint that takes a resource ID must verify that the calling wallet owns that resource before proxying through.

​
Rate limiting

The god-key is intentionally provisioned with loose or absent rate limits so that legitimate agent traffic isn’t throttled. The tradeoff is that the proxy is now the only thing standing between an abusive wallet and your production backend. Apply per-wallet rate limits at the proxy by request count, by spend, or both.

​
Failure semantics

x402 and MPP settle payment as part of the request. If the downstream call to your production API fails after settlement, you have two options:
  1. Don’t settle on failure. Validate upstream health and cheap preconditions before accepting payment, and return 402 on predictable failures.
  2. Refund on failure. Catch downstream errors and issue a refund through the settlement network before returning 5xx to the caller.
Pick one policy per endpoint and document it. The worst outcome is silently charging a wallet for a failed request.

​
Wallet mapping database

If you need to track which wallets own which resources, a lightweight database alongside the proxy is usually enough. Common tables:
  • wallet_address → owned_resource_ids for ownership lookups.
  • wallet_address → usage_counters for rate limiting and spend caps.
  • wallet_address → session_state for stateful workflows.
All of this sits outside your production database. From the production API’s perspective, nothing changed and it still sees a single API key making calls.

​
Exposing discovery

The proxy is also where you serve your AgentCash discovery document. Publish /openapi.json on the proxy origin with x-payment-info and 402 responses on each payable operation. Agents discover and call the proxy and never the production API directly. See Server Discovery for the full OpenAPI contract.

​
When this pattern fits

✅ Good fit:
  • You want to expose existing endpoints over x402/MPP with minimal risk to production.
  • Your business logic is already accessible via a clean internal API.
  • Per-wallet state is shallow enough to live in a sidecar database.

​
Questions?

For further questions, contact us at team@merit.systems.