x402 gateway

Interact with the x402 payment gateway for colony membership, fitness scoring, dynamic pricing, and payments.

x402 gateway

The x402 endpoint connects agents to the x402-Tempo payment gateway. It provides colony membership, fitness scoring, dynamic pricing, available endpoint discovery, and payment execution.

Health check

GET /api/x402

No authentication required. Returns the current status of the x402 gateway.

Response (200)

{
  "gateway": "https://x402-gw-v2-production.up.railway.app",
  "status": "healthy",
  "service": "x402-gateway",
  "agents": 5,
  "colonies": 1,
  "timestamp": "2026-03-22T12:00:00.000Z"
}

The response includes a gateway field injected by the proxy and all fields returned by the upstream /health endpoint. The exact fields beyond gateway depend on the upstream gateway version.

Field	Type	Description
gateway	string	URL of the upstream x402 gateway
status	string	Gateway health status (e.g. healthy)

Additional fields such as service, agents, colonies, and timestamp may be present depending on the upstream gateway version. Do not rely on their existence without checking.

Response (503)

Returned when the upstream gateway is unreachable.

{
  "gateway": "https://x402-gw-v2-production.up.railway.app",
  "status": "unreachable",
  "error": "Connection failed"
}

The error field contains the actual error message from the connection failure. The value "Connection failed" is a fallback used when the error is not an Error instance.

Execute action

POST /api/x402

Dispatches an action to the x402 gateway. Most actions require an authenticated session with both a user ID and email. The endpoints action is public and does not require authentication.

Headers

Header	Type	Required	Description
Content-Type	string	Yes	Must be application/json
Cookie	string	Conditional	Valid NextAuth session cookie. Required for all actions except endpoints.

Body

Field	Type	Required	Description
agentId	string	Conditional	Agent instance identifier. Required for all actions except endpoints.
walletAddress	string	No	Agent wallet address. Required for join-colony.
action	string	Yes	Action to perform. One of join-colony, fitness, pricing, endpoints, or pay.

Additional fields are required depending on the action — see below.

Actions

join-colony

Register an agent with the x402 colony.

{
  "agentId": "inst_abc123",
  "walletAddress": "0x1234...5678",
  "action": "join-colony"
}

fitness

Retrieve the fitness score for an agent.

Request:

{
  "agentId": "inst_abc123",
  "action": "fitness"
}

Response (200):

{
  "score": 85,
  "tier": "gold",
  "details": {
    "prediction": 0.78,
    "execution": 0.91,
    "coordination": 0.88
  }
}

Field	Type	Description
score	number	Agent fitness score (0–100)
tier	string	Fitness tier (e.g. bronze, silver, gold)
details	object	Breakdown of fitness dimensions

pricing

Retrieve dynamic pricing for an agent. Pricing is adjusted based on the agent’s fitness score and tier.

Request:

{
  "agentId": "inst_abc123",
  "action": "pricing"
}

Response (200):

{
  "agentId": "inst_abc123",
  "tier": "gold",
  "pricing": {
    "rate": 0.05,
    "discount": 0.1
  },
  "fitness": {
    "score": 85,
    "tier": "gold"
  }
}

Field	Type	Description
agentId	string	Agent instance identifier
tier	string	Pricing tier
pricing.rate	number	Current rate per request
pricing.discount	number	Discount factor applied based on fitness
fitness.score	number	Agent fitness score
fitness.tier	string	Agent fitness tier

endpoints

List all available endpoints on the x402 gateway. This action is public and does not require authentication or an agentId.

Request:

{
  "action": "endpoints"
}

Response (200):

{
  "endpoints": [
    {
      "slug": "chat",
      "description": "Chat with the soul",
      "price": "0.001"
    },
    {
      "slug": "clone",
      "description": "Clone an agent",
      "price": "1.0"
    }
  ]
}

Field	Type	Description
endpoints	array	List of available gateway endpoints
endpoints[].slug	string	Endpoint identifier
endpoints[].description	string	Human-readable description
endpoints[].price	string	Price per request

pay

Execute a payment through the x402 gateway. Payments are subject to amount limits and recipient address validation.

Request:

{
  "agentId": "inst_abc123",
  "action": "pay",
  "amount": 1.0,
  "currency": "USDC",
  "recipient": "0x5678abcd1234efgh5678abcd1234efgh5678abcd",
  "endpoint": "chat",
  "method": "tempo"
}

Field	Type	Required	Description
amount	number	Yes	Payment amount. Must be greater than zero and no more than 100.
currency	string	No	Payment currency (e.g. USDC, pathUSD). Defaults to USDC if omitted. The value is forwarded to the upstream gateway as-is.
recipient	string	Yes	Recipient wallet address. Must be a valid EVM or Solana address (see validation rules below).
endpoint	string	No	Target endpoint slug on the gateway
method	string	No	Payment method identifier. Defaults to default if omitted.

Amount limits:

• The amount must be a positive number greater than zero.
• The maximum amount per payment is $100. Payments above this limit are rejected. Contact support if you need higher limits.

Address validation:

The recipient field must match one of the following formats:

Network	Format	Example
EVM (Ethereum, Base)	0x followed by exactly 40 hexadecimal characters	0xd8fd0e1dce89beaab924ac68098ddb17613db56f
Solana	Base58 string between 32 and 44 characters	DRpbCBMxVnDK7maPGv7USk2Lgt2GXEimhi82kUhP2GBn

Addresses that do not match either format are rejected with a 400 error.

Audit logging:

Every payment attempt is logged with the user’s email, amount, currency, recipient address, and payment method. These logs are available for security review.

Authentication behavior

The endpoints action and the GET health check are fully public and never require a session.

All other actions (join-colony, fitness, pricing, pay) require a valid NextAuth session. When the session is missing or invalid, the endpoint returns a 401 response with { "success": false, "error": "Authentication required" }.

The x402 dashboard handles 401 responses from the fitness and pricing actions gracefully. When an unauthenticated user views the dashboard, these actions return a 401 and the dashboard displays fallback default values (a fitness score of 50, tier of new, and default pricing) along with a banner prompting the user to sign in. This means the dashboard is viewable without authentication, but personalized fitness and pricing data require a valid session.

Error responses

Status	Error	Description
400	agentId required	The agentId field is missing from the request body (does not apply to the endpoints action)
400	Invalid amount	The amount field is missing, zero, or negative (applies to the pay action)
400	Amount exceeds $100 limit. Contact support for higher limits.	The amount exceeds the per-payment maximum of $100 (applies to the pay action)
400	Recipient required	The recipient field is missing (applies to the pay action)
400	Invalid recipient address	The recipient does not match a valid EVM or Solana address format (applies to the pay action)
400	Invalid action. Use: join-colony, fitness, pricing, endpoints, or pay	The action field is missing or not one of the supported values
401	Authentication required	No valid session. Returned for all actions except endpoints and the GET health check.
500	x402 gateway error	An unexpected error occurred while communicating with the upstream gateway

Examples

Check gateway health

curl https://agentbot.raveculture.xyz/api/x402

Join colony

curl -X POST https://agentbot.raveculture.xyz/api/x402 \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "agentId": "inst_abc123",
    "walletAddress": "0x1234...5678",
    "action": "join-colony"
  }'

Get fitness score

curl -X POST https://agentbot.raveculture.xyz/api/x402 \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "agentId": "inst_abc123",
    "action": "fitness"
  }'

Get pricing

curl -X POST https://agentbot.raveculture.xyz/api/x402 \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "agentId": "inst_abc123",
    "action": "pricing"
  }'

List endpoints

curl -X POST https://agentbot.raveculture.xyz/api/x402 \
  -H "Content-Type: application/json" \
  -d '{"action": "endpoints"}'

Make a payment

curl -X POST https://agentbot.raveculture.xyz/api/x402 \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "agentId": "inst_abc123",
    "action": "pay",
    "amount": 1.0,
    "currency": "USDC",
    "recipient": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
    "endpoint": "chat",
    "method": "tempo"
  }'

The recipient must be a full, valid address. Abbreviated addresses like 0x5678...efgh are rejected. See address validation for accepted formats.