Flipvo API quickstart

Paid lookups over plain HTTP, for software and AI agents. You can call a route with no account: the first answer is an HTTP 402 that carries the price, you pay it, and you send the same request again.

1. See what is served (free)

These GETs cost nothing and are not metered. License verification serves: CA, CO, FL, LA, MN, NJ, OR, TN, TX, VA, WA. Entity lookup serves: CO, CT, FL, IA, NY, OR.

curl https://api.flipvo.com/v1/license/states

2. Read a price

Send the request you mean to make, with no payment header. A valid body gets the 402; the amount is in the PAYMENT-REQUIRED header (x402) and in one WWW-Authenticate: Payment header per accepted MPP method. Nothing is charged for this request. An empty body or {} gets the 402 as well, so you can read a price before building a request. While a data source or provider is known to be down, the answer is a 503 with Retry-After instead, before any payment.

curl -i -X POST https://api.flipvo.com/v1/license/verify \
  -H 'content-type: application/json' \
  -d '{"state": "CA", "name": "Example Construction Inc"}'

That route costs $0.02 per call. The PAYMENT-REQUIRED value is base64 JSON: accepts[].amount is in USDC atomic units (6 decimals, so 20000 is $0.02). Decode it with:

echo "$PAYMENT_REQUIRED_VALUE" | base64 -d

3. Pay and retry

Pay with one of the methods that 402 offers, then send the same request with the payment header; the answer comes back with a receipt. The methods a route accepts depend on its price, so read them from the 402 or from the table below. An x402 or MPP client library does the read, pay and retry for you.

Routes and prices

RoutePrice per callAccepted (the 402 lists those its price clears)
POST /v1/ping$0.001x402
POST /v1/drive$0.01x402, tempo
POST /v1/matrix$0.05x402, tempo
POST /v1/license/verify$0.02x402, tempo
POST /v1/entity/lookup$0.01x402, tempo
POST /v1/nonprofit/verify$0.01x402, tempo
POST /v1/sanctions/screen$0.01x402, tempo
POST /v1/exclusions/screen$0.01x402, tempo
POST /v1/carrier/lookup$0.03x402, tempo
POST /v1/license/search$0.05x402, tempo
POST /v1/airport/nearest$0.02x402, tempo
POST /v1/osha/history$0.02x402, tempo
POST /v1/npi/verify$0.01x402, tempo

Accepted methods: x402 USDC on Base (method x402); MPP USDC on Tempo (method tempo). Prices are read from the live configuration when this page is served.

Worked examples

POST /v1/license/verify — $0.02 per call

curl -i -X POST https://api.flipvo.com/v1/license/verify \
  -H 'content-type: application/json' \
  -d '{"state": "CA", "name": "Example Construction Inc"}'

POST /v1/entity/lookup — $0.01 per call

curl -i -X POST https://api.flipvo.com/v1/entity/lookup \
  -H 'content-type: application/json' \
  -d '{"state": "CO", "name": "Example Holdings LLC"}'

POST /v1/sanctions/screen — $0.01 per call

curl -i -X POST https://api.flipvo.com/v1/sanctions/screen \
  -H 'content-type: application/json' \
  -d '{"name": "Banco Nacional de Cuba"}'

When a request is refused before payment

When the answer fails after payment

After payment, a failure on our side (a data or routing backend that stops answering while your request is being served) is a 503 or another 5xx, not an answer. On the routing routes (/v1/drive, /v1/matrix, /v1/airport/nearest), a 503 caused by a rate-limited or unreachable routing provider carries Retry-After, and requests that follow get the pre-payment 503 above; a 503 from any other backend carries no Retry-After. An x402 payment is not settled for a failed answer. An MPP payment for a failed answer is recorded as not delivered.

From an MCP client

The same routes are tools on POST /mcp (streamable HTTP, same prices). initialize and tools/list are free. On tools/call, an x402 payment goes in the request's _meta["x402/payment"] rather than in an HTTP header.

Reference