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

# Log Transaction

> Manually log a transaction against a card

Logs a transaction against a card. Useful for tracking spend that occurs outside of automatic payment webhook processing.

### Request Body

| Parameter       | Type   | Required | Description                               |
| --------------- | ------ | -------- | ----------------------------------------- |
| `amount_cents`  | number | Yes      | Transaction amount in cents               |
| `merchant_name` | string | No       | Name of the merchant                      |
| `description`   | string | No       | Description of the transaction            |
| `agent_id`      | string | No       | Agent UUID that initiated the transaction |
| `metadata`      | object | No       | Arbitrary key-value metadata              |

<RequestExample>
  ```bash theme={"theme":"css-variables"}
  curl -X POST https://api.usenaive.ai/v1/cards/card-uuid-1/log-transaction \
    -H "Authorization: Bearer nv_sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "amount_cents": 1500,
      "merchant_name": "OpenAI",
      "description": "GPT-4 API usage",
      "agent_id": "agent-uuid-1",
      "metadata": {
        "invoice_id": "inv_123"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  {
    "transaction": {
      "id": "txn-uuid-1",
      "card_id": "card-uuid-1",
      "amount_cents": 1500,
      "merchant_name": "OpenAI",
      "description": "GPT-4 API usage",
      "agent_id": "agent-uuid-1",
      "metadata": {
        "invoice_id": "inv_123"
      },
      "created_at": "2026-03-15T14:30:00Z"
    }
  }
  ```
</ResponseExample>

## CLI

```bash theme={"theme":"css-variables"}
naive cards log-transaction <id> --amount 1500
```

With optional fields:

```bash theme={"theme":"css-variables"}
naive cards log-transaction <id> --amount 1500 --merchant "OpenAI" --description "GPT-4 API usage"
```

## MCP

Tool: `naive_cards_log_transaction`

```json theme={"theme":"css-variables"}
{
  "card_id": "card-uuid-1",
  "amount_cents": 1500,
  "merchant_name": "OpenAI",
  "description": "GPT-4 API usage",
  "agent_id": "agent-uuid-1"
}
```