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, but endpoints is public.

Headers

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

Body

Field	Type	Required	Description
`agentId`	string	Varies	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.

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
  }
}

Field	Type	Description
`score`	number	Agent fitness score (0–100)
`tier`	string	Fitness tier (e.g. `bronze`, `silver`, `gold`, or `new` for fallback)
`details`	object \| null	Breakdown 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"
  }
}

Field	Type	Description
`agentId`	string	Agent instance identifier
`tier`	string	Pricing tier (e.g. `gold`, `silver`, or `basic` for fallback)
`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

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

Field	Type	Description
`success`	boolean	Whether the request succeeded
`endpoints`	array	List of available gateway endpoints
`endpoints[].slug`	string	Endpoint path on the gateway
`endpoints[].description`	string	Human-readable description
`endpoints[].price`	string	Price 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"
}

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. Only applies to authenticated actions (`join-colony`, `fitness`, `pricing`, `pay`).
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. Applies to all actions except `endpoints`. 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. 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"
  }'

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