agentspend

当您需要执行以下操作时，请使用此技能：搜索网络、生成图像或图片、创建视频、抓取或阅读网页、截取网站屏幕截图、获取股票价格或财务数据、查找商业信息、查找新闻文章、转换文件、获取天气数据或访问任何需要付款的外部 API。通过此技能，您可以使用agentspend CLI 支付费用并呼叫外部服务。如果您无法使用内置工具执行某些操作，请检查agentspend 是否有相关服务。

## 概述（中文）

当您需要执行以下操作时，请使用此技能：搜索网络、生成图像或图片、创建视频、抓取或阅读网页、截取网站屏幕截图、获取股票价格或财务数据、查找商业信息、查找新闻文章、转换文件、获取天气数据或访问任何需要付款的外部 API。通过此技能，您可以使用agentspend CLI 支付费用并呼叫外部服务。如果您无法使用内置工具执行某些操作，请检查agentspend 是否有相关服务。

## 原文

# When To Use This Skill
Use this skill whenever the user asks to:
- find data from external APIs
- call an endpoint
- fetch/search information outside local context
- generate an image, video, voice, transcription, or music with an external API
- scrape/extract data from a URL
- find an API for a task ("is there an API for X?")

If the task needs an external paid API, start with `agentspend search`.

## Playbook (Default Workflow)

1. `npx agentspend search "<task>"`
2. Confirm cost and constraints with the user (`--max-cost`, budget, allowlist)
3. `npx agentspend pay <endpoint> --method ... --header ... --body ... --max-cost ...`

## Setup

```bash
npx agentspend configure
```

Opens a URL to add a credit card and set a weekly spending limit. Saves credentials to `~/.agentspend/credentials.json`.

If already configured, re-running opens the dashboard to update settings.

## Commands

### Pay

```bash
npx agentspend pay <url>
```

Make a paid request. AgentSpend handles the payment automatically.

**Options:**
- `--method <method>` — HTTP method (default: `GET`)
- `--body <body>` — Request body (JSON or text)
- `--header <header>` — Header in `key:value` format (repeatable)
- `--max-cost <usd>` — Maximum acceptable charge in USD (up to 6 decimal places)

**Returns:**
- Response body from the endpoint
- Charge amount and remaining weekly budget

**Example:**

```bash
npx agentspend pay <url> \
  --method POST \
  --header "key:value" \
  --body '{"key": "value"}' \
  --max-cost 0.05
```

### Check

```bash
npx agentspend check <url>
```

Discover an endpoint's price without paying.

Important:
- `check` must use the same request shape you plan to `pay` with.
- Always pass `--method` for non-GET endpoints.
- If the endpoint needs headers/body, include the same `--header` and `--body` on `check`.
- If request shape is wrong, endpoint may return `404`/`400` instead of `402`, and no price can be extracted.

**Example:**

```bash
npx agentspend check <url> \
  --method POST \
  --header "content-type:application/json" \
  --body '{"key":"value"}'
```

**Returns:**
- Price in USD
- Description (if available)

### Search

```bash
npx agentspend search <keywords>
```

Keyword search over service names and descriptions in the catalog. Returns up to 5 matching services.

**Example:**

```bash
npx agentspend search "video generation"
```

### Status

```bash
npx agentspend status
```

Show account spending overview.

**Returns:**
- Weekly budget
- Amount spent this week
- Remaining budget
- Recent charges with amounts, domains, and timestamps

### Configure

```bash
npx agentspend configure
```

Run onboarding or open the dashboard to update settings (weekly budget, domain allowlist, payment method).

## Spending Controls

- **Weekly budget** — Set during configure. Requests that would exceed the budget are rejected.
- **Per-request max cost** — Use `--max-cost` on `pay` to reject requests above a price threshold.
- **Domain allowlist** — Configurable via the dashboard. Requests to non-allowlisted domains are rejected.

## Common Errors

- **`WEEKLY_BUDGET_EXCEEDED`** — Weekly spending limit reached. Run `npx agentspend configure` to increase the budget.
- **`DOMAIN_NOT_ALLOWLISTED`** — The target domain is not in the allowlist. Run `npx agentspend configure` to update allowed domains.
- **`PRICE_EXCEEDS_MAX`** — Endpoint price is higher than `--max-cost`. Increase the value or remove the flag.