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

Requires an authenticated session with both a user ID and email. Dispatches an action to the x402 gateway.

Headers

Header	Type	Required	Description
`Content-Type`	string	Yes	Must be `application/json`
`Cookie`	string	Yes	Valid NextAuth session cookie

Body

Field	Type	Required	Description
`agentId`	string	Yes	Agent instance identifier
`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`

{
  "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. 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"
    }
  ]
}

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. Request:

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

Field	Type	Required	Description
`amount`	string	Yes	Payment amount
`currency`	string	Yes	Payment currency (e.g. `USDC`, `pathUSD`). The value is forwarded to the upstream gateway as-is.
`recipient`	string	Yes	Recipient wallet address
`endpoint`	string	No	Target endpoint slug on the gateway
`method`	string	No	Payment method identifier

Error responses

Status	Error	Description
400	`agentId required`	The `agentId` field is missing from the request body
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. You must be signed in with both a user ID and email.
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" \
  -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"
  }'

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

x402 gateway

x402 gateway

Health check

Response (200)

Response (503)

Execute action

Headers

Body

Actions

`join-colony`

`fitness`

`pricing`

`endpoints`

`pay`

Error responses

Examples

Check gateway health

Join colony

Get fitness score

Get pricing

List endpoints

Make a payment

​x402 gateway

​Health check

​Response (200)

​Response (503)

​Execute action

​Headers

​Body

​Actions

​join-colony

​fitness

​pricing

​endpoints

​pay

​Error responses

​Examples

​Check gateway health

​Join colony

​Get fitness score

​Get pricing

​List endpoints

​Make a payment

x402 gateway

Health check

Response (200)

Response (503)

Execute action

Headers

Body

Actions

`join-colony`

`fitness`

`pricing`

`endpoints`

`pay`

Error responses

Examples

Check gateway health

Join colony

Get fitness score

Get pricing

List endpoints

Make a payment