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`

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

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`

Authentication behavior

Error responses

Examples

Check gateway health

Join colony

Get fitness score

Get pricing

List endpoints

Make a payment

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

​x402 gateway

​Health check

​Response (200)

​Response (503)

​Execute action

​Headers

​Body

​Actions

​join-colony

​fitness

​pricing

​endpoints

​pay

​Authentication behavior

​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`

Authentication behavior

Error responses

Examples

Check gateway health

Join colony

Get fitness score

Get pricing

List endpoints

Make a payment