# Getting started

Environments, your first API key and your first request.

The WireBloom Banking Platform API connects an ERP, accounting or treasury system to a WireBloom customer account. One versioned API (`/v1`) serves the web app, the mobile app and integrators, so everything the web app shows is available to your system within the scopes of your key.

## Environments

| Environment | Base URL                                       | Keys        | Money                                |
| ----------- | ---------------------------------------------- | ----------- | ------------------------------------ |
| Production  | `https://api.banking.wirebloom.com/v1`         | `wb_live_…` | real (banking partners)              |
| Staging     | `https://api.staging.banking.wirebloom.com/v1` | `wb_test_…` | simulated ([sandbox](/docs/sandbox)) |
| Local       | `http://localhost:3001/v1`                     | `wb_test_…` | simulated                            |

JSON over HTTPS (UTF-8). Money is `{ "amountMinor": "125000", "currency": "EUR" }`: integer minor units as a string, never floats. Timestamps are RFC 3339 UTC (`…Z`). Clients must ignore unknown fields and tolerate new enum values.

## Your first request

1. Ask a customer Owner or Admin to create a `wb_test_` key on the sandbox customer (Settings → API keys, see [Authentication and API keys](/docs/authentication)).
2. Store the key in your secrets manager: it is shown once.
3. List the balances of the customer:

```sh
curl https://api.staging.banking.wirebloom.com/v1/balances \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"
```

`X-Tenant-Id` is the id of the customer the key belongs to ([Tenancy](/docs/tenancy)). The response is a paginated list ([Pagination](/docs/pagination)); the operation is [`listBalances`](/reference/accounts#listBalances).

## Next steps

- Send money with [`createPayment`](/reference/payments#createPayment) and an `Idempotency-Key` ([Idempotency](/docs/idempotency)).
- Receive events instead of polling: [Webhooks](/docs/webhooks).
- Try every asynchronous outcome in the [sandbox](/docs/sandbox) before going live.
- Read the [error catalogue](/errors) and the [rate limits](/docs/rate-limits).

## Sample integration

`platform/examples/integration-client` (TypeScript, Node 22) uses the typed client generated from the contract and includes a webhook receiver that verifies signatures. It lists balances, registers itself as an endpoint, sends a test event, simulates an incoming payment and prints the events it receives, then removes the endpoint.

```sh
pnpm --filter @wirebloom/example-client build
WIREBLOOM_API_URL=http://localhost:3001/v1 WIREBLOOM_API_KEY=wb_test_… \
WIREBLOOM_TENANT_ID=<customer id> pnpm --filter @wirebloom/example-client start
```

## Security checklist

- Keep keys and webhook secrets in a secrets manager; never in code, logs or URLs.
- One key per system, least scopes, IP allow-list and expiry where possible; rotate regularly.
- Verify every webhook signature and timestamp; de-duplicate on the event id.
- Treat webhook payloads as hints: confirm state with the API before acting on money.
- Report suspected key exposure to your WireBloom administrator and revoke the key at once.