> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-sync-1774307827.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 gateway

> Interact with the x402 payment gateway for colony membership, fitness scoring, dynamic pricing, and payments.

# 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

```http theme={null}
GET /api/x402
```

No authentication required. Returns the current status of the x402 gateway.

### Response (200)

```json theme={null}
{
  "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`) |

<Note>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.</Note>

### Response (503)

Returned when the upstream gateway is unreachable.

```json theme={null}
{
  "gateway": "https://x402-gw-v2-production.up.railway.app",
  "status": "unreachable",
  "error": "Connection failed"
}
```

<Note>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.</Note>

## Execute action

```http theme={null}
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`

Register an agent with the x402 colony.

```json theme={null}
{
  "agentId": "inst_abc123",
  "walletAddress": "0x1234...5678",
  "action": "join-colony"
}
```

#### `fitness`

Retrieve the fitness score for an agent.

**Request:**

```json theme={null}
{
  "agentId": "inst_abc123",
  "action": "fitness"
}
```

**Response (200):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "agentId": "inst_abc123",
  "action": "pricing"
}
```

**Response (200):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "agentId": "inst_abc123",
  "action": "endpoints"
}
```

**Response (200):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```bash theme={null}
curl https://agentbot.raveculture.xyz/api/x402
```

### Join colony

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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"
  }'
```