Copy page

Agent payments (MPP)

Tomba for AI agents

https://agents.tomba.io serves Tomba's finder, verifier, and enrichment endpoints to AI agents that have no Tomba account. Instead of sending an API key, the agent pays for each request through InFlow with the Machine Payments Protocol (MPP). If you have a Tomba account, call the Tomba API with your key and secret instead.

How it works

1. The agent calls an endpoint, for example GET https://agents.tomba.io/email-verifier?email=jane.doe@stripe.com.
2. The service answers 402 Payment Required with a WWW-Authenticate header that holds one Payment challenge for each accepted currency.
3. The agent pays one challenge through InFlow and receives a payment credential.
4. The agent sends the same request again with the header Authorization: Payment <credential>.
5. The service checks the credential and calls the Tomba API. It settles the payment only if Tomba returned usable data, then returns Tomba's response with a Payment-Receipt header.

The InFlow CLI runs steps 2 to 4 for you; see the Quickstart. To build them into an agent, see Use with AI agents.

Endpoints

Every endpoint uses GET, takes the query parameters of the Tomba API endpoint listed next to it, and returns that endpoint's response body.

Discovery documents

These paths are free and need no payment.

Browse the catalog

The ODP catalog lists every paid endpoint as an Offering, grouped into Collections, each priced per request. Responses use the application/odp+json media type.

Add ?representation=full to a listing for complete resources, or terse for identity and price only. Listings default to terse and a single resource defaults to full; any other value is rejected with a 400 problem body.

?limit= takes 1 to 100 and defaults to 50 — anything outside that, or not a number, is a 400. When more results remain, the page carries a next reference:

Code
{
    "odp_version": "1.0",
    "items": [{ "id": "domain-search", "name": "Find all email addresses…" }],
    "next": "/odp/offerings?cursor=eyJleHBpcmVzQXQiOjE3OTEy…&representation=terse&limit=1"
}

Follow next exactly as given — it is an origin-relative path that already carries your limit and representation, so don't rebuild it from the cursor. The last page omits next rather than sending null. Cursors are signed and stay valid for one hour.

Tomba is also listed in the InFlow directory.

Pricing

Each request costs 0.00312 USDC or 0.00312 USDT — $3.12 per 1,000 requests — paid from your InFlow balance. Every 402 response offers one challenge per currency, and you pay one of them. The InFlow CLI and the InFlow buyer SDK don't pick the currency you hold on their own; see Choose a currency.

The service settles payments in InFlow's production environment, so pay with a production InFlow account.

InFlow holds each charge for manual approval unless you add a policy that approves them. An unattended agent will wait, so set one up before you automate: Approve payments automatically.

Billing

You're charged only when Tomba returns usable data. Once the service has called Tomba for a paid request, the response carries X-Payment-Charged: true or X-Payment-Charged: false.

When a response isn't charged, the credential stays unspent: correct the request and send it again with the same credential before the challenge's expires time.

• A credential pays for one request to the endpoint it was issued for. It can't be spent on another endpoint, or again after it settles.
• Every paid request is charged, including a repeat of an earlier request.

Errors

Other statuses, such as 400, 422, and 429, come from the Tomba API; see Status codes.

Rate limits

There is no rate limit. Send as many paid requests as you like, as fast as you like — your spend is the only cap, and you control that with your InFlow balance and policy.

Responses still carry rate limit headers, listed in Access-Control-Expose-Headers so a browser client can read them. Should a 429 ever come back, it carries Retry-After, isn't charged, and leaves your credential unspent — wait and retry with the same one.