> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt > Use this file to discover all available pages before exploring further. # Buy > One conversational endpoint that places real orders. Send the user's request as plain text in `ask`; thread follow-ups with `conversation_id`; place a shown cart by echoing its `hash` in `confirm` (or an array of hashes for several carts). Money only moves on a confirm, and only for exactly the cart the hash describes. ## OpenAPI ````yaml openapi.json POST /buy openapi: 3.1.0 info: title: Agentcard API version: 2.0.0 description: >- The Agentcard v2 API — connect your users and verify their identity from your own backend. Every call is authenticated with a platform access token minted from your `client_id` + `client_secret`. servers: - url: https://api.agentcard.sh description: >- There is one base URL. Sandbox vs production is decided by the client credential you use, never by the host. security: - platformToken: [] tags: - name: Authentication description: >- Exchange your client credentials for a platform access token, and introspect what a token acts as. - name: Connect description: >- Connect a user to your platform: send a one-time code, verify it, record consent, and keep the connection alive. - name: Identity verification description: >- Verify a connected user's identity: upload their ID, submit any extra fields we ask for, then show a short face scan. - name: Wallet funding description: >- Fund a connected user's wallet from your own UI — request a payment link, relay the phone verification code, and poll until the funds land. - name: Withdrawals description: >- Move money out of a connected user's wallet — to a saved bank account or a crypto address on Base. Transfers are processed manually by the Agentcard team, usually within 1-3 business days. paths: /buy: post: tags: - Purchase summary: Buy description: >- One conversational endpoint that places real orders. Send the user's request as plain text in `ask`; thread follow-ups with `conversation_id`; place a shown cart by echoing its `hash` in `confirm` (or an array of hashes for several carts). Money only moves on a confirm, and only for exactly the cart the hash describes. operationId: buy requestBody: required: true content: application/json: schema: type: object properties: ask: type: string description: >- What the user wants, in plain language. Required unless the call is a confirm. minLength: 1 pattern: \S conversation_id: type: string description: The thread to continue. A confirm always requires it. minLength: 1 confirm: description: >- A cart hash from a previous response (16 hex characters), or an array of hashes to place several carts. An array confirm cannot carry an ask in the same call. oneOf: - type: string pattern: ^[0-9a-f]{16}$ - type: array items: type: string pattern: ^[0-9a-f]{16}$ minItems: 1 maxItems: 8 anyOf: - required: - ask - required: - confirm dependentRequired: confirm: - conversation_id not: required: - ask - confirm properties: confirm: type: array examples: ask: summary: Start a purchase value: ask: >- a 16 oz bag of Colombian ground coffee from Amazon, ship it to 1900 Jefferson St, San Francisco confirm: summary: Place a shown cart value: conversation_id: cmsq18x2m00a1 confirm: 9f2c4a1b8e3d5f07 multiCartConfirm: summary: Place several carts value: conversation_id: cmsq18x2m00a1 confirm: - 9f2c4a1b8e3d5f07 - 31d8a6e0c47b92f5 responses: '200': description: One turn of the purchase conversation, in the fixed envelope. content: application/json: schema: type: object description: >- The fixed response envelope. Every field is present on every response, null when empty. properties: conversation_id: type: string description: >- Thread it back on every follow-up. Returned on the first call too. status: type: string enum: - needs_input - order_placed - partially_placed - declined description: >- needs_input is progress, not failure: the reply is a question or a cart waiting on confirmation. reply: type: string description: The assistant's turn as prose, ready to show a human. messages: type: array items: type: string description: >- The same turn split into ordered bubbles for chat surfaces. message_id: type: string cart: type: - object - 'null' description: >- The most recently shown cart. Null when no cart is on the table. properties: merchant: type: string description: Public merchant id, e.g. retail, doordash, goodeggs. merchant_name: type: string description: >- Display name for the merchant, or the store when one is selected (Amazon, Walmart). items: type: array items: type: object properties: name: type: string qty: type: integer priceCents: type: integer required: - name - qty serviceFeesCents: type: integer description: >- All fees combined, including the Agentcard service fee. tipCents: type: integer totalCents: type: integer description: >- The all-in amount a confirm authorizes: merchandise, fees, and tip. hash: type: string description: >- Identity of exactly this cart. Echo it back as confirm to place the order. required: - merchant - merchant_name - items - serviceFeesCents - tipCents - totalCents - hash carts: type: array items: type: object description: >- The most recently shown cart. Null when no cart is on the table. properties: merchant: type: string description: Public merchant id, e.g. retail, doordash, goodeggs. merchant_name: type: string description: >- Display name for the merchant, or the store when one is selected (Amazon, Walmart). items: type: array items: type: object properties: name: type: string qty: type: integer priceCents: type: integer required: - name - qty serviceFeesCents: type: integer description: >- All fees combined, including the Agentcard service fee. tipCents: type: integer totalCents: type: integer description: >- The all-in amount a confirm authorizes: merchandise, fees, and tip. hash: type: string description: >- Identity of exactly this cart. Echo it back as confirm to place the order. required: - merchant - merchant_name - items - serviceFeesCents - tipCents - totalCents - hash description: >- Every open cart in the conversation, oldest first. A conversation can hold carts at several merchants. placements: type: - array - 'null' description: >- Per-cart outcomes of a multi-cart confirm; null on every other call. Partial success is representable here. items: type: object properties: merchant: type: string merchant_name: type: string status: type: string enum: - needs_input - order_placed - partially_placed - declined reply: type: string error_code: type: - string - 'null' required: - merchant - merchant_name - status - reply catalog: type: - object - 'null' description: >- The last product search as data, with a freshness stamp. Null when nothing fresh was searched. properties: merchant: type: string merchant_name: type: string store: type: - object - 'null' properties: id: type: string name: type: string items: type: array items: type: object properties: id: type: string name: type: string priceCents: type: integer required: - id as_of: type: string format: date-time error_code: type: - string - 'null' description: Machine-readable failure code when something went wrong. required: - conversation_id - status - reply - messages - message_id - cart - carts - placements - catalog - error_code '400': description: Invalid request body. content: application/json: schema: type: object properties: error: type: string hint: type: string '404': description: conversation_id not found for this user and connection. content: application/json: schema: type: object properties: error: type: string '409': description: >- The confirm could not run: the cart changed since that hash was issued (the body carries the fresh carts), nothing has been shown to confirm yet, or the conversation is closed. Never a charge. content: application/json: schema: type: object properties: error: type: string conversation_id: type: string cart: type: - object - 'null' description: >- The most recently shown cart. Null when no cart is on the table. properties: merchant: type: string description: Public merchant id, e.g. retail, doordash, goodeggs. merchant_name: type: string description: >- Display name for the merchant, or the store when one is selected (Amazon, Walmart). items: type: array items: type: object properties: name: type: string qty: type: integer priceCents: type: integer required: - name - qty serviceFeesCents: type: integer description: >- All fees combined, including the Agentcard service fee. tipCents: type: integer totalCents: type: integer description: >- The all-in amount a confirm authorizes: merchandise, fees, and tip. hash: type: string description: >- Identity of exactly this cart. Echo it back as confirm to place the order. required: - merchant - merchant_name - items - serviceFeesCents - tipCents - totalCents - hash carts: type: array items: type: object description: >- The most recently shown cart. Null when no cart is on the table. properties: merchant: type: string description: Public merchant id, e.g. retail, doordash, goodeggs. merchant_name: type: string description: >- Display name for the merchant, or the store when one is selected (Amazon, Walmart). items: type: array items: type: object properties: name: type: string qty: type: integer priceCents: type: integer required: - name - qty serviceFeesCents: type: integer description: >- All fees combined, including the Agentcard service fee. tipCents: type: integer totalCents: type: integer description: >- The all-in amount a confirm authorizes: merchandise, fees, and tip. hash: type: string description: >- Identity of exactly this cart. Echo it back as confirm to place the order. required: - merchant - merchant_name - items - serviceFeesCents - tipCents - totalCents - hash example: error: >- cart changed since that hash was issued — verify the current carts and confirm their hashes conversation_id: cmsq18x2m00a1 cart: merchant: retail merchant_name: Amazon items: - name: Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz qty: 1 priceCents: 2450 serviceFeesCents: 61 tipCents: 0 totalCents: 2511 hash: 31d8a6e0c47b92f5 carts: - merchant: retail merchant_name: Amazon items: - name: Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz qty: 1 priceCents: 2450 serviceFeesCents: 61 tipCents: 0 totalCents: 2511 hash: 31d8a6e0c47b92f5 '502': description: >- The shopping agent could not complete this turn. On a multi-cart confirm the body still carries placements for the orders that already went through. content: application/json: schema: type: object properties: error: type: string conversation_id: type: string placements: type: - array - 'null' items: type: object error_code: type: - string - 'null' security: - userAccessToken: [] components: securitySchemes: platformToken: type: http scheme: bearer description: >- A platform access token. Get one on the **Create an access token** endpoint by exchanging your `client_id` + `client_secret`, then send it as `Authorization: Bearer `. Tokens live one hour. userAccessToken: type: http scheme: bearer description: >- The user's connection access_token (user authentication), or an org-minted buy_token for org-owned accounts. ````