---
title: "Agentic Payments"
description: "Let AI agents pay for supported CarsXE API calls with x402, without first creating or storing a CarsXE API key."
canonical_url: "https://docs.carsxe.com/docs/guides/agentic-payments"
markdown_url: "https://docs.carsxe.com/docs/guides/agentic-payments.md"
last_updated: "1980-01-01"
---

# Agentic Payments
URL: /docs/guides/agentic-payments
LLM index: /llms.txt
Description: Let AI agents pay for supported CarsXE API calls with x402, without first creating or storing a CarsXE API key.
Related: /docs/guides/agents, /docs/get-started#authentication, /api-reference

Task: Pay for supported CarsXE API calls with x402 without a CarsXE API key.

Auth rule: Omit the `key` query parameter. If `key` is present, normal API-key auth applies and x402 is skipped.

Steps:
1. Call the CarsXE endpoint without `key`, using the final query/body parameters.
2. Read the `402 Payment Required` response for `endpointId`, `price`, `resource`, and payment requirements.
3. Pay with an x402-compatible wallet or client for the exact price returned (never hardcode prices).
4. Retry the identical request with the x402 payment header (`X-PAYMENT` or the client-specific equivalent).
5. Return the normal CarsXE JSON response to the user.

Verification:
- Unpaid call returns `402` with payment instructions.
- Paid retry returns a successful `2xx` response with `success: true` and product JSON.
- Recalls-batch submit returns `202`; retain its one-time `data.batchToken` for status, results, and download requests.
- Paid responses may include an `X-PAYMENT-RESPONSE` header for run logs.

Recovery:
- `503` / "x402 payments are not configured" → use API-key auth via /docs/guides/agents instead.
- Paid retry returns `500` after settlement → do not pay again; retain the `X-PAYMENT-RESPONSE` value or transaction hash and contact CarsXE support.
- Keep request parameters identical between the unpaid call and paid retry.

Related: /docs/guides/agents, /docs/get-started#authentication, /api-reference

# Agentic Payments

Agentic payments let an AI agent call supported CarsXE APIs without a CarsXE API key. Instead, the agent uses an x402-compatible payment client or wallet, reads the payment requirements from the API response, pays for the request, and retries with the payment proof.

Use this when you want an agent to buy a single vehicle data lookup on demand, such as decoding a VIN, checking recalls, getting market value, or resolving a license plate.

<Note>
  If your request includes a CarsXE API key with `key=YOUR_API_KEY`, the API
  uses normal API-key authentication. x402 is only used when no CarsXE API key
  is sent.
</Note>

## What to ask your agent

Give your agent a direct instruction that includes the vehicle task and tells it to use x402:

<Note>
  Each lookup is a paid API call. Prices are small and vary by endpoint — a VIN
  decode is around **$0.15**, for example. Your agent reads the exact, current
  price from the `402 Payment Required` response before paying, so it never
  guesses.
</Note>

<CodeGroup title="Prompt examples">

```text title="VIN decode"
Read the CarsXE agentic payments docs at https://docs.carsxe.com/docs/guides/agentic-payments, then use x402 to pay for a CarsXE VIN decode for WBAFR7C57CC811956 and summarize the make, model, year, engine, and trim.
```

```text title="Recalls"
Read the CarsXE agentic payments docs at https://docs.carsxe.com/docs/guides/agentic-payments, then use x402 with CarsXE to check recalls for VIN WBAFR7C57CC811956. Show open recalls first.
```

```text title="Market value"
Read the CarsXE agentic payments docs at https://docs.carsxe.com/docs/guides/agentic-payments, then use x402 to pay for a CarsXE market value lookup for WBAFR7C57CC811956 with 50,000 miles in CA.
```

```text title="Plate decode"
Read the CarsXE agentic payments docs at https://docs.carsxe.com/docs/guides/agentic-payments, then use x402 to look up plate 7XER187 in California with CarsXE and tell me the decoded vehicle.
```

</CodeGroup>

## Agent flow

An x402-capable agent should follow this flow:

1. Make the CarsXE API request without `key`.
2. Read the `402 Payment Required` response.
3. Inspect the returned payment requirements, including price, network, and resource.
4. Submit payment with an x402-compatible wallet or payment client.
5. Retry the same API request with the x402 payment header.
6. Read the normal CarsXE JSON response and answer the user.

Pricing is returned in the payment requirement and can vary by endpoint. Your agent should not hardcode prices; it should read the current requirement from the `402` response.

## Minimal HTTP shape

First, the agent calls the endpoint without a CarsXE API key:

<CodeGroup title="Request">

```bash
curl -i "https://api.carsxe.com/specs?vin=WBAFR7C57CC811956"
```

</CodeGroup>

The API responds with payment instructions:

<CodeGroup title="Payment required">

```http title="Status"
HTTP/1.1 402 Payment Required
Content-Type: application/json
```

```json title="Response body"
{
  "success": false,
  "message": "Payment or API key required. Complete payment or authenticate with your CarsXE API key to continue. If paying programmatically, include the x402 payment header (payment-signature or x-payment). Get an API key: https://carsxe.com/dashboard/developer",
  "endpointId": "specs.v1",
  "price": "$0.15",
  "resource": "/specs",
  "apiKeyUrl": "https://carsxe.com/dashboard/developer"
}
```

</CodeGroup>

After the agent pays with an x402-compatible client, it retries the same request with the payment proof header. Header names can vary by x402 client; CarsXE accepts the standard x402 payment header used by the client.

<CodeGroup title="Paid retry">

```bash
curl -i "https://api.carsxe.com/specs?vin=WBAFR7C57CC811956" \
  -H "X-PAYMENT: <x402-payment-header>"
```

</CodeGroup>

Successful paid responses include the normal CarsXE API JSON body. The response can also include an `X-PAYMENT-RESPONSE` header that the agent may keep with its run logs.

If a paid retry returns `500` after the payment settled, do not submit another
payment for the same request. Retain the `X-PAYMENT-RESPONSE` value or
transaction hash and contact CarsXE support so the result can be recovered or
the settlement can be refunded.

## Supported endpoints

| Product                   | Method | Path                            | Required parameters                              | Optional parameters                                     |
| ------------------------- | ------ | ------------------------------- | ------------------------------------------------ | ------------------------------------------------------- |
| Vehicle Specifications    | `GET`  | `/specs`                        | `vin`                                            | `deepdata`, `format`, `disableIntVINDecoding`           |
| Market Value v1           | `GET`  | `/marketvalue`                  | `vin`                                            | `format`                                                |
| Market Value v2           | `GET`  | `/v2/marketvalue`               | `vin`                                            | `country`, `state`, `mileage`, `condition`              |
| Vehicle History           | `GET`  | `/history`                      | `vin`                                            | `format`                                                |
| International VIN Decoder | `GET`  | `/v1/international-vin-decoder` | `vin`                                            | —                                                       |
| Vehicle Recalls           | `GET`  | `/v1/recalls`                   | `vin`                                            | —                                                       |
| Vehicle Recalls Report    | `GET`  | `/v1/recalls-reports`           | `vin`                                            | —                                                       |
| Lien & Theft              | `GET`  | `/v1/lien-theft`                | `vin`                                            | —                                                       |
| Plate Decoder             | `GET`  | `/platedecoder`                 | `plate`, `state`                                 | `format`, `country`                                     |
| Plate Decoder v2          | `GET`  | `/v2/platedecoder`              | `plate`, `state`                                 | `district`, `country`, `require_vin`                    |
| US-Only Plate Decoder     | `GET`  | `/v1/us-platedecoder`           | `plate`, `state`                                 | `decodeVIN`                                             |
| Vehicle Images            | `GET`  | `/images`                       | `make`, `model`                                  | `year`, `trim`, `color`, `angle`, `body`, `background`  |
| Year Make Model           | `GET`  | `/v1/ymm`                       | `year`, `make`, `model`                          | `trim`, `allTrimOptions`                                |
| Vehicle Recalls by YMM    | `GET`  | `/v1/recalls-ymm`               | `year`, `make`, `model`                          | —                                                       |
| OBD Codes Decoder         | `GET`  | `/obdcodesdecoder`              | `code` or `obd_code`                             | —                                                       |
| Plate Image Recognition   | `POST` | `/platerecognition`             | JSON body with one image URL field               | —                                                       |
| VIN OCR                   | `POST` | `/v1/vinocr`                    | JSON body with one image URL or image data field | —                                                       |
| Recalls Batch Submit      | `POST` | `/v1/recalls-batch/submit`      | JSON `vins` array                                | `webhookUrl`                                            |

### Recalls Batch with x402

For x402, submit a JSON `vins` array. Duplicate VINs are normalized and charged once, and the payment requirement is the current per-VIN starter price multiplied by the unique VIN count. The `csv` and `csvUrl` request forms remain available with CarsXE API-key authentication only.

The successful `202` response includes `data.batchToken`. Keep this token secret: it is returned once and grants access only to that batch. Send it as `X-CarsXE-Batch-Token` when calling `/v1/recalls-batch/status`, `/v1/recalls-batch/results`, or `/v1/recalls-batch/download`. These follow-up calls do not require another x402 payment.

```bash
curl -G "https://api.carsxe.com/v1/recalls-batch/status" \
  -d batchId=brb_mnablbn7_wvbaqv \
  -H "X-CarsXE-Batch-Token: <batch-token>"
```

## Agent checklist

- Do not include `key` when using x402.
- Keep the request parameters identical between the unpaid request and the paid retry.
- Read the current price and network from the `402` response.
- Use the same endpoint path shown in the payment requirement.
- Return the CarsXE API result to the user after the paid retry succeeds.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).