# Your first API call

This walkthrough uses **Frankfurter Exchange Rates** (`frankfurter`) — a free platform catalog API (`price_cents = 0`). No credit card required.

## 1. Get an API key

**Option A — agent auto-register (0 credits, free APIs only):**

```bash
npx @ozma_app/cli register --json
# save api_key to ~/.ozma/config.json or export OZMA_API_KEY
```

**Option B — human signup ($1 trial after email verify):**

Sign up at [https://ozma.app/signup](https://ozma.app/signup) and copy your key from [Dashboard → Keys](https://ozma.app/dashboard/keys).

```bash
export OZMA_API_KEY=ozma_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

## 2. Inspect the listing

```bash
npx @ozma_app/cli inspect frankfurter --schema --json
```

Note the proxy path: `GET /latest` with query params `from`, `to`.

## 3. Call through the gateway

```bash
curl -s -H "Authorization: Bearer $OZMA_API_KEY" \
  "https://gateway.ozma.app/v1/proxy/frankfurter/latest?from=USD&to=EUR" | jq
```

Or with the CLI:

```bash
npx @ozma_app/cli call frankfurter /latest --query from=USD --query to=EUR --json
```

## 4. Read the envelope

```json
{
  "ok": true,
  "data": {
    "amount": 1.08,
    "base": "USD",
    "date": "2026-07-22",
    "rates": { "EUR": 0.92 }
  },
  "meta": {
    "request_id": "req_01J…",
    "cost_cents": 0,
    "price_cents_effective": 0,
    "credit_applied_cents": 0,
    "billable_cents": 0
  }
}
```

- **`ok`** — success vs failure
- **`data`** — upstream JSON body
- **`meta.request_id`** — support correlation id
- **`meta.cost_cents`** — what this call would cost (0 for free APIs)

## Alternative: httpbin.org

For a request-echo example:

```bash
curl -s -H "Authorization: Bearer $OZMA_API_KEY" \
  "https://gateway.ozma.app/v1/proxy/httpbin-org/get?hello=ozma" | jq '.data'
```

## Free vs paid

| | Free (`price_cents = 0`) | Paid |
|--|--------------------------|------|
| Card required | No | Yes (after credits) |
| Register-only key | Works | Blocked at 402 |
| `meta.billable_cents` | 0 | May be > 0 postpaid |

Some APIs require **provider terms acceptance** before calls succeed (HTTP **428**). Frankfurter and httpbin currently have no required terms.

## Next steps

- [Discover APIs](/docs/guides/discover-apis)
- [Keys & budgets](/docs/guides/keys-and-budgets) — cap agent spend
- [Agent MCP loop](/docs/examples/agent-mcp-loop)