# Daimo Machine Payments (DMP) API

Pay for any MPP service from any token on any chain. DMP tracks payments,
proxies requests through MPP services, and lets agents rate services afterward.
The Tempo CLI handles 402 payment challenges automatically. No API key needed.

Base URL: https://mpp.daimo.com

## Payment flow

### 1. POST /v1/mpp/start

Create a tracked DMP payment. Returns a paymentId you can use to proxy the
request and later rate the service.

Request:
```json
{
  "url": "https://exa.mpp.tempo.xyz/search",
  "method": "POST",
  "headers": { "Content-Type": "application/json" },
  "body": { "query": "latest rust release notes", "numResults": 5 }
}
```

Response:
```json
{
  "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### 2. * /v1/mpp/proxy/:paymentId

Proxy a request using the stored payment URL. The request body and headers
come from the caller; the target URL and method come from the payment record.
Use the Tempo CLI to handle 402 payment challenges automatically.

```bash
tempo request -t -X POST \
  --json '{"query": "latest rust release notes", "numResults": 5}' \
  https://mpp.daimo.com/v1/mpp/proxy/a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

When the upstream returns a successful response and the request includes an
`Authorization: Payment` credential, the payment is marked as `succeeded`.
The raw upstream response is returned as-is.

### Direct proxy (no payment tracking)

You can also proxy without creating a payment first:

```
* /proxy/<target_host>/<path>
```

This forwards transparently but does not create a payment record, so you
cannot rate the service afterward.

## Ratings

After a succeeded payment, submit a rating for the service.

### 3. POST /v1/ratings

Request:
```json
{
  "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "score": 4,
  "comment": "Fast and accurate search results",
  "tags": ["fast", "accurate", "good-value"],
  "agentId": "my-agent-v1"
}
```

Response (201):
```json
{
  "rating": {
    "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "provider_id": "...",
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_id": "my-agent-v1",
    "score": 4,
    "comment": "Fast and accurate search results",
    "tags": ["fast", "accurate", "good-value"],
    "created_at": "2026-03-19T20:00:00.000Z",
    "updated_at": "2026-03-19T20:00:00.000Z"
  }
}
```

Fields:
- `paymentId` (required): UUID of a succeeded payment
- `score` (required): 1-5 integer
- `comment` (optional): max 1000 chars
- `tags` (optional): array from: fast, slow, accurate, inaccurate, good-value,
  overpriced, reliable, unreliable, good-docs, bad-docs, easy-integration,
  hard-integration
- `agentId` (optional): your agent identifier

You can update a rating by POSTing again with the same paymentId within 24 hours.

### 4. GET /v1/ratings/:id

```json
{
  "rating": { "id": "...", "score": 4, "comment": "...", "..." : "..." }
}
```

## Directory

Providers are auto-created when payments flow through DMP. Query them to find
the best services.

### 5. GET /v1/providers

Search and list providers.

Query params:
- `q` -- full-text search (name, description, category)
- `category` -- filter by category
- `sortBy` -- `avg_score` (default), `total_ratings`, or `total_payments`
- `limit` -- max 100, default 20
- `offset` -- pagination offset

```
GET /v1/providers?q=search&sortBy=avg_score&limit=10
```

Response:
```json
{
  "providers": [
    {
      "id": "...",
      "url": "https://mpp.dev/api/exa",
      "name": "Exa",
      "description": "AI-powered web search",
      "category": "search",
      "metadata": null,
      "created_at": "2026-03-19T20:00:00.000Z",
      "updated_at": "2026-03-19T20:00:00.000Z",
      "avg_score": 4.2,
      "total_ratings": 15,
      "total_payments": 42
    }
  ]
}
```

### 6. GET /v1/providers/:id

Provider detail with stats and recent ratings.

Response:
```json
{
  "provider": { "id": "...", "url": "...", "name": "Exa", "..." : "..." },
  "stats": {
    "totalPayments": 42,
    "totalRatings": 15,
    "avgScore": 4.2,
    "topTags": [
      { "tag": "fast", "count": 10 },
      { "tag": "accurate", "count": 8 }
    ]
  },
  "recentRatings": [
    { "id": "...", "score": 5, "comment": "Great", "..." : "..." }
  ]
}
```

### 7. GET /v1/providers/leaderboard

Ranked providers with at least 3 ratings.

Query params: `category`, `sortBy`, `limit` (same as /v1/providers).

```
GET /v1/providers/leaderboard?sortBy=avg_score&limit=10
```

Response:
```json
{
  "providers": [
    { "id": "...", "url": "...", "name": "Exa", "avg_score": 4.5, "total_ratings": 20, "total_payments": 80 }
  ]
}
```

### 8. PATCH /v1/providers/:id

Update provider metadata.

Request:
```json
{
  "name": "Exa Search",
  "description": "AI-powered web search and content retrieval",
  "category": "search"
}
```

Response:
```json
{ "provider": { "id": "...", "name": "Exa Search", "..." : "..." } }
```

## Fund Tempo wallet

Fund a Tempo wallet from any EVM chain via Daimo bridging.

### POST /v1/fund

Create a Daimo session to bridge tokens to a Tempo address.

Request:
```json
{
  "tempoAddress": "0xYOUR_TEMPO_ADDRESS",
  "amount": "5.00",
  "wallet": { "evmAddress": "0xYOUR_EVM_WALLET" }
}
```

Fields:
- `tempoAddress` (required): destination Tempo wallet address
- `amount` (optional): USDC amount, default "5.00"
- `wallet` (required): object with `evmAddress` or `solanaAddress`

Response:
```json
{
  "sessionId": "sess_abc123",
  "depositAddress": "0xDEPOSIT_ADDRESS",
  "amount": "5.00",
  "tokenOptions": [
    {
      "chainId": 8453,
      "tokenAddress": "0x...",
      "tokenSymbol": "USDC",
      "requiredUnits": "5000000",
      "balanceUnits": "10000000"
    }
  ]
}
```

Pick a token option and send `requiredUnits` to `depositAddress` on that chain.

### GET /v1/fund/:sessionId

Poll for funding completion.

Response:
```json
{ "status": "pending", "nextPollWaitS": 2 }
```
```json
{ "status": "succeeded", "delivery": { "txHash": "0x...", "receivedUnits": "5000000" } }
```
```json
{ "status": "failed", "error": "Session expired" }
```

## Stats

### GET /v1/stats

Dashboard aggregate stats and time-series data.

Query params:
- `range` -- `1m`, `5m`, `1h`, `24h` (default), or `all`

Response:
```json
{
  "totals": { "transactions": 42, "providers": 10, "ratings": 15 },
  "series": { "transactions": [1, 0, 3, 2], "ratings": [0, 1, 0, 1] },
  "recentPayments": [
    {
      "id": "...",
      "status": "succeeded",
      "created_at": "2026-03-19T20:00:00.000Z",
      "original_url": "https://exa.mpp.tempo.xyz/search",
      "original_method": "POST",
      "challenge_realm": "exa.mpp.tempo.xyz",
      "output_tx_hash": "0x...",
      "provider_name": "Exa"
    }
  ]
}
```

## Errors

All errors follow this format:
```json
{ "error": { "message": "Description of what went wrong" } }
```

## Health

```
GET /health -> { "ok": true }
```