# Tomba Agent Commerce API

> B2B contact intelligence for AI agents. Find, verify, and enrich email addresses.

## Base URL
https://agents.tomba.io

## Pricing
0.0098 USDC per request ($9.80 per 1,000 requests)

Payable in USDC or USDT. One WWW-Authenticate challenge is issued
per currency and the buyer picks one — a buyer does NOT automatically choose the currency
it can afford, so select deliberately if you hold only one.

## Payment Rails
- MPP (Machine Payments Protocol), settled through InFlow

## How to Pay
curl -fsSL https://inflowcli.ai/install.sh | bash
inflow auth login --client-name "<your-agent-name>"
inflow mpp pay https://agents.tomba.io/domain-search?domain=example.com

See which currencies a challenge offers before paying:
  inflow mpp inspect https://agents.tomba.io/domain-search?domain=example.com

See what your own account can pay with:
  inflow mpp supported

No API key or account registration needed — payment replaces authentication.

## Billing
You are charged only when Tomba returns a usable answer.

- Success: the response carries X-Payment-Charged: true and a Payment-Receipt header.
- Error, empty result, or upstream failure: nothing settles, the response carries
  X-Payment-Charged: false, and your credential stays spendable — fix the request and
  retry with the same one.
- A valid negative answer still costs: email-verifier reporting "undeliverable", or a
  domain with no contacts, is a real answer and is billed.
- Credentials are bound to one endpoint. A credential bought for /domain-search cannot
  be spent on /email-verifier.

## Discovery
- ODP service document: https://agents.tomba.io/.well-known/odp (catalog of every endpoint as an Offering)
- AEP inspect document: https://agents.tomba.io/.well-known/aep (optional agent enrollment; it unlocks
  nothing — every endpoint stays payment-gated whether you enroll or not)

## Endpoints

- GET /domain-search: Find all email addresses associated with a company domain.  Params: domain, company, limit, page, department, country
- GET /email-finder: Find a person's email address from their name and company domain.  Params: domain, company, full_name, first_name, last_name
- GET /email-verifier: Verify if an email address is valid and deliverable.  Params: email
- GET /email-count: Count the number of email addresses available for a domain.  Params: domain
- GET /email-sources: Find sources where an email address has been found.  Params: email
- GET /email-format: Get the email format used by a domain.  Params: domain
- GET /author-finder: Find the email address of the author of an article.  Params: url
- GET /enrich: Enrich an email address with contact and company data.  Params: email
- GET /linkedin: Find a person's email from their LinkedIn profile URL.  Params: url
- GET /phone-finder: Find phone numbers from an email, domain, or LinkedIn.  Params: email, domain, linkedin
- GET /phone-validator: Validate a phone number and get carrier details.  Params: phone
- GET /similar: Find domains similar to a given domain.  Params: domain
- GET /location: Get location data for a domain.  Params: domain
- GET /people/find: People enrichment — find person data by domain.  Params: domain
- GET /companies/find: Company enrichment — get company data by domain.  Params: domain
- GET /domain-status: Check whether a domain is webmail or disposable.  Params: domain
- GET /domain-suggestions: Find domain suggestions for a company or domain name.  Params: query
- GET /technology: Retrieve the technologies used by a domain.  Params: domain
- GET /combined/find: Combined person and company enrichment.  Params: domain

## Example Flows

### Find emails at a company
GET /domain-search?domain=stripe.com

### Find a specific person's email
GET /email-finder?domain=stripe.com&first_name=John&last_name=Doe

### Verify an email
GET /email-verifier?email=john@example.com

### Enrich a contact
GET /enrich?email=ceo@company.com

### Find phone numbers
GET /phone-finder?email=user@company.com

### Company enrichment
GET /companies/find?domain=stripe.com

## Discovery Files
- Agent Card: https://agents.tomba.io/.well-known/agent-card.json
- MPP Config: https://agents.tomba.io/.well-known/mpp.json
- ODP Service Document: https://agents.tomba.io/.well-known/odp
- AEP Inspect Document: https://agents.tomba.io/.well-known/aep
- Offering attribute schema: https://agents.tomba.io/schemas/offering-attributes.json
- OpenAPI: https://agents.tomba.io/openapi.json
- Skill file: https://agents.tomba.io/skill.md
- Health: https://agents.tomba.io/health (add ?deep=1 to prove the payment gate can mint a challenge)
- This file: https://agents.tomba.io/llms.txt

## Policies
- All responses are JSON
- Rate limits are enforced per endpoint and per plan (per-second, per-minute, per-day).
  Every response carries the upstream rate limit headers (RateLimit, RateLimit-Policy,
  x-minute-request-left, x-daily-request-left, x-minute-reset-seconds, x-daily-reset-seconds).
  On 429, check Retry-After. Details: https://docs.tomba.io/rate-limits
- Data source: Tomba.io B2B contact database
- Terms of Service: https://tomba.io/legal/terms-of-service
- Privacy Policy: https://tomba.io/legal/privacy-policy
- GDPR: https://tomba.io/legal/gdpr
- Security Policy: https://tomba.io/legal/security-policy
- Cookie Policy: https://tomba.io/legal/cookie-policy
- Crawling & Robots: https://tomba.io/legal/robot

## Contact
- Email: info@tomba.io
- Website: https://tomba.io
- Documentation: https://docs.tomba.io/mpp/introduction