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
Dispatches an action to the x402 gateway. Most actions require an authenticated session, but endpoints is public.

​
Headers

HeaderTypeRequiredDescription
Content-TypestringYesMust be application/json
CookiestringVariesValid NextAuth session cookie. Required for all actions except endpoints.

​
Body

FieldTypeRequiredDescription
agentIdstringVariesAgent instance identifier. Required for all actions except endpoints.
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.
Several actions return graceful fallback responses when the upstream gateway is unreachable instead of failing with a 500 error. These fallback responses are noted in each action’s documentation below.

​
Actions

​
join-colony

Register an agent with the x402 colony. Requires authentication. The request times out after 10 seconds. This action does not have a fallback — if the upstream gateway is unreachable, a 500 error is returned. 
{
  "agentId": "inst_abc123",
  "walletAddress": "0x1234...5678",
  "action": "join-colony"
}

​
fitness

Retrieve the fitness score for an agent. Requires authentication. The request times out after 10 seconds. 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, or new for fallback)
detailsobject | nullBreakdown of fitness dimensions. null in fallback responses.
Fallback response: When the upstream gateway is unreachable, the API returns a default response instead of an error: 
{
  "success": true,
  "score": 50,
  "tier": "new",
  "details": null
}

​
pricing

Retrieve dynamic pricing for an agent. Pricing is adjusted based on the agent’s fitness score and tier. Requires authentication. The request times out after 10 seconds. 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 (e.g. gold, silver, or basic for fallback)
pricing.ratenumberCurrent rate per request
pricing.discountnumberDiscount factor applied based on fitness
fitness.scorenumberAgent fitness score
fitness.tierstringAgent fitness tier
Fallback response: When the upstream gateway is unreachable, the API returns a default response instead of an error: 
{
  "success": true,
  "agentId": "inst_abc123",
  "tier": "basic",
  "pricing": {
    "rate": 0.01,
    "discount": 0
  },
  "fitness": {
    "score": 50,
    "tier": "new"
  }
}

​
endpoints

List all available endpoints on the x402 gateway. This action is public — no authentication or agentId is required. The request times out after 10 seconds. Request: 
{
  "action": "endpoints"
}
Response (200): 
{
  "success": true,
  "endpoints": [
    {
      "slug": "/gateway/colony/join",
      "description": "Join agent colony",
      "price": "Free"
    },
    {
      "slug": "/gateway/fitness/:agentId",
      "description": "Get agent fitness score",
      "price": "Free"
    },
    {
      "slug": "/gateway/pricing/:agentId",
      "description": "Get dynamic pricing",
      "price": "Free"
    },
    {
      "slug": "/gateway/pay",
      "description": "Make payment",
      "price": "Variable"
    }
  ]
}
FieldTypeDescription
successbooleanWhether the request succeeded
endpointsarrayList of available gateway endpoints
endpoints[].slugstringEndpoint path on the gateway
endpoints[].descriptionstringHuman-readable description
endpoints[].pricestringPrice per request (e.g. "Free", "Variable", or a numeric string)
Fallback response: When the upstream gateway is unreachable, the API returns a hardcoded default list of endpoints (shown above) instead of an error. The response shape is identical whether served from the upstream gateway or the fallback.

​
pay

Execute a payment through the x402 gateway. Requires authentication. The request times out after 15 seconds. This action does not have a fallback — if the upstream gateway is unreachable, a 500 error is returned. 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. Only applies to authenticated actions (join-colony, fitness, pricing, pay).
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. Applies to all actions except endpoints. You must be signed in with both a user ID and email.
500x402 gateway errorAn unexpected error occurred while communicating with the upstream gateway. Only returned for actions without fallback behavior (join-colony, pay).

​
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": "0x5678...efgh",
    "endpoint": "chat",
    "method": "tempo"
  }'