# Dexter x402 API Reference

## Bazaar Discovery API

### `GET /discovery/resources`

Returns all verified x402 endpoints in the Dexter marketplace.

**Base URL:** `https://x402.dexter.cash`

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | number | 20 | Max number of results to return (up to 200) |

**Example Request:**

```bash
curl -s "https://x402.dexter.cash/discovery/resources?limit=5"
```

**Response Shape:**

```json
{
  "x402Version": 2,
  "items": [
    {
      "resource": "https://example.com/api/endpoint",
      "type": "http",
      "description": "Human-readable description of what this endpoint does",
      "method": "GET",
      "x402Version": 2,
      "accepts": [
        {
          "scheme": "exact",
          "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
          "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "payTo": "SELLER_ADDRESS",
          "maxAmountRequired": "10000",
          "maxTimeoutSeconds": 30,
          "resource": "https://example.com/api/endpoint",
          "description": "Payment description",
          "mimeType": "application/json",
          "extra": {
            "name": "USD Coin",
            "version": "2"
          },
          "outputSchema": {
            "input": { "type": "http", "method": "GET" },
            "output": { "type": "object", "properties": {} }
          }
        }
      ],
      "lastUpdated": "2026-02-27T19:15:46.700Z"
    }
  ]
}
```

**Key Fields:**

| Field | Description |
|-------|-------------|
| `items[].resource` | The endpoint URL to call |
| `items[].description` | AI-generated description of what the API does |
| `items[].method` | HTTP method (GET, POST) |
| `items[].accepts` | Array of payment options (one per network/scheme) |
| `items[].accepts[].scheme` | Payment scheme (always `exact` for Dexter) |
| `items[].accepts[].network` | Chain identifier (CAIP-2 format for v2) |
| `items[].accepts[].maxAmountRequired` | Price in atomic USDC units (6 decimals) |
| `items[].accepts[].payTo` | Seller's payment address |
| `items[].accepts[].asset` | Token mint/contract address (USDC) |
| `items[].accepts[].outputSchema` | JSON schema describing the API's input/output |
| `items[].lastUpdated` | When the endpoint was last verified |

**Price Conversion:**

USDC has 6 decimals. To convert atomic units to dollars:

| Atomic Units | USDC |
|-------------|------|
| 1000 | $0.001 |
| 10000 | $0.01 |
| 100000 | $0.10 |
| 1000000 | $1.00 |
| 8000000 | $8.00 |

---

## Capability Search API

### `GET /api/x402gle/capability`

Semantic vector search over the x402 marketplace. Prefer this over `/discovery/resources` whenever the user is actually searching for a capability (as opposed to enumerating the full bazaar).

**Base URL:** `https://api.dexter.cash`

**How it works:**
1. The query is parsed by an intent-extraction LLM that also produces a synonym-expanded rewrite.
2. The expanded query is embedded with `voyage-3-large` (1024-dim).
3. pgvector retrieves the top-60 candidates by cosine similarity, filtered by a minimum floor (0.45).
4. Candidates are split into **strong** (≥0.55) and **related** (0.45–0.54) tiers.
5. The top strong results are reordered by a cross-encoder LLM rerank (skippable with `?rerank=false`).

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `q` | string | — | **Required.** Natural-language description of the capability. Pass full sentences, not keywords. |
| `limit` | number | 20 | Max results across strong + related tiers combined (1–50) |
| `unverified` | boolean | `false` | Include unverified resources in results |
| `testnets` | boolean | `false` | Include testnet-only resources |
| `rerank` | boolean | `true` | Run the cross-encoder LLM rerank on top strong results |

**Example Request:**

```bash
QUERY="check wallet balance on Base"
curl -s "https://api.dexter.cash/api/x402gle/capability?q=$(jq -rn --arg q "$QUERY" '$q|@uri')&limit=10"
```

**Response Shape:**

```json
{
  "ok": true,
  "query": "check wallet balance on Base",
  "intent": {
    "capabilityText": "check wallet balance",
    "expandedCapabilityText": "check wallet balance token balance portfolio address holdings..."
  },
  "strongResults": [
    {
      "resourceId": "84a7af2d-...",
      "resourceUrl": "https://api.nansen.ai/api/v1/profiler/address/current-balance",
      "displayName": "Address Balance Snapshot",
      "description": "Fetch the current native and token balances...",
      "category": "Analytics",
      "host": "api.nansen.ai",
      "method": "POST",
      "icon": "https://www.google.com/s2/favicons?domain=api.nansen.ai&sz=64",
      "pricing": {
        "usdc": 0.01,
        "network": "eip155:8453",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "chains": [
          { "network": "eip155:8453", "priceUsdc": 0.01, "priceLabel": "$0.01", "asset": "0x833...", "priceAtomic": "10000" },
          { "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "priceUsdc": 0.01, "priceLabel": "$0.01", "asset": "EPjFW...", "priceAtomic": "10000" }
        ]
      },
      "verification": {
        "status": "pass",
        "paid": true,
        "qualityScore": 92,
        "lastVerifiedAt": "2026-04-15T..."
      },
      "usage": {
        "totalSettlements": 0,
        "totalVolumeUsdc": 0
      },
      "gaming": { "flags": [], "suspicious": false },
      "similarity": 0.779,
      "why": "semantic 78% · paid-verified · q92 · no recorded settlements (cold start)",
      "tier": "strong",
      "score": 0.053
    }
  ],
  "relatedResults": [],
  "strongCount": 35,
  "relatedCount": 25,
  "topSimilarity": 0.779,
  "noMatchReason": null,
  "rerank": { "enabled": true, "applied": true },
  "thresholds": { "similarityFloor": 0.45, "strongMatch": 0.55 },
  "embeddingTokens": 29,
  "durationMs": 2897
}
```

**Key Fields:**

| Field | Description |
|-------|-------------|
| `strongResults[]` | High-confidence capability matches. Present these first; they're already reranked. |
| `relatedResults[]` | Adjacent services that cleared the similarity floor but not the strong threshold. Fallback only. |
| `<result>.pricing.usdc` | Primary-chain price in USDC dollars (not atomic units — no conversion needed). |
| `<result>.pricing.chains[]` | Every payment rail the resource accepts. Each entry has network, asset, priceAtomic, priceUsdc, priceLabel. |
| `<result>.tier` | `"strong"` or `"related"` — which tier this result came from. |
| `<result>.similarity` | Raw cosine similarity 0–1 between the query embedding and the resource embedding. |
| `<result>.why` | One-sentence explanation of the ranking (factors: semantic, verification, quality, settlements, gaming flags). |
| `noMatchReason` | `"below_similarity_threshold"` (zero candidates) or `"below_strong_threshold"` (only related) or `null`. |
| `rerank.applied` | `true` if the cross-encoder LLM actually reordered the top strong results. |

**Failure modes:**

- `400 invalid_query` — caller error (missing `q`, malformed params)
- `502 capability_search_failed` — backend stage failed. Check the `stage` field: `intent_parse`, `voyage_embed`, `candidate_retrieval`, or `ranking`.

**When to use vs `/discovery/resources`:**

| Use case | Endpoint |
|----------|----------|
| User wants to find a capability ("get ETH price", "check wallet balance") | **Capability search** |
| User wants to enumerate the full bazaar (paginate through everything) | `/discovery/resources` |
| You need raw x402-spec format for protocol compliance | `/discovery/resources` |
| You want ranking, synonyms, and tiered results | **Capability search** |

---

## Facilitator API

### `GET /supported`

Returns supported payment schemes, networks, and features.

```bash
curl -s "https://x402.dexter.cash/supported"
```

**Response:**

```json
{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "extra": {
        "feePayer": "DEXVS3su4dZQWTvvPnLDJLRK1CeeKG6K3QqdzthgAkNV",
        "decimals": 6,
        "features": {
          "gasSponsored": true,
          "smartWalletSupported": true
        }
      }
    }
  ],
  "extensions": ["bazaar"],
  "signers": {}
}
```

### `GET /healthz`

Health check endpoint.

```bash
curl -s "https://x402.dexter.cash/healthz"
```

---

## x402 Payment Flow (How Endpoints Work)

### 1. Request without payment

```bash
curl -s "https://example-x402-endpoint.com/api/data"
# Returns: HTTP/1.1 402 Payment Required
```

### 2. Parse payment requirements

The 402 response carries pricing in **one or both** locations:

| Source | Format | When |
|--------|--------|------|
| **JSON body** (most common) | Raw JSON with `accepts` array | Most servers |
| **`Payment-Required` header** | Base64-encoded JSON | Some servers |

**Always check the body first, fall back to the header.**

**v1 response example** (tweetx402, some older servers):

```json
{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "1000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x9DdBc42e8fEa0D9a7FD68934545D3a9Bff334307",
      "maxTimeoutSeconds": 30
    }
  ]
}
```

**v2 response example** (Dexter bazaar endpoints, newer servers):

```json
{
  "x402Version": 2,
  "error": "Payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "10000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "SELLER_ADDRESS",
      "maxTimeoutSeconds": 60,
      "extra": {
        "feePayer": "DEXVS3su4dZQWTvvPnLDJLRK1CeeKG6K3QqdzthgAkNV",
        "decimals": 6
      }
    }
  ]
}
```

**Key v1/v2 parsing rules:**

| Field | v1 | v2 | How to handle |
|-------|----|----|---------------|
| Amount | `maxAmountRequired` | `amount` | Use `amount \|\| maxAmountRequired` |
| Network | `solana`, `base` | CAIP-2: `solana:5eykt4...` | Accept both formats |
| Payment header sent | `X-PAYMENT` | `PAYMENT-SIGNATURE` | lobster.cash handles this |
| Decimals | Assumed 6 | `extra.decimals` | Default to 6 if missing |

### 3. Payment execution (handled by lobster.cash)

The skill describes the payment intent. lobster.cash builds the transaction, signs it with the user's smart wallet, and sends it through the facilitator. The v2 facilitator is backward-compatible with v1 clients.

### 4. Retry with payment signature

```bash
# v1 servers expect:
curl -s "https://example.com/api/data" -H "X-PAYMENT: <payment>"

# v2 servers expect:
curl -s "https://example.com/api/data" -H "PAYMENT-SIGNATURE: <payment>"
```

lobster.cash determines the correct header based on the `x402Version` in the 402 response. The server verifies the payment through the facilitator and returns the API response.

---

## Network Identifiers

| Network | CAIP-2 Identifier | Legacy Format |
|---------|-------------------|---------------|
| Solana mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | `solana` |
| Solana devnet | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` | `solana-devnet` |
| Base | `eip155:8453` | `base` |
| Base Sepolia | `eip155:84532` | — |
| Polygon | `eip155:137` | — |
| SKALE | `eip155:1187947933` | — |

## USDC Token Addresses

| Network | USDC Address |
|---------|-------------|
| Solana | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
| Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |