# Agent signup

An AI agent can open a Free Arche account for the person it works for and start calling the API at once. It needs no browser and no card, only its owner’s real email address.

## Open an account

Send the owner’s email and a name for the agent. No credentials are needed.

**Open an account**

```bash
curl -X POST "https://api.arche.fi/v1/agent/signup" \
  -H "Content-Type: application/json" \
  -d '{"email": "owner@yourcompany.com", "agent_name": "research-assistant"}'
```

```python
import requests

response = requests.post(
    "https://api.arche.fi/v1/agent/signup",
    json={"email": "owner@yourcompany.com", "agent_name": "research-assistant"},
    timeout=30,
)
api_key = response.json()["data"]["api_key"]
```

The response returns the key once:

```json
{
  "data": {
    "api_key": "ak_test_…",
    "plan": "free",
    "owner_email": "owner@yourcompany.com",
    "owner_notified": true,
    "expires_at": "2026-10-25T09:30:00Z",
    "claim_url": "https://app.arche.fi/sign-up",
    "checkout_link_endpoint": "/v1/agent/checkout-link"
  }
}
```

Store `api_key` at once: it cannot be retrieved again. Send it in the `X-Api-Key` header, as on any other request. The Free plan is sandbox-only, so this is a sandbox key; it reads the same data as a production key.

If the key is lost before the owner takes over the account, sign up again with the same email. The old key stops working and a new one is returned. The owner is not emailed again.

## The owner takes over

Arche emails the owner an invitation to the account. When the owner signs up at `claim_url` with the same email, the account becomes theirs, the agent’s key keeps working, and from then on keys are managed at [app.arche.fi/keys](https://app.arche.fi/keys).

Until the owner signs up, the key works for 14 days from the first signup and then returns `401 AGENT_ACCOUNT_UNCLAIMED`. Signing up again does not extend it. Tell the owner to check their email, or send them `claim_url`.

## When a call needs a paid plan

An error that a paid plan would lift carries `details.checkout_link_endpoint`. This applies to `FEATURE_NOT_AVAILABLE`, to `COVERAGE_SELECTION_FULL` (the Free plan covers 25 companies you choose) and to `MONTHLY_QUOTA_EXCEEDED`. Request a payment link for the owner:

```bash
curl -X POST "https://api.arche.fi/v1/agent/checkout-link" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": "developer", "interval": "month"}'
```

`plan` is `developer`, `growth` or `scale`, and `interval` is `month` or `year`. Both are optional and default to Developer, billed monthly. The response carries `checkout_url`, with the plan and its price in minor units.

Send `checkout_url` to the owner. The page asks them to sign in, or sign up with the account’s email, before they pay. A paid plan includes production keys, which the owner creates at [app.arche.fi/keys](https://app.arche.fi/keys). An account that already has a subscription gets `409 CHECKOUT_UNAVAILABLE`, and its owner changes plan in the dashboard.

Over MCP, the `account_checkout_link` tool returns the same link, and MCP errors carry the same `details`.

## Limits

- One account per email address, and one invitation per address.
- An email that already has an Arche login is refused. Its owner creates a key in the dashboard instead.
- Five signups per day from one IP address.
- Placeholder addresses such as `example.com` are refused.
- The Free plan’s limits apply: 25 companies you choose, and 2,000 requests a month.

## Errors

| Code                            | HTTP     | Meaning                                                                                         |
| ------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `AGENT_SIGNUP_EMAIL_REGISTERED` | 409      | The email already has an Arche login, or its owner has taken over the agent’s account           |
| `AGENT_SIGNUP_RATE_LIMITED`     | 429      | Too many signups from this address today; `Retry-After` says when to try again                  |
| `AGENT_ACCOUNT_UNCLAIMED`       | 401, 403 | The owner did not sign up within 14 days. A data call gets `401` and a repeat signup gets `403` |
| `CHECKOUT_UNAVAILABLE`          | 409      | The account already has a subscription, or a plan agreed directly                               |
| `VALIDATION_ERROR`              | 422      | The email or agent name cannot be used                                                          |