# Account API

> Manage your Crius account programmatically - email and wallet sign-in, usage and quota, API keys (create, update, rotate, revoke), dashboard sessions and linked wallets.

Source: https://crius.sh/docs/reference/account/

The Account API lives at **`https://account.crius.sh`** (the same paths also work on `api.crius.sh`, which forwards them). Account calls are **free**: they never cost credits and have their own limit of 10 requests per second.

| Access | Endpoints |
|---|---|
| No key | sign-up and sign-in (`/v1/account/signup/*`) |
| Any key of the account | `GET /v1/account/usage` |
| Dashboard session only | everything else: profile, keys, sessions, wallets, billing |

API keys can read usage but can never manage the account. Management needs a **session key** from a dashboard sign-in, which lasts 7 days and can't call data endpoints. This is what [dashboard.crius.sh](https://dashboard.crius.sh) uses; you only need these endpoints to build your own tooling.

## Sign up and sign in

### Email code

```bash
# 1. Ask for a one-time code (the dashboard also sends a Cloudflare Turnstile token).
curl -X POST https://account.crius.sh/v1/account/signup/email \
  -H "content-type: application/json" \
  -d '{"email": "you@example.com", "turnstile_token": "…"}'

# 2. Verify it. "session": true returns a 7-day dashboard session instead of a new API key.
curl -X POST https://account.crius.sh/v1/account/signup/email/verify \
  -H "content-type: application/json" \
  -d '{"email": "you@example.com", "code": "123456", "session": true}'
```

A new email creates an account on the Free plan; a known email signs in. Codes expire after 10 minutes and five wrong attempts void a code. One account per inbox: `+tags`, dots in Gmail addresses and `googlemail.com` are folded together, and disposable inboxes are refused.

### Wallet

A wallet [linked to your account](#wallets) can sign in without email:

1. `GET /v1/account/signup/challenge?address=0x…` returns a message to sign (valid 10 minutes).
2. Sign it with `personal_sign` (EIP-191). Nothing is sent on-chain and it costs nothing.
3. `POST /v1/account/signup/wallet` with `{"address", "signature", "session": true}`.

## Account and usage

| Method | Path | Returns |
|---|---|---|
| GET | `/v1/account` | Account id, email, plan, status, linked wallets, limits |
| GET | `/v1/account/usage` | Month-to-date credits used and remaining, rate limit, current subscription, daily usage for 30 days, top endpoints this month |

```bash
curl https://account.crius.sh/v1/account/usage -H "x-api-key: $CRIUS_API_KEY"
```

Usage is flushed every few seconds, so a request you just made appears almost immediately.

## API keys

| Method | Path | Does |
|---|---|---|
| GET | `/v1/account/keys` | List keys (prefix, name, scopes, restrictions, status, last used) |
| POST | `/v1/account/keys` | Create a key; the response contains the secret, **once** |
| PATCH | `/v1/account/keys/{key_id}` | Change name, scopes, IP allow-list, allowed origins, rate limit or expiry |
| POST | `/v1/account/keys/{key_id}/rotate` | New secret; the old one works for `grace_period_s` (default 3,600, max 7 days) |
| DELETE | `/v1/account/keys/{key_id}` | Revoke immediately |

Body fields for create and update:

```json
{
  "name": "trading-bot",
  "scopes": ["read", "stream"],
  "ip_allowlist": ["203.0.113.7", "10.0.0.0/8"],
  "allowed_origins": [],
  "expires_in_days": 90,
  "limits": { "rps": 5 },
  "env": "live"
}
```

`scopes` accepts `read`, `stream`, `simulate` and `export`. A key with `allowed_origins` is read-only. `limits.rps` can't exceed your plan. An account can have 20 active keys.

## Sessions

| Method | Path | Does |
|---|---|---|
| GET | `/v1/account/sessions` | Dashboard sign-ins that are still valid |
| DELETE | `/v1/account/sessions/{key_id}` | Sign one out |

## Wallets

Linked wallets are a sign-in method and are used to pay and control your [subscription on-chain](https://crius.sh/docs/reference/billing/). A wallet belongs to one account, and an account can link up to 10.

| Method | Path | Does |
|---|---|---|
| GET | `/v1/account/wallets` | List linked wallets |
| POST | `/v1/account/wallets` | Link: `{"address", "signature"}` over a fresh challenge |
| DELETE | `/v1/account/wallets/{address}` | Unlink |

> **Note:**
> We email you when a key is created, rotated or revoked and when a wallet is linked or unlinked, with the IP that did
> it. If you didn't, revoke your keys and sign out every session.