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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Create a card

> Issue a virtual card to a connected user from your server.

Issues a card to a connected user. Send an `Idempotency-Key`, and on a `202`
or a timeout retry with the same key. See
[Retry safely](https://docs.agentcard.com/api-reference/cards/overview.md#retry-safely).

To cap a multi-use card per charge and per day, week, month or year, or to choose the merchant categories it can be charged at, send `spending_controls`. A single-use card takes `allowed_mccs` alone, and the card network declines a charge at any other merchant. See [Set spending controls](https://docs.agentcard.com/api-reference/cards/overview.md#set-spending-controls).


## OpenAPI

````yaml openapi.json POST /api/v2/cards
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.
paths:
  /api/v2/cards:
    post:
      tags:
        - Cards
      summary: Create a card
      description: >-
        Issues a virtual card to a connected user, with your company credential.
        Send an `Idempotency-Key`: a retry with the same key collects the same
        card and spends once.
      operationId: cardCreate
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Your key for this card. Retry with the same one after a timeout or a
            `202`.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - amount_cents
              properties:
                user_id:
                  type: string
                  description: The connected user the card is for.
                amount_cents:
                  type: integer
                  minimum: 100
                  description: What the card can spend, in cents. At least 100.
                type:
                  type: string
                  enum:
                    - single_use
                    - multi_use
                  default: single_use
                  description: '`single_use` closes after its first approved charge.'
                expires_at:
                  type: string
                  format: date-time
                  description: >-
                    Closes a `multi_use` card at this time, at most 365 days
                    out.
                scope_preset:
                  type: string
                  enum:
                    - ai_labs
                  description: Locks a `multi_use` card to AI-lab merchants.
                spending_controls:
                  $ref: '#/components/schemas/SpendingControlsInput'
                  description: >-
                    Caps and merchant categories. A `multi_use` card takes all
                    of them; a `single_use` card takes `allowed_mccs` alone,
                    which the card network declines against. Not with
                    `scope_preset`.
      responses:
        '201':
          description: The card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '202':
          description: >-
            Funding is in progress. Retry with the same `Idempotency-Key` after
            `retry_after_seconds` to collect the card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardFunding'
        '400':
          description: >-
            `invalid_request`: a field isn't one this endpoint accepts.
            `spending_controls_unsupported`: controls were sent without `type:
            multi_use`, or with `scope_preset`. `spending_controls_conflict`:
            both `allowed_mccs` and `blocked_mccs`. `spending_controls_invalid`:
            one interval named twice in `limits`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: >-
            `connection_not_found`: no connection for that user in this
            credential's mode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `idempotency_key_reuse`: that key was used for a different amount or
            user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            The card can't be issued yet: `kyc_required`,
            `org_wallet_funding_required`, `wallet_funding_required`,
            `sandbox_funding_required`, `deposit_confirming`,
            `card_limit_reached`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - platformToken: []
components:
  schemas:
    SpendingControlsInput:
      type: object
      additionalProperties: false
      properties:
        per_authorization_cents:
          type:
            - integer
            - 'null'
          minimum: 100
          description: >-
            The most one charge may be, in cents. At least 100. A `multi_use`
            card only.
        limits:
          type:
            - array
            - 'null'
          maxItems: 4
          description: At most one cap per interval. A `multi_use` card only.
          items:
            $ref: '#/components/schemas/SpendingLimit'
        allowed_mccs:
          type:
            - array
            - 'null'
          minItems: 1
          maxItems: 200
          items:
            type: string
            pattern: ^[0-9]{4}$
          description: >-
            Four-digit merchant category codes. Not with `blocked_mccs`. The one
            control a `single_use` card takes, fixed when that card is created.
        blocked_mccs:
          type:
            - array
            - 'null'
          minItems: 1
          maxItems: 200
          items:
            type: string
            pattern: ^[0-9]{4}$
          description: >-
            Four-digit merchant category codes. Not with `allowed_mccs`. A
            `multi_use` card only.
    Card:
      type: object
      required:
        - object
        - id
        - status
        - spend_limit_cents
        - balance_cents
        - last4
        - expiry
        - type
        - created_at
      properties:
        object:
          type: string
          description: Always `card`.
          enum:
            - card
        id:
          type: string
          description: The card's id.
        status:
          type: string
          description: >-
            `creating`, `open`, `in_use`, `paused`, `pausing`, `closing`, or
            `closed`.
        type:
          type: string
          description: '`single_use` or `multi_use`.'
        spend_limit_cents:
          type: integer
          description: What the card can spend in all.
        balance_cents:
          type: integer
          description: What's left to spend.
        spending_controls:
          $ref: '#/components/schemas/SpendingControls'
        last4:
          type: string
          description: The last four digits.
        expiry:
          type: string
          description: '`MM/YY`.'
        user_id:
          type:
            - string
            - 'null'
          description: The user the card is for.
        cardholder_name:
          type: string
          description: The name the card was issued in, for the payment form.
        billing_address:
          type: string
          description: The billing address, for the payment form.
        funds_source:
          type: string
          description: 'On a new card: what funded it.'
        transfer_id:
          type: string
          description: 'On a company-funded new card: the transfer that funded it.'
        closed_reason:
          type: string
          description: 'Only when `closed`: `used`, `canceled`, `expired`, `declined`.'
        card_expires_at:
          type: string
          description: When a `multi_use` card closes itself.
          format: date-time
        created_at:
          type: string
          description: When it was issued.
          format: date-time
    CardFunding:
      type: object
      required:
        - object
        - status
        - retry_after_seconds
      properties:
        object:
          type: string
          description: Always `card_funding`.
          enum:
            - card_funding
        status:
          type: string
          description: Always `funding_in_progress`.
          enum:
            - funding_in_progress
        transfer_id:
          type: string
          description: The transfer funding the card.
        retry_after_seconds:
          type: integer
          description: When to retry with the same `Idempotency-Key`.
        message:
          type: string
          description: What to do next.
    Error:
      type: object
      description: Every v2 error uses the same envelope.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable string (snake_case). Branch on this.
            message:
              type: string
              description: A human-readable explanation, safe to log.
            docs:
              type: string
              description: A link back to the reference.
            field_errors:
              type: object
              additionalProperties:
                type: string
              description: Only on `invalid_fields` — names each field to fix.
            warnings:
              type: array
              items:
                type: string
              description: >-
                Only on document upload errors — actionable feedback safe to
                show the user.
            status:
              type: string
              description: >-
                Only on `verification_terminally_rejected` — the user's current
                verification status, which this call did not change.
            reason:
              type: string
              description: >-
                The detail behind the failure, on the errors that carry one: on
                `verification_terminally_rejected` an end-user-safe explanation
                of the rejection, when the review left one; on `invalid_code`
                and `invalid_return_url` which part of the input was refused.
            reason_code:
              type: string
              description: >-
                Only on `verification_terminally_rejected`, and only when the
                rejection maps to a known class — most final rejections carry no
                code.
    SpendingLimit:
      type: object
      required:
        - interval
        - amount_cents
      properties:
        interval:
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - yearly
          description: 'The rolling window: 24 hours, 7 days, 30 days or 365 days.'
        amount_cents:
          type: integer
          minimum: 100
          description: The most the card spends in the window, in cents.
    SpendingControls:
      type: object
      description: >-
        The card's caps and merchant categories. On a `multi_use` card Agentcard
        checks each charge against them once the card network has approved it,
        and pauses the card on a charge that breaks one; the card network
        declines only charges past `spend_limit_cents`. A `single_use` card
        carries `allowed_mccs` alone, and the card network declines a charge at
        any other merchant as it is authorized.
      required:
        - per_authorization_cents
        - limits
        - allowed_mccs
        - blocked_mccs
      properties:
        per_authorization_cents:
          type:
            - integer
            - 'null'
          description: The most one charge may be, in cents. A charge at the cap passes.
        limits:
          type: array
          description: Caps on what the card spends in a rolling window.
          items:
            $ref: '#/components/schemas/SpendingLimit'
        allowed_mccs:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >-
            The only merchant category codes the card may be charged at. On a
            `single_use` card the card network holds this list itself and
            declines a charge anywhere else.
        blocked_mccs:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Merchant category codes the card may not be charged at.
  responses:
    Unauthorized:
      description: >-
        `unauthorized` — the platform access token is missing or expired.
        Exchange your client credentials for a fresh one.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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 <token>`. Tokens live one hour.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.