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
| Route | Price per call | Accepted (the 402 lists those its price clears) |
|---|---|---|
POST /v1/ping | $0.001 | x402 |
POST /v1/drive | $0.01 | x402, tempo |
POST /v1/matrix | $0.05 | x402, tempo |
POST /v1/license/verify | $0.02 | x402, tempo |
POST /v1/entity/lookup | $0.01 | x402, tempo |
POST /v1/nonprofit/verify | $0.01 | x402, tempo |
POST /v1/sanctions/screen | $0.01 | x402, tempo |
POST /v1/exclusions/screen | $0.01 | x402, tempo |
POST /v1/carrier/lookup | $0.03 | x402, tempo |
POST /v1/license/search | $0.05 | x402, tempo |
POST /v1/airport/nearest | $0.02 | x402, tempo |
POST /v1/osha/history | $0.02 | x402, tempo |
POST /v1/npi/verify | $0.01 | x402, 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
- 422 before the 402: the body fails validation, so it is refused before any payment
and is not charged. The answer lists the errors in
detail; a body that does not fit the route's fields also gets ahintwith those fields and where the schema is. - 503 with
Retry-After: a data source or provider is busy or down, so the request is not taken; retry after that many seconds.
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
- Interactive API reference and OpenAPI document
- /llms.txt: every route, its body and its notes, as plain text
- Terms of use and Privacy policy