> ## 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.

# Agentic Payments

> Search products and place purchases from API, CLI, or MCP using one simple flow.

Use Agentic Payments when you want one simple way to shop with Machines.

<Tip>
  This demo uses our <a href="https://docs.machines.cash/claude-plugin">Claude plugin</a>.

  <video autoPlay muted loop playsInline controls className="w-full aspect-video rounded-xl mt-4" src="https://mintcdn.com/machines-cash/wD9cDhPLICvgzhJl/videos/claude-purchase-full.mp4?fit=max&auto=format&n=wD9cDhPLICvgzhJl&q=85&s=5ccad667e12a7fbcdc9ffa860f2fc5cb" data-path="videos/claude-purchase-full.mp4" />
</Tip>

The same flow works across API, CLI, and MCP:

* `search` finds an item or resolves a direct URL
* `buy` starts the purchase
* `actions` let you confirm, check progress, or submit a 3DS code

<Tip>
  Current launch default: shopping flows default to Amazon. In the current API, the search route is still named `/agent/v1/browser` for compatibility.
</Tip>

## What you usually need

In most cases, nothing beyond the item itself:

* a product URL or shopping query
* an authenticated Machines session

If the user already has an active Machines card and saved billing profile, Machines uses them automatically.

## The shared flow

Every purchase returns an `actionId`. That makes the flow portable across surfaces.

You can start a purchase in one place and continue it in another:

* start in API, check status in CLI
* start in MCP, submit 3DS over API
* start in CLI, confirm from MCP

Possible action states:

| Status                  | Meaning                                                  |
| ----------------------- | -------------------------------------------------------- |
| `awaiting_confirmation` | Machines is waiting for the user to confirm the purchase |
| `processing`            | The purchase is in progress                              |
| `awaiting_3ds`          | A 3DS verification code is required                      |
| `completed`             | The purchase finished successfully                       |
| `failed`                | The purchase stopped with a terminal error               |
| `expired`               | The action or quote expired before completion            |

## Quickstart

### 1. Search for a product

The simplest read-only path is a query string:

```bash theme={null}
curl -s \
  -H 'Authorization: Bearer <USER_SESSION_TOKEN>' \
  'https://api.machines.cash/agent/v1/browser?q=apple%20airpods%20pro'
```

Structured search requests use `POST /agent/v1/browser`:

```bash theme={null}
curl -s \
  -X POST \
  -H 'Authorization: Bearer <USER_SESSION_TOKEN>' \
  -H 'Content-Type: application/json' \
  https://api.machines.cash/agent/v1/browser \
  -d '{
    "input": "airpods pro 3",
    "provider": "amazon",
    "limit": 3
  }'
```

Example response:

```json theme={null}
{
  "status": "resolved",
  "items": [
    {
      "title": "Apple AirPods Pro",
      "price": "$249.00",
      "url": "https://www.amazon.com/dp/B0DGHMNQ5Q",
      "provider": "amazon"
    }
  ],
  "selectedItem": {
    "title": "Apple AirPods Pro",
    "price": "$249.00",
    "url": "https://www.amazon.com/dp/B0DGHMNQ5Q",
    "provider": "amazon"
  },
  "next": {
    "buyInput": {
      "url": "https://www.amazon.com/dp/B0DGHMNQ5Q",
      "provider": "amazon"
    }
  }
}
```

### 2. Start a purchase

Use `POST /agent/v1/buy` to start checkout.

If the user already has a Machines card and billing profile, this is usually enough:

```bash theme={null}
curl -s \
  -X POST \
  -H 'Authorization: Bearer <USER_SESSION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UNIQUE_KEY>' \
  https://api.machines.cash/agent/v1/buy \
  -d '{
    "url": "https://www.amazon.com/dp/B0DGHMNQ5Q"
  }'
```

You can also override the saved card selector:

```bash theme={null}
curl -s \
  -X POST \
  -H 'Authorization: Bearer <USER_SESSION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UNIQUE_KEY>' \
  https://api.machines.cash/agent/v1/buy \
  -d '{
    "url": "https://www.amazon.com/dp/B0DGHMNQ5Q",
    "card": "<card-label-or-last4>"
  }'
```

Example response:

```json theme={null}
{
  "actionId": "543720cb-edb5-4651-90bc-7068ce133668",
  "status": "awaiting_confirmation",
  "message": "purchase prepared and awaiting user confirmation",
  "nextStep": {
    "type": "confirm",
    "message": "confirm purchase to proceed"
  },
  "item": {
    "title": "Apple AirPods Pro",
    "price": "$249.00",
    "url": "https://www.amazon.com/dp/B0DGHMNQ5Q",
    "provider": "amazon"
  }
}
```

<Note>
  For Amazon orders, Machines uses the provider checkout path for you. You do not need to manage provider-specific payment steps yourself.
</Note>

### 3. Check status

```bash theme={null}
curl -s \
  -H 'Authorization: Bearer <USER_SESSION_TOKEN>' \
  https://api.machines.cash/agent/v1/actions/543720cb-edb5-4651-90bc-7068ce133668
```

Example response:

```json theme={null}
{
  "actionId": "543720cb-edb5-4651-90bc-7068ce133668",
  "status": "awaiting_3ds",
  "message": "3DS verification required. enter the code from your bank",
  "nextStep": {
    "type": "enter_3ds_code",
    "message": "enter the code from your bank"
  }
}
```

### 4. Confirm if needed

If the action is waiting for confirmation:

```bash theme={null}
curl -s \
  -X POST \
  -H 'Authorization: Bearer <USER_SESSION_TOKEN>' \
  https://api.machines.cash/agent/v1/actions/543720cb-edb5-4651-90bc-7068ce133668/confirm
```

<AccordionGroup>
  <Accordion title="If 3DS is requested">
    3DS is an extra bank verification step for some purchases. It does not happen on every order, so you only need this step when the action status is `awaiting_3ds`.

    ```bash theme={null}
    curl -s \
      -X POST \
      -H 'Authorization: Bearer <USER_SESSION_TOKEN>' \
      -H 'Content-Type: application/json' \
      https://api.machines.cash/agent/v1/actions/543720cb-edb5-4651-90bc-7068ce133668/3ds \
      -d '{
        "code": "123456"
      }'
    ```
  </Accordion>
</AccordionGroup>

## CLI

The CLI uses the same flow and the same `/agent/v1` routes.

```bash theme={null}
machines search "apple airpods pro"
machines search "kindle paperwhite"
machines search "ninja air fryer"
machines buy "https://www.amazon.com/dp/B0DGHMNQ5Q"
machines buy "https://www.amazon.com/dp/B0DGHMNQ5Q" --card "<card-label-or-last4>" --wait
machines agent status 543720cb-edb5-4651-90bc-7068ce133668
machines agent confirm 543720cb-edb5-4651-90bc-7068ce133668
machines agent 3ds 543720cb-edb5-4651-90bc-7068ce133668 --code 123456
```

<Note>
  `machines search` is the preferred command. `machines browser` still works as a compatibility alias.
</Note>

CLI defaults:

* if `--card` is omitted, Machines uses the user's default active card and stored billing profile
* `--wait` and `--watch` keep polling until the action pauses or finishes
* raw card input is file or stdin only through `--payment-card-file`

## MCP and AI apps

Machines MCP uses the same flow. The user does not need to paste billing details or card numbers when their Machines account is already set up.

Useful prompts:

* `buy these apple airpods pro on amazon using my default card`
* `search apple airpods pro on amazon`
* `search kindle paperwhite on amazon`
* `search ninja air fryer on amazon`
* `search anker usb c charger on amazon`
* `check the status for action 543720cb-edb5-4651-90bc-7068ce133668`
* `confirm my pending purchase`
* `submit this 3ds code for my purchase: 123456`

If you are calling tools directly, use:

* `machines.agent.browser`
* `machines.agent.buy`
* `machines.agent.action_status`
* `machines.agent.action_confirm`
* `machines.agent.action_submit_3ds`

## Request fields

### Search request

```json theme={null}
{
  "input": "apple airpods pro",
  "provider": "amazon",
  "limit": 3,
  "locale": "en-US"
}
```

### Buy request

```json theme={null}
{
  "url": "https://www.amazon.com/dp/B0DGHMNQ5Q",
  "provider": "amazon",
  "card": "<card-label-or-last4>"
}
```

Notes:

* `card` is a saved-card selector, such as a card label or a last 4 selector
* if `card` is omitted, Machines uses the default active card
* direct API and CLI flows may also accept a one-time `paymentCard`, but MCP does not

## More example searches

```bash theme={null}
machines search "apple airpods pro"
machines search "kindle paperwhite"
machines search "ninja air fryer"
machines search "lego botanical orchid"
machines search "anker usb c charger"
```

## Next steps

* <a href="/cli">Machines CLI</a> for terminal usage
* <a href="/mcp-setup">MCP Setup</a> for AI app connections
* <a href="/consumer-api-reference">Consumer API Reference</a> for the broader user API