Agentic Payments

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

This demo uses our Claude plugin.

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

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

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:

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:

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:

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

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:

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:

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

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

3. Check status

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

Example response:

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

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

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.

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"
  }'

CLI

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

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

machines search is the preferred command. machines browser still works as a compatibility alias.

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

{
  "input": "apple airpods pro",
  "provider": "amazon",
  "limit": 3,
  "locale": "en-US"
}

Buy request

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

Next steps

Machines CLI for terminal usage
MCP Setup for AI app connections
Consumer API Reference for the broader user API

Updates

Start

Use Your Own AI

User API

User Auth API

User Crypto API

User KYC API

User Cards API

User Balances & Contracts API

User Deposits API

User Identity API

User Payments API

User Additional API

Agentic Payments

What you usually need

The shared flow

Quickstart

1. Search for a product

2. Start a purchase

3. Check status

4. Confirm if needed

CLI

MCP and AI apps

Request fields

Search request

Buy request

More example searches

Next steps

​What you usually need

​The shared flow

​Quickstart

​1. Search for a product

​2. Start a purchase

​3. Check status

​4. Confirm if needed

​CLI

​MCP and AI apps

​Request fields

​Search request

​Buy request

​More example searches

​Next steps

What you usually need

The shared flow

Quickstart

1. Search for a product

2. Start a purchase

3. Check status

4. Confirm if needed

CLI

MCP and AI apps

Request fields

Search request

Buy request

More example searches

Next steps