> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alphax.asia/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alphax.asia/_mcp/server.

# Card API overview

The AlphaX Card API lets you — a **partner** — onboard companies and issue and
manage virtual cards for them, entirely through our API.

The model follows the same pattern you may know from other platform APIs: you
authenticate once with your **partner API key**, and name the **company** you
are acting for on each request.

## Authentication & acting for a company

Every request is authenticated with your partner API key in the `X-API-Key`
header. Endpoints that act on a specific company also take an `X-Company-Id`
header — the ULID of the company you are acting for (from `GET /v1/companies`).

```bash
curl https://public-api.alphax.com/v1/cards \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "X-Company-Id: 01KZ2WJKWVFPCVAB6MY106QRZV"
```

The company-level endpoints (`/v1/companies`) do **not** require `X-Company-Id`.
Everything scoped to a single company (wallets, card holders, cards, …) does.

## The end-to-end flow

#### Onboard a company

`POST /v1/companies` creates a company and links it to you. Provisioning
continues asynchronously — watch the `company.onboarding_status_changed`
webhook.

#### Submit KYB

`POST /v1/kyb-profiles` submits the company's verification details. The
result arrives via the `company.kyb_status_changed` webhook.

#### Create a wallet & fund it

`POST /v1/wallets` creates a crypto wallet and `POST /v1/wallets/{id}/addresses`
opens a deposit address. Funds are deposited on-chain to that address; we
notify you with `wallet.deposit_received`.

#### Top up the spending account

`POST /v1/card-spending-account/topups` moves wallet funds into the card
spending account — the balance cards draw down.

#### Create a card holder & a card

`POST /v1/card-holders` creates the person, then `POST /v1/cards` issues a
card (pick a `bin` from `GET /v1/card-bins`).

#### Reveal card details

`POST /v1/cards/{id}/details` returns a short-lived token your front-end
renders with the **card widget** to show the PAN, expiry, and CVV.

## Asynchronous by design

Many operations (onboarding, KYB, card issuing, deposits, transactions) complete
asynchronously. Rather than polling, subscribe to **webhooks** — we notify your
endpoint the moment state changes. See the [Webhooks](/cards/webhooks) guide.

## Environments

| Environment | Base URL                              |
| ----------- | ------------------------------------- |
| Production  | `https://public-api.alphax.com`       |
| Sandbox     | `https://public-api.demo.alphax.asia` |

Use the sandbox with testnet assets while you build. See the
[Quickstart](/cards/quickstart) to run the full flow end to end.