Skip to main content

​
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.
FieldTypeDescription
gatewaystringURL of the upstream x402 gateway
statusstringGateway 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
Requires an authenticated session with both a user ID and email. Dispatches an action to the x402 gateway.

​
Headers

HeaderTypeRequiredDescription
Content-TypestringYesMust be application/json
CookiestringYesValid NextAuth session cookie

​
Body

FieldTypeRequiredDescription
agentIdstringYesAgent instance identifier
walletAddressstringNoAgent wallet address. Required for join-colony.
actionstringYesAction 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
  }
}
FieldTypeDescription
scorenumberAgent fitness score (0–100)
tierstringFitness tier (e.g. bronze, silver, gold)
detailsobjectBreakdown 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"
  }
}
FieldTypeDescription
agentIdstringAgent instance identifier
tierstringPricing tier
pricing.ratenumberCurrent rate per request
pricing.discountnumberDiscount factor applied based on fitness
fitness.scorenumberAgent fitness score
fitness.tierstringAgent fitness tier

​
endpoints

List all available endpoints on the x402 gateway. Request: 
{
  "agentId": "inst_abc123",
  "action": "endpoints"
}
Response (200): 
{
  "endpoints": [
    {
      "slug": "chat",
      "description": "Chat with the soul",
      "price": "0.001"
    },
    {
      "slug": "clone",
      "description": "Clone an agent",
      "price": "1.0"
    }
  ]
}
FieldTypeDescription
endpointsarrayList of available gateway endpoints
endpoints[].slugstringEndpoint identifier
endpoints[].descriptionstringHuman-readable description
endpoints[].pricestringPrice per request

​
pay

Execute a payment through the x402 gateway. Request: 
{
  "agentId": "inst_abc123",
  "action": "pay",
  "amount": "1.0",
  "currency": "USDC",
  "recipient": "0x5678...efgh",
  "endpoint": "chat",
  "method": "tempo"
}
FieldTypeRequiredDescription
amountstringYesPayment amount
currencystringYesPayment currency (e.g. USDC, pathUSD). The value is forwarded to the upstream gateway as-is.
recipientstringYesRecipient wallet address
endpointstringNoTarget endpoint slug on the gateway
methodstringNoPayment method identifier

​
Error responses

StatusErrorDescription
400agentId requiredThe agentId field is missing from the request body
400Invalid action. Use: join-colony, fitness, pricing, endpoints, or payThe action field is missing or not one of the supported values
401Authentication requiredNo valid session. You must be signed in with both a user ID and email.
500x402 gateway errorAn 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" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "agentId": "inst_abc123",
    "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": "0x5678...efgh",
    "endpoint": "chat",
    "method": "tempo"
  }'