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

# Cards

> Virtual spending instruments with policy controls

# Cards

A **Card** is a virtual spending instrument issued to an agent. Cards have policy controls that determine how they can be used.

## Card Types

| Usage    | Description                                       |
| -------- | ------------------------------------------------- |
| `single` | One-time use, auto-closes after first transaction |
| `multi`  | Reusable for multiple transactions                |

## Creating a Card

```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_xxx",
    "agentId": "agent_xxx",
    "usage": "multi"
  }'
```

## Card Fields

| Field        | Type   | Description                    |
| ------------ | ------ | ------------------------------ |
| `customerId` | string | Owner of the card              |
| `agentId`    | string | Agent assigned to use the card |
| `usage`      | string | `single` or `multi`            |
| `status`     | string | Card status                    |

## Card Status

| Status   | Description                       |
| -------- | --------------------------------- |
| `active` | Card can be used for transactions |
| `frozen` | Temporarily blocked               |
| `closed` | Permanently deactivated           |

## Policy Controls

Cards can have their own policy overrides:

```json theme={"system"}
{
  "policy": {
    "maxAmount": 10000,
    "allowedMerchants": ["amazon.com"],
    "lockToFirstMerchant": true
  }
}
```

## Accessing Card Details

Card credentials are retrieved via the details endpoint after declaring an intent:

```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/details \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "intentId": "int_xxx",
    "purpose": "Purchase supplies"
  }'
```

Response:

```json theme={"system"}
{
  "pan": "4111111111111111",
  "exp": "12/28",
  "cvv": "123"
}
```

## Card Actions

### Freeze a Card

```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/freeze \
  -H "Authorization: Bearer your_api_key"
```

### Unfreeze a Card

```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/unfreeze \
  -H "Authorization: Bearer your_api_key"
```

### Close a Card

```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/close \
  -H "Authorization: Bearer your_api_key"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Intents" icon="bullseye" href="/concepts/intents">
    Declare purchase intents
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Get real-time notifications
  </Card>
</CardGroup>