# Endpoints

## Endpoints

### Base URL

```
https://x402.quickintel.io
```

***

### Endpoints Overview

| Method | Path                    | Auth         | Description                  |
| ------ | ----------------------- | ------------ | ---------------------------- |
| `POST` | `/v1/tator/prompt`      | x402 ($0.20) | Submit a trading prompt      |
| `GET`  | `/v1/tator/jobs/:jobId` | Free         | Poll job status (async mode) |
| `GET`  | `/v1/tator/health`      | Free         | Backend health check         |
| `GET`  | `/health`               | Free         | Gateway health check         |
| `GET`  | `/accepted`             | Free         | Payment discovery            |

***

### POST /v1/tator/prompt

Submit a natural language trading instruction for processing.

#### Pricing

**$0.20 per call** — charged regardless of outcome (transaction, info, or error response).

#### Request

**Headers:**

| Header              | Required | Description                 |
| ------------------- | -------- | --------------------------- |
| `Content-Type`      | Yes      | `application/json`          |
| `PAYMENT-SIGNATURE` | Yes      | Base64-encoded x402 payment |

**Body:**

```json
{
  "prompt": "buy $10 worth of ETH on base",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f7AAAA",
  "provider": "your-agent-name",
  "chain": "base",
  "slippage": 1,
  "async": false
}
```

**Fields:**

| Field           | Type    | Required | Description                             |
| --------------- | ------- | -------- | --------------------------------------- |
| `prompt`        | string  | ✅        | Natural language trading instruction    |
| `walletAddress` | string  | ✅        | Your wallet address (EVM or Solana)     |
| `provider`      | string  | ✅        | Your agent/integration name             |
| `chain`         | string  | ❌        | Preferred chain (can also be in prompt) |
| `slippage`      | number  | ❌        | Slippage tolerance % (default: 1)       |
| `async`         | boolean | ❌        | Use async mode (default: false)         |

#### Prompt Best Practices

Always include in your prompt:

* **Chain name** — "on Base", "on Arbitrum"
* **Token symbol or contract address** — Use CA for obscure tokens
* **Amount with unit** — "$50 worth" or "100 USDC"

See Overview - Prompt Best Practices for examples.

#### Response (Sync Mode)

**Success (200 OK):**

```json
{
  "success": true,
  "jobId": "4c6f5fb5-fdaa-49cb-8a16-5088156f5231",
  "status": "completed",
  "type": "transaction",
  "response": "Your $10 worth of ETH has been prepared on Base.",
  "operation": {
    "operation_id": "op_1771094491979_wk6bp2x",
    "operation_type": "buy",
    "token_symbol": "ETH",
    "amount": 10,
    "chain": "base"
  },
  "transactions": [{
    "type": "swap",
    "to": "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5",
    "data": "0xe21fd0e9...",
    "value": "970400362929736",
    "chainId": 8453,
    "gas": "373855"
  }],
  "transaction_data": {
    "quote": {
      "inputToken": "USDC",
      "outputToken": "ETH",
      "inputAmount": "10000000",
      "outputAmount": "0.00485"
    },
    "slippage": 1
  },
  "processingTime": 24649
}
```

#### Response (Async Mode)

When `async: true`, returns immediately:

**Accepted (202):**

```json
{
  "success": true,
  "jobId": "4c6f5fb5-fdaa-49cb-8a16-5088156f5231",
  "status": "processing",
  "message": "Job created. Poll GET /v1/jobs/:jobId for results.",
  "request": {
    "prompt": "buy $10 worth of ETH on base",
    "walletAddress": "0x742d...",
    "provider": "your-agent-name"
  }
}
```

#### Response (Unclear Prompt)

If your prompt is missing information:

**Success (200 OK) but type is `info`:**

```json
{
  "success": true,
  "jobId": "...",
  "status": "completed",
  "type": "info",
  "response": "I'd be happy to help you trade! Could you please specify: 1) Which token, 2) How much, and 3) Which chain?",
  "transactions": []
}
```

> ⚠️ **Note:** You are still charged $0.20 for unclear prompts.

#### Error Responses

**Payment Required (402):**

```json
{
  "error": "Payment required",
  "message": "This endpoint requires $0.20 USDC to access.",
  "paymentRequired": { ... }
}
```

**Bad Request (400):**

```json
{
  "success": false,
  "error": "Missing required field",
  "field": "walletAddress"
}
```

**Timeout (408):**

```json
{
  "success": false,
  "status": "failed",
  "error": "Request timed out after 90000ms. Please try again."
}
```

***

### GET /v1/tator/jobs/:jobId

Poll for job status and results when using async mode.

#### Pricing

**Free** — no payment required for polling.

#### Request

**Path Parameters:**

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| `jobId`   | string | Job ID from the initial prompt response |

**Query Parameters:**

| Parameter       | Type   | Required | Description                              |
| --------------- | ------ | -------- | ---------------------------------------- |
| `walletAddress` | string | ✅        | The wallet address from original request |

**Example:**

```bash
curl "https://x402.quickintel.io/v1/tator/jobs/4c6f5fb5-fdaa-49cb-8a16-5088156f5231?walletAddress=0x742d..."
```

#### Response

**Processing (200):**

```json
{
  "success": true,
  "jobId": "4c6f5fb5-fdaa-49cb-8a16-5088156f5231",
  "status": "processing"
}
```

**Completed (200):**

```json
{
  "success": true,
  "jobId": "4c6f5fb5-fdaa-49cb-8a16-5088156f5231",
  "status": "completed",
  "type": "transaction",
  "response": "Your buy order is ready...",
  "transactions": [{ ... }],
  ...
}
```

**Not Found (404):**

```json
{
  "success": false,
  "jobId": "...",
  "status": "failed",
  "error": "Job not found or expired"
}
```

***

### GET /v1/tator/health

Check if the Tator backend is healthy and reachable.

#### Pricing

**Free**

#### Request

```bash
curl https://x402.quickintel.io/v1/tator/health
```

#### Response

**Healthy (200):**

```json
{
  "success": true,
  "status": "healthy",
  "timestamp": "2026-02-14T18:30:19.401Z",
  "version": "1.1.0",
  "features": {
    "asyncMode": true,
    "responseTypes": ["info", "transaction", "error"]
  }
}
```

***

### GET /health

Check gateway health and see configured backends/networks.

#### Pricing

**Free**

#### Request

```bash
curl https://x402.quickintel.io/health
```

#### Response

```json
{
  "status": "healthy",
  "service": "quickintel-x402-gateway",
  "version": "1.2.0",
  "backends": {
    "tator": { "configured": true, "status": "ready" }
  },
  "payment": {
    "settlement": "local",
    "networks": [
      { "network": "eip155:8453", "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }
    ]
  },
  "routes": [
    {
      "path": "/v1/tator/*",
      "price": "$0.20",
      "backend": "Tator Trader"
    }
  ]
}
```

***

### GET /accepted

Discover payment requirements and supported networks.

#### Pricing

**Free**

#### Request

```bash
curl https://x402.quickintel.io/accepted
```

#### Response

```json
{
  "x402Version": 2,
  "service": "quickintel-x402-gateway",
  "routes": [
    {
      "path": "/v1/tator/*",
      "backend": "Tator Trader",
      "price": "$0.20",
      "payTo": "0x6a35dF48189eB83404d97b32dd3E91517ff4ceb9",
      "description": "AI-powered trade execution API...",
      "requiredFields": {
        "prompt": "string (required)",
        "walletAddress": "string (required)",
        "provider": "string (required)"
      },
      "networks": [
        {
          "network": "eip155:8453",
          "chainId": 8453,
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "assetName": "USD Coin",
          "decimals": 6,
          "amountRequired": "200000"
        }
      ]
    }
  ]
}
```

***

### Response Headers

#### PAYMENT-RESPONSE

After successful payment, this header contains settlement details:

```
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0eEhhc2giOiIweC4uLiJ9
```

Decoded:

```json
{
  "success": true,
  "txHash": "0x44da78c62707baa63cba7293d6bb49fb71927be0ff5bf24312b170120e75e689",
  "network": "eip155:8453",
  "blockNumber": 42152565
}
```

***

### Pricing Summary

| Endpoint                 | Price |
| ------------------------ | ----- |
| `POST /v1/tator/prompt`  | $0.20 |
| `GET /v1/tator/jobs/:id` | Free  |
| `GET /v1/tator/health`   | Free  |
| `GET /health`            | Free  |
| `GET /accepted`          | Free  |

***

### Next Steps

* [**Request & Response**](https://tatordocs.quickintel.io/api-and-agent-integration/request-and-response-format) — Detailed format documentation
* [**Example Flows**](https://tatordocs.quickintel.io/api-and-agent-integration/example-flows) — Complete code examples
