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)
npx agentspend search "<task>"- Confirm cost and constraints with the user (
--max-cost, budget, allowlist) npx agentspend pay <endpoint> --method ... --header ... --body ... --max-cost ...
Setup
npx agentspend configureOpens 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
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 inkey:valueformat (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:
npx agentspend pay <url> \
--method POST \
--header "key:value" \
--body '{"key": "value"}' \
--max-cost 0.05Check
npx agentspend check <url>Discover an endpoint's price without paying.
Important:
checkmust use the same request shape you plan topaywith.- Always pass
--methodfor non-GET endpoints. - If the endpoint needs headers/body, include the same
--headerand--bodyoncheck. - If request shape is wrong, endpoint may return
404/400instead of402, and no price can be extracted.
Example:
npx agentspend check <url> \
--method POST \
--header "content-type:application/json" \
--body '{"key":"value"}'Returns:
- Price in USD
- Description (if available)
Search
npx agentspend search <keywords>Keyword search over service names and descriptions in the catalog. Returns up to 5 matching services.
Example:
npx agentspend search "video generation"Status
npx agentspend statusShow account spending overview.
Returns:
- Weekly budget
- Amount spent this week
- Remaining budget
- Recent charges with amounts, domains, and timestamps
Configure
npx agentspend configureRun 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-costonpayto 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. Runnpx agentspend configureto increase the budget.DOMAIN_NOT_ALLOWLISTED— The target domain is not in the allowlist. Runnpx agentspend configureto update allowed domains.PRICE_EXCEEDS_MAX— Endpoint price is higher than--max-cost. Increase the value or remove the flag.