Proxy Mode — Zero Code Integration

Overview

The Sentinel Proxy lets you add audit and compliance to any x402 payment by simply changing the endpoint URL. Instead of installing the SDK, you prefix your endpoint with sentinel.valeocash.com/proxy/ and add your API key as a header. That's it.

URL Pattern

# Original endpoint
https://weather-api.x402.org/forecast

# Through Sentinel Proxy
https://sentinel.valeocash.com/proxy/weather-api.x402.org/forecast

# Pattern
https://sentinel.valeocash.com/proxy/{host}/{path}

Authentication

The proxy requires a Sentinel API key for tracking. Pass it via header or query parameter:

# Via header (recommended)
curl -H "X-Sentinel-Key: sk_sentinel_xxx" \
     https://sentinel.valeocash.com/proxy/api.example.com/data

# Via query parameter
curl "https://sentinel.valeocash.com/proxy/api.example.com/data?sentinel_key=sk_sentinel_xxx"

Agent Identification

Identify which agent is making the request so Sentinel can track per-agent spend:

# Via header
curl -H "X-Sentinel-Key: sk_sentinel_xxx" \
     -H "X-Sentinel-Agent: researcher-01" \
     https://sentinel.valeocash.com/proxy/api.example.com/data

# Via query parameter
curl -H "X-Sentinel-Key: sk_sentinel_xxx" \
     "https://sentinel.valeocash.com/proxy/api.example.com/data?agent_id=researcher-01"

# If omitted, defaults to "proxy-default"

Response Headers

Sentinel adds tracking headers to every proxied response:

X-Sentinel-Record: pay_7kQ3mXvB9pLw   # Audit record ID
X-Sentinel-Agent: researcher-01        # Agent that made the request
X-Sentinel-Budget-Spent: $0.04/hr      # Hourly spend so far

All original response headers from the target endpoint are forwarded unchanged.

x402 Payment Flow

In the current version, the proxy works as a pass-through:

1. Your request is forwarded to the target endpoint.
2. If the endpoint returns 402 Payment Required, that response is passed back to you. Your client/wallet handles the payment signing.
3. When you retry with the Payment header, the proxy forwards it and captures the PAYMENT-RESPONSE header from the successful response.
4. The payment details (amount, tx hash, network) are extracted and logged as an audit record.

Error Handling

# Target unreachable
HTTP 502 { "error": "bad_gateway", "message": "Failed to reach api.example.com" }

# Target timeout (30s)
HTTP 504 { "error": "gateway_timeout", "message": "Failed to reach api.example.com" }

# Missing target URL
HTTP 400 { "error": "missing_target", "message": "No target URL provided" }

# Invalid API key
HTTP 401 { "error": "unauthorized", "message": "Valid X-Sentinel-Key header required" }

# Rate limit exceeded (100 req/min)
HTTP 429 { "error": "rate_limited", "message": "Max 100 requests per minute exceeded" }

CORS

The proxy includes CORS headers on all responses, allowing browser-based clients to use it directly:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
Access-Control-Allow-Headers: X-Sentinel-Key, X-Sentinel-Agent, Content-Type, Authorization, Payment

Proxy vs. SDK

Supported Methods

The proxy supports all HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS. Request bodies are forwarded as-is for methods that support them.

Rate Limits

The proxy enforces a rate limit of 100 requests per minute per API key. If exceeded, you'll receive a 429 response with a Retry-After: 60 header.