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

# Calling paid APIs

> How to use AgentCash to call premium, paywalled endpoints.

The primary use case for AgentCash is calling APIs that require payment. Endpoints may charge via x402 (on-chain USDC transfer) or MPP (signed off-chain payment intent); AgentCash handles both transparently. This guide covers the flow from your agent's perspective.

## Basic usage

Ask your agent to fetch data from a premium endpoint:

> Use AgentCash to fetch [https://stableenrich.dev/api/company/lookup](https://stableenrich.dev/api/company/lookup) with body `{"domain": "anthropic.com"}`.

The agent calls the `fetch` tool (in MCP mode) or uses the CLI, which:

1. Sends the request to the endpoint
2. Receives a `402 Payment Required` response listing accepted protocols (`x402`, `mpp`) and networks
3. Picks a protocol your wallet supports and signs the payment proof
4. Retries the request with the proof attached
5. Returns the response data and payment info

## Checking the price first

If you want to know the cost before paying, ask your agent to check the endpoint:

> Check the pricing for [https://stableenrich.dev/api/company/lookup](https://stableenrich.dev/api/company/lookup) using AgentCash.

This probes the endpoint without making a payment. It returns the price, accepted methods, and input/output schema.

## Request options

The `fetch` command accepts standard HTTP options:

```
URL:     https://example.com/api/endpoint
Method:  POST (default: GET)
Headers: {"Content-Type": "application/json"}
Body:    {"key": "value"}
Timeout: 30000 (milliseconds)
```

<Note>
  AgentCash sets `Content-Type: application/json` by default for requests with a body.
</Note>

## Payment info in responses

Every paid request returns payment metadata alongside the response data:

* **amount**: USDC paid
* **transaction**: on-chain transaction hash
* **network**: which chain the payment was made on

## Error handling

If a payment fails, AgentCash returns a clear error. Common issues:

| Error                       | Cause                                 | Fix                                 |
| --------------------------- | ------------------------------------- | ----------------------------------- |
| Insufficient balance        | Not enough USDC for the request price | [Fund your wallet](/wallet/funding) |
| Payment verification failed | On-chain verification issue           | Retry the request                   |
| Timeout                     | Endpoint took too long to respond     | Increase timeout or try again       |