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

# Consumer API Reference

> Full reference for /consumer/v1 endpoints used by users, agents, and MCP clients.

This is the full consumer API surface.

Use this when you are building an agent or automation for a Machines account.

<CardGroup cols={3}>
  <Card title="Auth and key lifecycle" icon="key" href="POST /consumer/v1/bootstrap">
    Bootstrap, key management, and scoped sessions.
  </Card>

  <Card title="Crypto helpers" icon="shield" href="POST /consumer/v1/crypto/encrypt">
    Encrypt and decrypt labels for user-safe display.
  </Card>

  <Card title="Agentic Payments" icon="shopping-bag" href="/agentic-payments">
    Search products, buy, and continue purchase steps with one shared flow.
  </Card>
</CardGroup>

## Base URL

`https://api.machines.cash`

Canonical consumer routes are under `/consumer/v1`.

Agent task routes are separate and live under `/agent/v1`.

The main task routes are:

* `GET /agent/v1/browser`
* `POST /agent/v1/browser`
* `POST /agent/v1/buy`
* `GET /agent/v1/actions/:actionId`
* `POST /agent/v1/actions/:actionId/confirm`
* `POST /agent/v1/actions/:actionId/3ds`

See <a href="/agentic-payments">Agentic Payments</a> for the quickstart and examples.

MCP runtime compatibility:

* tools are under `machines.consumer.*`
* agentic commerce tools are under `machines.agent.*`
* resources are under `machines://consumer/*`
* `machines.user.cards.list` is the user-friendly cards listing tool

## Authentication

* Consumer API key header (for session minting): `X-Consumer-Key`
* Consumer session bearer (for operations): `Authorization: Bearer <token>`
* Web session helper: `POST /identity/consumer-api-keys`

## Bootstrap Signing Message

`POST /consumer/v1/bootstrap` accepts either template below (exact line order and newlines).

Preferred (simpler):

```text theme={null}
Machines Cash Bootstrap
Address: <address>
Nonce: <nonce>
Issued At: <issuedAt ISO timestamp>
Expires At: <expiresAt ISO timestamp>
```

Legacy (still accepted):

```text theme={null}
Machines Cash Consumer Agent Bootstrap
Address: <address>
Nonce: <nonce>
Issued At: <issuedAt ISO timestamp>
Expires At: <expiresAt ISO timestamp>
Connector: <connector or unknown>
Chain ID: <chainId or unknown>
Wallet Label: <walletLabel or unknown>
```

Notes:

* Address may be lowercase or checksum.
* Keep bootstrap windows short (recommended around 60 seconds).

## Idempotency

For state-changing financial writes, include `idempotency-key`.

Common required operations include:

* deposits create and transfer

Preview and poll-style operations do not require idempotency.

## Compatibility behavior

* `GET /consumer/v1/users` resolves current user profile (no raw user id required).
* `GET /consumer/v1/agreements` and `POST /consumer/v1/agreements` map to application agreement state/actions.
* `GET /consumer/v1/kyc/status` resolves current user KYC status.

## Blocked endpoint on consumer surface

`GET /consumer/v1/identity/data-key` is intentionally blocked (`403`).

Use:

* `POST /consumer/v1/crypto/encrypt`
* `POST /consumer/v1/crypto/decrypt`

for encryption/decryption workflows.

## Partner API

Partner routes are documented separately:

* <a href="/partner">Partner docs</a>
* <a href="/api-reference">Partner API reference</a>