# Quickstart

Ingram Domains is a registrar with an API-first contract: everything the
dashboard does, an agent or script can do over REST at
`https://domains.ingram.tech/api/v1`. This page goes from zero to a
registered domain.

## 1. Create an account

One call creates a user, a workspace, and an API token — no email
confirmation, no browser:

```bash
curl -s https://domains.ingram.tech/api/v1/accounts \
  -H 'content-type: application/json' \
  -d '{"email": "agent@example.com", "password": "a-strong-password"}'
```

```json
{
  "user_id": "usr_…",
  "organization_id": "org_…",
  "email": "agent@example.com",
  "api_token": "ingram_live_…",
  "api_token_prefix": "ingram_live_3fk",
  "balance": { "amount": 0, "currency": "eur" }
}
```

The `api_token` is shown exactly once — store it. Every authenticated call
sends it as a bearer:

```bash
export INGRAM_TOKEN="ingram_live_…"
```

Already signed up in the dashboard? Mint a token under **Settings → API
tokens** instead.

## 2. Check availability

Public — no token needed:

```bash
curl -s 'https://domains.ingram.tech/api/v1/check?q=my-great-idea.com'
```

```json
{ "query": "my-great-idea.com", "results": [
  { "domain": "my-great-idea.com", "result": "AVAILABLE", "price": 18, "currency": "EUR" }
] }
```

The `price` is the registration price in EUR per year — the exact number the
next step must confirm.

## 3. Fund the wallet

Purchases debit your workspace wallet. Two ways to fund it:

- **Top up** in the dashboard (**Billing → Top up**, card via Stripe
  Checkout), or
- **Pay as you go**: pass a `payment_method` (a Stripe PaymentMethod id) or a
  `shared_payment_token` directly on the registration call — the exact price
  is charged, credited, and immediately debited, so no standing balance is
  needed.

See [Payments & the wallet](/docs/payments) for the full model.

## 4. Register — with `confirm_price`

Spending is never implicit. You must echo the price you saw; if the live
price differs, the call fails instead of charging you:

```bash
curl -s https://domains.ingram.tech/api/v1/domains \
  -H "authorization: Bearer $INGRAM_TOKEN" \
  -H 'content-type: application/json' \
  -H 'idempotency-key: 5f0c3a1e-registration-1' \
  -d '{"domain": "my-great-idea.com", "duration": 1, "confirm_price": 18}'
```

On success you get the domain and the registry status (`Pending` means the
registry accepted and is processing — normal). On a price change you get a
`409 price_changed` with the current price to re-confirm; on an empty wallet
a `402 insufficient_balance`. Both are structured for programmatic recovery —
see [Errors](/docs/errors).

## Where next

- [Concepts](/docs/concepts) — workspaces, wallet, tokens, and the four
  product surfaces.
- [Agents](/docs/agents) — the MCP server, and why the API is shaped the way
  it is.
- The full REST reference is the live [Swagger UI](https://domains.ingram.tech/api/v1/docs)
  and [OpenAPI spec](https://domains.ingram.tech/api/v1/openapi.json).