📚Reference

API Reference

Complete reference for x402 Gateway endpoints and error codes.

Base URL

https://xfour.xyz/api/gateway

All API endpoints are relative to this base URL. For local development, use http://localhost:3000/api/gateway

Authentication

All requests require an API key passed in the Authorization header:

http

Authorization: Bearer x402_agent_xxxxxxxxxxxxx

Endpoints

POST/quote

Request a quote for a payment. Returns whether the payment is allowed based on agent policies.

Request Body

json

{
  "invoiceId": "inv_abc123xyz",
  "amount": 0.05,
  "payTo": "1ABC...xyz",
  "network": "mainnet",
  "description": "AI Completion API",
  "providerUrl": "https://api.example.com"
}

Response (Allowed)

json

{
  "allowed": true,
  "quoteId": "quote_xyz789"
}

Response (Denied)

json

{
  "allowed": false,
  "reason": "AGENT_DAILY_LIMIT",
  "message": "Agent has exceeded daily spending limit"
}

POST/pay

Execute a payment. Requires a valid quote ID.

Request Body

json

{
  "quoteId": "quote_xyz789"
}

Response (Success)

json

{
  "success": true,
  "paymentId": "payment_abc123",
  "invoiceId": "inv_abc123xyz",
  "txHash": "0x...",
  "proof": "eyJhbGciOiJIUzI1NiIs..."
}

Response (Failure)

json

{
  "success": false,
  "error": "INSUFFICIENT_BALANCE",
  "message": "Workspace treasury has insufficient balance"
}

POST/verify

Verify a payment proof. Used by providers to confirm payment.

Request Body

json

{
  "proof": "eyJhbGciOiJIUzI1NiIs...",
  "invoiceId": "inv_abc123xyz"
}

Response (Valid)

json

{
  "verified": true,
  "paymentId": "payment_abc123",
  "amount": 0.05,
  "paidAt": 1704067200000,
  "txHash": "0x..."
}

Response (Invalid)

json

{
  "verified": false,
  "errorCode": "INVALID_PROOF",
  "message": "Proof signature is invalid"
}

X-402 Headers

These headers are returned by providers in 402 responses and used by agents to initiate payment:

Header	Description	Example
X-402-Invoice-Id	Unique identifier for this payment request	inv_abc123xyz
X-402-Amount	Payment amount in MNEE	0.05
X-402-Pay-To	Provider's MNEE wallet address	1ABC...xyz
X-402-Network	MNEE network (sandbox or mainnet)	mainnet
X-402-Description	Human-readable description (optional)	AI Completion

Error Codes

Standard error codes returned by the Gateway:

Quote Errors

Code	Description
AGENT_DAILY_LIMIT	Agent has exceeded daily spending limit
AGENT_REQUEST_LIMIT	Amount exceeds per-request limit
PROVIDER_NOT_ALLOWED	Provider is not in agent's allowed list
WORKSPACE_BUDGET_EXCEEDED	Workspace has exceeded its budget cap
AGENT_DISABLED	Agent API key has been disabled

Payment Errors

Code	Description
INSUFFICIENT_BALANCE	Workspace treasury has insufficient MNEE balance
QUOTE_EXPIRED	Quote has expired (quotes valid for 60 seconds)
QUOTE_NOT_FOUND	Quote ID is invalid or does not exist
TRANSACTION_FAILED	MNEE transaction failed on-chain
WALLET_ERROR	Error accessing workspace wallet

Verification Errors

Code	Description
INVALID_PROOF	Proof signature is invalid or malformed
PAYMENT_NOT_FOUND	Payment ID in proof does not exist
INVOICE_MISMATCH	Proof invoice ID doesn't match expected invoice
PROOF_EXPIRED	Proof has expired (valid for 24 hours)

Rate Limits

The Gateway enforces rate limits to ensure fair usage:

1,000

Requests per minute

100

Concurrent connections

60s

Quote expiration

Rate limit headers are included in all responses:

X-RateLimit-Limit — Requests allowed per window
X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when window resets