> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Machine Payments (MPP)

> Let AI agents pay per-request to use Tako APIs via the Machine Payments Protocol

## Overview

Tako supports the [Machine Payments Protocol (MPP)](https://mpp.dev/) — an open standard for machine-to-machine payments via HTTP 402. This allows AI agents to discover and pay for Tako API access automatically, without requiring API keys or account signup.

## How It Works

1. **Discovery** — Agents find Tako's available endpoints at `https://tako.com/.well-known/mpp.json`
2. **402 Challenge** — When an agent calls an MPP endpoint without payment, Tako returns `402 Payment Required` with pricing info
3. **Payment** — The agent pays via Stripe or Tempo stablecoins
4. **Access** — The agent retries with a payment credential and gets the response

Agent frameworks like [mppx](https://mpp.dev/) handle this flow automatically — from the agent's perspective, it's a single API call.

## Available Endpoints

### Sync endpoints

| Endpoint                     | Method | Description                                  |
| ---------------------------- | ------ | -------------------------------------------- |
| `/api/mpp/v1/search/fast`    | POST   | Fast data search                             |
| `/api/mpp/v1/visualize`      | POST   | Visualize data from a search query           |
| `/api/mpp/v1/thinviz/create` | POST   | Create a ThinViz card from components        |
| `/api/mpp/v1/charts/edit`    | POST   | Edit a chart using a natural language prompt |

### Async endpoints

These endpoints return `202 Accepted` with a task ID. Poll the corresponding status endpoint using the receipt token from the `Payment-Receipt` header.

| Endpoint                       | Method | Description                              | Poll endpoint                | Expected duration |
| ------------------------------ | ------ | ---------------------------------------- | ---------------------------- | ----------------- |
| `/api/mpp/v1/threads/deep`     | POST   | Deep knowledge search with full pipeline | `/api/mpp/v1/threads/status` | 30s – 10 min      |
| `/api/mpp/v1/reports/generate` | POST   | Generate a research report               | `/api/mpp/v1/reports/status` | 10 – 30 min       |

### Poll endpoints (free)

| Endpoint                     | Method | Description                       |
| ---------------------------- | ------ | --------------------------------- |
| `/api/mpp/v1/threads/status` | GET    | Poll status for deep search tasks |
| `/api/mpp/v1/reports/status` | GET    | Poll status for report generation |

Poll endpoints are free — authenticate with `Authorization: MPP receipt <token>` using the receipt from the original paid request.

Live pricing is available at `https://tako.com/.well-known/mpp.json`.

## Payment Methods

* **Stripe** — Pay via Stripe PaymentIntent. Agents need a pre-configured Stripe customer with a payment method.
* **Tempo** — Pay via Tempo stablecoin on-chain transaction.

## Authentication Flow

### Paid endpoints

```
# 1. Agent calls endpoint with no auth
POST /api/mpp/v1/search/fast

# 2. Tako returns 402 with challenge headers
HTTP/1.1 402 Payment Required
WWW-Authenticate: MPP realm="tako"
MPP-Price: 0.036667 USD
MPP-Payment-Methods: stripe, tempo

# 3. Agent pays and retries with credential
POST /api/mpp/v1/search/fast
Authorization: MPP stripe pi_xxxxx

# 4. Tako verifies payment and returns response
HTTP/1.1 200 OK
Payment-Receipt: <receipt-token>
```

### Async endpoints (deep search, reports)

Async endpoints return `202 Accepted` immediately. Use the receipt token to poll for results.

```
# 1. Submit a deep search (paid)
POST /api/mpp/v1/threads/deep
Authorization: MPP stripe pi_xxxxx
Content-Type: application/json

{
  "knowledge_search_request": {
    "inputs": {"text": "How has NVIDIA's revenue grown vs AMD?"}
  },
  "skip_routing": true
}

# 2. Receive 202 with task ID and receipt
HTTP/1.1 202 Accepted
Payment-Receipt: <receipt-token>

{"task_id": "abc-123", "thread_id": "thread-456", "status": "pending"}

# 3. Poll for results (free, receipt-authenticated)
GET /api/mpp/v1/threads/status?task_id=abc-123
Authorization: MPP receipt <receipt-token>

# 4. Completed response includes full results with charts
HTTP/1.1 200 OK
{"status": "completed", "result": {...}}
```

Poll every 5–10 seconds for deep search, every 30–60 seconds for reports.

Status values: `pending`, `in_progress`, `completed`, `failed`. Use the `since_index` query param for incremental event polling.

### Request format

MPP endpoints accept the same request body as their non-MPP counterparts. For example, `/api/mpp/v1/search/fast` accepts the same body as `/v1/knowledge_search`:

```json theme={null}
{
  "query": "Tesla stock price",
  "search_effort": "fast",
  "source_indexes": ["data"]
}
```

### Report generation

Reports use a combined create + dispatch flow:

```json theme={null}
POST /api/mpp/v1/reports/generate

{
  "report_type": "memo",
  "title": "NVIDIA Competitive Analysis",
  "config": {"query": "NVIDIA competitive landscape and market position"}
}
```

Poll with `GET /api/mpp/v1/reports/status?report_id=<report_id>`.

## Discovery Manifest

Agents can discover all MPP-enabled endpoints at:

```
GET https://tako.com/.well-known/mpp.json
```

Response:

```json theme={null}
{
  "version": "1.0",
  "provider": "tako",
  "description": "Tako data visualization and research platform",
  "endpoints": [
    {
      "path": "/api/mpp/v1/search/fast",
      "method": "POST",
      "price": {"amount": "0.036667", "currency": "USD"},
      "response_type": "sync",
      "description": "Fast data search"
    },
    {
      "path": "/api/mpp/v1/threads/deep",
      "method": "POST",
      "price": {"amount": "0.550000", "currency": "USD"},
      "response_type": "async",
      "poll_path": "/api/mpp/v1/threads/status",
      "description": "Deep async knowledge search with full pipeline"
    }
  ],
  "payment_methods": ["stripe", "tempo"]
}
```

## Idempotency

To handle network failures, include an `Idempotency-Key` header. If the payment was processed but the response was lost, retrying with the same key returns the cached response instead of charging again.

```
POST /api/mpp/v1/search/fast
Authorization: MPP stripe pi_xxxxx
Idempotency-Key: my-unique-request-id
```

## Error Codes

| Status | Meaning                                            |
| ------ | -------------------------------------------------- |
| 402    | Payment required — includes MPP challenge headers  |
| 400    | Malformed credential or unsupported payment method |
| 409    | Payment credential already used (replay)           |
| 401    | Invalid receipt token (poll endpoints)             |
| 429    | Rate limit exceeded — back off and retry           |