Machine Payments (MPP)

Overview

Tako supports the Machine Payments Protocol (MPP) — 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

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

Agent frameworks like mppx 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:

{
  "query": "Tesla stock price",
  "search_effort": "fast",
  "source_indexes": ["data"]
}

Report generation

Reports use a combined create + dispatch flow:

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:

{
  "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

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

Machine Payments (MPP)

Overview

How It Works

Available Endpoints

Sync endpoints

Async endpoints

Poll endpoints (free)

Payment Methods

Authentication Flow

Paid endpoints

Async endpoints (deep search, reports)

Request format

Report generation

Discovery Manifest

Idempotency

Error Codes

​Overview

​How It Works

​Available Endpoints

​Sync endpoints

​Async endpoints

​Poll endpoints (free)

​Payment Methods

​Authentication Flow

​Paid endpoints

​Async endpoints (deep search, reports)

​Request format

​Report generation

​Discovery Manifest

​Idempotency

​Error Codes

Overview

How It Works

Available Endpoints

Sync endpoints

Async endpoints

Poll endpoints (free)

Payment Methods

Authentication Flow

Paid endpoints

Async endpoints (deep search, reports)

Request format

Report generation

Discovery Manifest

Idempotency

Error Codes