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.

What to ask your agent

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

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.

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:

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

The API responds with payment instructions:

HTTP/1.1 402 Payment Required
Content-Type: application/json

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.

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

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

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.

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.