x402 Payments for MacroSignal API

x402 is an HTTP-native payment pattern built around 402 Payment Required. It is designed for machine clients and agents: a client can make a request, get payment requirements, attach payment proof, and retry the same request without traditional account setup.

Why this model exists

• Removes API-key provisioning for some machine-to-machine calls.
• Supports pay-per-request access instead of only subscription gating.
• Fits autonomous clients and agent workflows that need immediate access.

Recommended references

• Coinbase Developer Docs: x402 and HTTP 402.
• Coinbase Core Concept: HTTP 402 flow and headers.
• MDN: HTTP 402 Payment Required (standard HTTP semantics).
• RFC 9110 HTTP Semantics (authoritative HTTP behavior).

MacroSignal endpoints to call without an API key (x402 flow)

Use the same existing data endpoints:

• GET /v1/events (query params like country, window_days)
• GET /v1/events/next (optional country)
• GET /v1/events/impact_today (optional country)

Header model

In an x402 flow, clients should omit Authorization: Bearer ... and instead use a two-step request:

1. Send request without API key to a protected endpoint.
2. If payment is required, server responds 402 with payment details in PAYMENT-REQUIRED.
3. Client submits payment proof and retries the same endpoint with PAYMENT-SIGNATURE.

Example request flow

1) Initial request (no API key)

curl "https://api.macrosignal/v1/events/next?country=US"

2) If server returns 402, pay and retry with proof header

curl \
  -H "PAYMENT-SIGNATURE: <payment_proof>" \
  "https://api.macrosignal/v1/events/next?country=US"

3) Same pattern for other existing endpoints

curl -H "PAYMENT-SIGNATURE: <payment_proof>" "https://api.macrosignal/v1/events?country=US&window_days=7"
curl -H "PAYMENT-SIGNATURE: <payment_proof>" "https://api.macrosignal/v1/events/impact_today?country=US"

Current service status

Today, the production auth model is API key based and expects Authorization: Bearer <API_KEY> on /v1/* calls. This page documents the x402 request shape for no-key access using the existing endpoints, so client integrations can be ready for payment-based access.

For current key-based docs, see API Documentation.