# MPP - Machine Payments Protocol

## What is MPP?

The **Machine Payments Protocol (MPP)** is an IETF-based HTTP authentication scheme that enables AI agents and automated systems to pay for API access on a per-request basis. Instead of requiring API keys and subscriptions, MPP lets machines pay for each API call using the standard HTTP `402 Payment Required` flow.

Tomba's MPP integration is available at **[agents.tomba.io](https://agents.tomba.io)** and powered by [InFlow](https://inflowpay.ai), supporting both **fiat** (USD) and **crypto** (USDC) payments.

## Why MPP?

| Traditional API Access          | MPP Access                            |
| ------------------------------- | ------------------------------------- |
| Requires account registration   | No account needed                     |
| API key + secret authentication | Payment replaces authentication       |
| Monthly subscription plans      | Pay-per-request pricing               |
| Usage quotas and limits         | Pay for what you use                  |
| Manual billing management       | Automated machine-to-machine payments |

## How It Works

MPP follows a simple challenge-response flow:

<Mermaid
    chart={`sequenceDiagram
    participant Agent as AI Agent (Buyer)
    participant Agents as agents.tomba.io
    participant Tomba as api.tomba.io
    participant InFlow as InFlow Payment Network
    Agent->>Agents: GET /domain-search?domain=example.com
    Agents-->>Agent: 402 Payment Required + WWW-Authenticate: Payment
    Agent->>InFlow: Create payment transaction
    InFlow-->>Agent: Payment credential
    Agent->>Agents: GET /domain-search (Authorization: Payment)
    Agents->>Tomba: Proxy to api.tomba.io/v1/domain-search
    Tomba-->>Agents: 200 OK + data
    Agents-->>Agent: 200 OK + data + Payment-Receipt header`}
/>

### Step-by-Step

1. **Request** — The AI agent calls a Tomba agent endpoint (e.g., `agents.tomba.io/domain-search`)
2. **Challenge** — The proxy returns `402 Payment Required` with a payment challenge in the `WWW-Authenticate` header
3. **Pay** — The agent's MPP buyer (via mppx CLI) creates a payment transaction with InFlow
4. **Retry** — The agent retries the request with `Authorization: Payment <credential>`
5. **Proxy** — agents.tomba.io verifies the payment, then proxies the request to `api.tomba.io`
6. **Receipt** — A `Payment-Receipt` header is included in the response for proof of payment

## Base URL

```
https://agents.tomba.io
```

## Available Endpoints

All Tomba API tools are available as pay-per-request endpoints:

| Endpoint               | Description                   |
| ---------------------- | ----------------------------- |
| `GET /domain-search`   | Search emails by domain       |
| `GET /email-finder`    | Find email by name + domain   |
| `GET /email-verifier`  | Verify an email address       |
| `GET /email-count`     | Count emails for a domain     |
| `GET /email-sources`   | Find email sources            |
| `GET /email-format`    | Get email format for a domain |
| `GET /author-finder`   | Find author email from URL    |
| `GET /enrich`          | Enrich an email address       |
| `GET /linkedin`        | Find email from LinkedIn URL  |
| `GET /phone-finder`    | Find phone by email/domain    |
| `GET /phone-validator` | Validate a phone number       |
| `GET /similar`         | Find similar domains          |
| `GET /location`        | Get location data             |
| `GET /people/find`     | People enrichment             |
| `GET /companies/find`  | Company enrichment            |
| `GET /combined/find`   | Combined enrichment           |

### Discovery Endpoints

| Endpoint                           | Description                   |
| ---------------------------------- | ----------------------------- |
| `GET /`                            | Agent commerce index (JSON)   |
| `GET /.well-known/agent-card.json` | Agent card                    |
| `GET /.well-known/mpp.json`        | MPP config and pricing        |
| `GET /openapi.json`                | OpenAPI 3.1 spec              |
| `GET /llms.txt`                    | LLM-friendly docs             |
| `GET /skill.md`                    | Skill file with mppx examples |

## Supported Payment Rails

| Rail        | Description               |
| ----------- | ------------------------- |
| `tempo_mpp` | MPP via InFlow / mppx CLI |
| `x402_base` | x402 USDC on Base         |

## Supported Currencies

| Currency | Rail         | Description                          |
| -------- | ------------ | ------------------------------------ |
| `USDC`   | `balance`    | Crypto stablecoin via InFlow balance |
| `USDT`   | `balance`    | Crypto stablecoin via InFlow balance |
| `USD`    | `instrument` | Fiat USD via payment instrument      |
| `EUR`    | `instrument` | Fiat EUR via payment instrument      |

## Pricing

MPP pricing is based on **$9.80 per 1,000 credits** (1 credit = 1 API request), which works out to **$0.0098 USDC per request**. The exact amount is included in every `402` challenge response.