# Quickstart

You need an API key from [console.gmjroaming.com](https://console.gmjroaming.com) and some
account balance.

```bash
export GMJ_KEY="your-api-key"
export GMJ="https://api.gmjroaming.com/api/v1"
```

## 1. Check your account

```bash
curl "$GMJ/user" -H "X-API-KEY: $GMJ_KEY" -H "Accept: application/json"
```

`data.balance` is your balance in USD.

## 2. Find a destination

```bash
curl "$GMJ/list-country?search=japan" -H "X-API-KEY: $GMJ_KEY"
```

```json
{ "status": "success", "code": 200, "data": [
  { "country_name": "Japan", "country_code": "jp", "image": "https://gmjroaming.com/img/country/jp.svg" }
] }
```

Pass `country_code` as `locationCode` in the next step. Regions such as `asia` or `europe`
work too.

## 3. Pick a package

```bash
curl "$GMJ/list-esim?locationCode=jp" -H "X-API-KEY: $GMJ_KEY"
```

Each package has a `packageCode`, a `name`, `priceUsd` (your price) and `volume` (bytes).

## 4. Buy it

The body is an **array**. Generate your own `transaction_id` and store it: it's your reference
for this purchase. The call waits until the eSIM is ready, so allow up to 60 seconds.

```bash
curl -X POST "$GMJ/checkout" -H "X-API-KEY: $GMJ_KEY" -H "Content-Type: application/json" \
  --max-time 60 \
  -d '[{"packageCode":"JC016","count":1,"transaction_id":"order-20261111-0001"}]'
```

```json
{
  "status": "success",
  "code": 200,
  "message": "Checkout successful",
  "currency": "USD",
  "current_balance": "95.80",
  "transaction_id": "order-20261111-0001"
}
```

## 5. Get the eSIM

```bash
curl -X POST "$GMJ/myesim" -H "X-API-KEY: $GMJ_KEY" \
  -H "Content-Type: application/json" -d '{"transaction_id":"order-20261111-0001"}'
```

Send your customer `qrCodeUrl` (a QR to scan) or `publicUrl` (an install page). `ac` is the
activation code for manual entry.

## Next

- Set up [webhooks](/webhooks) to hear when your customer installs the eSIM and uses data.
- Read [Buying eSIMs](/buying-esims) for retries and top-ups.

:::tip
Try read-only endpoints straight from the [API reference](/api/v1): click **Test request** and
paste your key. Endpoints that spend balance have the playground turned off.
:::