> 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 quickstart

This walks through the whole flow against the **sandbox**
(`https://public-api.demo.alphax.asia`). Set your key and company once:

```bash
export ALPHAX_KEY="<YOUR_API_KEY>"
export BASE="https://public-api.demo.alphax.asia/v1"
```

## 1. Onboard a company

```bash
curl -X POST "$BASE/companies" \
  -H "X-API-Key: $ALPHAX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Ltd",
    "countryCode": "HK",
    "directorName": "Jane Director",
    "directorEmail": "jane@acme.example",
    "directorPhone": "+85251234567",
    "addressLine1": "10 Queens Road",
    "addressLine2": "Central",
    "city": "Hong Kong",
    "state": "Hong Kong",
    "postalCode": "999077",
    "products": ["Card"]
  }'
```

The response returns the company `id` — export it as `CID` and send it as
`X-Company-Id` on the calls below.

```bash
export CID="<company id from the response>"
```

## 2. Submit KYB

`industry` is a **NAICS code**, not free text.

```bash
curl -X POST "$BASE/kyb-profiles" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Ltd",
    "industry": "541511",
    "registrationCountry": "HK",
    "registrationNumber": "12345678",
    "website": "https://acme.example",
    "uboFirstName": "Jane",
    "uboLastName": "Owner",
    "uboGender": "FEMALE",
    "uboCountryCode": "HK",
    "uboIdType": "PASSPORT",
    "uboIdNumber": "P1234567",
    "uboDob": "1990-01-15"
  }'
```

## 3. Create a wallet and open a deposit address

```bash
curl -X POST "$BASE/wallets" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "USDC" }'

# Open an address to deposit into (see the sandbox note below for the chain).
curl -X POST "$BASE/wallets/<WALLET_ID>/addresses" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{ "chain": "ETH" }'
```

**Funding on sandbox uses testnet assets — there is no mock-balance endpoint.**
For USDC, deposits are only enabled on **Ethereum Sepolia** (contract
`0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238`). Open an `ETH` address, get test
USDC from a faucet such as [faucet.circle.com](https://faucet.circle.com), and
send it to that address. We credit the wallet and fire `wallet.deposit_received`.

Confirm the balance landed:

```bash
curl "$BASE/wallets/<WALLET_ID>" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID"
```

## 4. Top up the spending account

```bash
curl -X POST "$BASE/card-spending-account/topups" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{ "walletCurrency": "USDC", "amount": 100 }'
```

Check the spending balance any time:

```bash
curl "$BASE/card-spending-account" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID"
```

## 5. Create a card holder and a card

```bash
curl -X POST "$BASE/card-holders" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John", "lastName": "Holder",
    "email": "john@acme.example", "dateOfBirth": "1992-05-20",
    "phone": "+14155550123",
    "addressLine1": "1 Market St", "addressLine2": "Suite 200",
    "city": "San Francisco", "state": "CA",
    "countryCode": "US", "postalCode": "94105"
  }'

# Pick a BIN the company can issue on.
curl "$BASE/card-bins" -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID"

curl -X POST "$BASE/cards" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{
    "cardHolderId": "<CARD_HOLDER_ID>",
    "name": "Marketing Card",
    "category": "MarketingExpenses",
    "bin": "<BIN>"
  }'
```

## 6. Reveal the card

`POST /v1/cards/{id}/details` returns a short-lived token; render it with the
[card widget](/cards/widget) to show the PAN, expiry, and CVV.

```bash
curl -X POST "$BASE/cards/<CARD_ID>/details" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID"
```