Skip to main content
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:
StatusMeaning
awaiting_confirmationMachines is waiting for the user to confirm the purchase
processingThe purchase is in progress
awaiting_3dsA 3DS verification code is required
completedThe purchase finished successfully
failedThe purchase stopped with a terminal error
expiredThe 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
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

​
More example searches

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