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

# Machine Spend

> Read unified x402 and MPP service-spend analytics for an agent

# Machine Spend

Machine Spend gives you a unified read layer over paid service usage recorded through Conto's x402 and MPP flows.

Use it to answer questions like:

* Which paid services is this agent using most?
* Which endpoints are driving the most spend?
* Is spend concentrated in x402, MPP, or both?
* Are there active x402 or MPP anomaly alerts for this agent?

<Info>
  Machine Spend is additive to existing x402 and MPP tracking. It does not replace protocol-specific
  endpoints like `/api/sdk/x402/services` or `/api/sdk/mpp/budget`; it gives you one combined view
  on top of them.
</Info>

## What It Includes

The machine-spend endpoints aggregate existing `A2S` transactions and protocol alerts into a shared view:

* total spend and call volume
* service-level breakdowns
* endpoint-level breakdowns
* x402 vs MPP split
* micropayment counts
* recent x402 / MPP anomaly alerts

This is especially useful when one agent uses multiple paid APIs across both protocols.

## Authentication

These endpoints use the normal **agent SDK key** flow:

```bash theme={null}
Authorization: Bearer conto_agent_xxx
```

Required scope:

* `analytics:read`

## Get a Summary

Returns a top-level summary plus recent machine-spend alerts for the authenticated agent.

```bash theme={null}
curl "https://conto.finance/api/sdk/service-spend/summary?period=30d&protocol=all" \
  -H "Authorization: Bearer $CONTO_API_KEY"
```

### Query Parameters

| Parameter  | Type   | Default | Description                       |
| ---------- | ------ | ------- | --------------------------------- |
| `period`   | string | `30d`   | One of `24h`, `7d`, `30d`, `all`  |
| `protocol` | string | `all`   | One of `all`, `x402`, `mpp`       |
| `limit`    | number | `10`    | Number of recent alerts to return |

### Example Response

```json theme={null}
{
  "filters": {
    "period": "30d",
    "protocol": "all",
    "agentId": "cmm5a1agt002n49h7bjqza33r",
    "startDate": "2026-03-18T00:00:00.000Z"
  },
  "summary": {
    "totalSpend": 14.73,
    "totalCalls": 219,
    "activeServices": 6,
    "activeAgents": 1,
    "activeAlerts": 1,
    "micropaymentTransactions": 188,
    "x402Spend": 4.12,
    "x402Calls": 173,
    "mppSpend": 10.61,
    "mppCalls": 46
  },
  "recentAlerts": [
    {
      "id": "cmm5j0alr000l49h7ktzbj11p",
      "protocol": "x402",
      "alertType": "X402_PRICE_SPIKE",
      "severity": "MEDIUM",
      "status": "ACTIVE",
      "title": "x402 price spike: api.example.com",
      "message": "api.example.com is charging more than its historical average",
      "createdAt": "2026-04-16T19:02:11.000Z",
      "organizationName": "Acme",
      "agentName": "research-agent"
    }
  ]
}
```

## List Services And Endpoints

Returns the top service domains and endpoints for the authenticated agent.

```bash theme={null}
curl "https://conto.finance/api/sdk/service-spend/services?period=7d&protocol=x402&limit=20" \
  -H "Authorization: Bearer $CONTO_API_KEY"
```

### Query Parameters

| Parameter  | Type   | Default | Description                              |
| ---------- | ------ | ------- | ---------------------------------------- |
| `period`   | string | `30d`   | One of `24h`, `7d`, `30d`, `all`         |
| `protocol` | string | `all`   | One of `all`, `x402`, `mpp`              |
| `limit`    | number | `10`    | Number of services / endpoints to return |

### Example Response

```json theme={null}
{
  "filters": {
    "period": "7d",
    "protocol": "x402",
    "agentId": "cmm5a1agt002n49h7bjqza33r",
    "startDate": "2026-04-10T00:00:00.000Z"
  },
  "services": [
    {
      "protocol": "x402",
      "serviceDomain": "api.example.com",
      "totalSpend": 2.41,
      "totalCalls": 120,
      "avgPricePerCall": 0.0201,
      "minPricePerCall": 0.01,
      "maxPricePerCall": 0.05,
      "firstActivityAt": "2026-04-11T03:44:52.000Z",
      "lastActivityAt": "2026-04-16T21:08:17.000Z"
    }
  ],
  "endpoints": [
    {
      "protocol": "x402",
      "resourceUrl": "https://api.example.com/search",
      "serviceDomain": "api.example.com",
      "totalSpend": 1.84,
      "totalCalls": 92,
      "avgPricePerCall": 0.02,
      "lastActivityAt": "2026-04-16T21:08:17.000Z"
    }
  ]
}
```

## When To Use Machine Spend vs Protocol-Specific Endpoints

Use **Machine Spend** when you want a unified service view across both protocols.

Use **protocol-specific endpoints** when you need details unique to one rail:

* `/api/sdk/x402/services` for x402 service-specific stats
* `/api/sdk/x402/budget` for x402 burn rate and policy limit views
* `/api/sdk/mpp/services` for MPP service-specific stats
* `/api/sdk/mpp/budget` for MPP session and budget views

## Dashboard View

Conto also exposes this data in the dashboard, where you can:

* filter by protocol and time window
* compare top services and endpoints
* inspect top agents and organizations
* review recent x402 / MPP anomaly alerts

## Next Steps

<CardGroup cols={2}>
  <Card title="x402 Payments" icon="bolt" href="/sdk/x402-payments">
    Record and control pay-per-call API spend
  </Card>

  <Card title="MPP Payments" icon="clock" href="/sdk/mpp-payments">
    Track session-based micropayment usage
  </Card>
</CardGroup>