# Skill: Make a Paid API Call on APIHub

> Call any API on the marketplace through the proxy. Payment is handled automatically based on your balance.

## Payment priority

For APIHub-native APIs (called through the proxy), payment is resolved in this order:

1. **Free tier** -- some endpoints offer free requests per minute
2. **Prepaid credits** -- debited from your balance, zero gas cost
3. **Per-request x402** -- on-chain USDC payment, requires gas
4. **402 challenge** -- returned if no payment method is available

If you have credits, they are used automatically. No extra headers needed.

**External APIs** (marked "external" in the marketplace) can be called two ways:

1. **Via APIHub** (recommended): `POST https://proxy.apihub.io/external` with `{ url, method, body, headers }`. APIHub pays the provider from the platform wallet and debits your credits for the exact amount. No wallet, no gas. Or use the `apihub_call_external` MCP tool, or `apihub call <url>` from the CLI.
2. **Directly via x402**: call the URL yourself with `@x402/fetch` and your own EVM wallet.

## Prerequisites

- An APIHub API key (see https://apihub.io/skills/register.md)
- Credits or a funded USDC wallet on Base

## Step 1: Find an API

Search for APIs:
```
POST https://api.apihub.io/v1/search
Authorization: Bearer ahk_your_key
Content-Type: application/json

{
  "query": "weather forecast"
}
```

Or browse the marketplace: https://apihub.io/marketplace

## Step 2: Check the endpoint

Get service details:
```
GET https://api.apihub.io/v1/services/weather
```

Response includes endpoints with pricing:
```json
{
  "ok": true,
  "data": {
    "slug": "weather",
    "endpoints": [
      {
        "method": "GET",
        "path": "/current",
        "example_query": "?city=NYC",
        "description": "Get current weather conditions for a city",
        "price_per_request": 1000
      }
    ]
  }
}
```

Prices are in microdollars (1,000 = $0.001).

## Step 3: Call the API through the proxy

The proxy URL pattern is: `https://proxy.apihub.io/{service_slug}/{endpoint_path}`

### With credits (no extra headers needed)

```
GET https://proxy.apihub.io/weather/current?city=NYC
Authorization: Bearer ahk_your_key
```

If you have sufficient credits, the response comes back directly:
```json
{
  "location": { "city": "New York", "country": "United States" },
  "current": { "temperature_c": 18, "conditions": "Partly cloudy" }
}
```

### With x402 (per-request payment)

If you have no credits, the proxy returns a 402 challenge. Use @x402/fetch to handle it automatically:

```typescript
import { wrapFetchWithPayment } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount("0xYOUR_KEY");
const walletClient = createWalletClient({ account, chain: base, transport: http() });
const x402Fetch = wrapFetchWithPayment(walletClient);

const res = await x402Fetch("https://proxy.apihub.io/weather/current?city=NYC", {
  headers: { "Authorization": "Bearer ahk_your_key" },
});
const data = await res.json();
```

## Response headers

Every proxied response includes these headers:

| Header | Description |
|--------|-------------|
| X-APIHub-Payment-Protocol | `credit`, `x402`, or `free` |
| X-APIHub-Price | Cost in microdollars |
| X-APIHub-Credit-Balance-Remaining | Credits left (if paid by credit) |
| X-APIHub-Request-Id | Unique request ID for support |

## POST requests

For POST endpoints, pass the body through:

```
POST https://proxy.apihub.io/ai-inference/generate
Authorization: Bearer ahk_your_key
Content-Type: application/json

{
  "prompt": "Explain quantum computing",
  "max_tokens": 200
}
```

## Content gateway calls

Content services work the same way but use a `fetch` endpoint:

```
GET https://proxy.apihub.io/news-content/fetch?url=https://example.com/article
Authorization: Bearer ahk_your_key
```

Returns structured content (title, text, headings) extracted via headless browser.

## Error handling

| Status | Meaning | Action |
|--------|---------|--------|
| 200 | Success | Parse response body |
| 402 | Payment required | Purchase credits or use x402 (see https://apihub.io/skills/handle-402.md) |
| 401 | Unauthorized | Check your API key |
| 429 | Rate limited | Wait and retry (check Retry-After header) |
| 502 | Upstream error | The provider's API returned an error |

## Related skills

- Handle 402 responses: https://apihub.io/skills/handle-402.md
- Purchase credits: https://apihub.io/skills/purchase-credits.md
- Use MCP instead of REST: https://apihub.io/skills/use-mcp.md