# Agent sign-in

Authenticate an automated agent with an EVM wallet, without a browser.

Source: https://docs.invoise.me/agents/sign-in/

Already have a shop API key? Skip sign-in and use the [payment API](https://docs.invoise.me/api-reference/). An agent only needs wallet sign-in when it must set up or administer an account.

Wallet sign-in is for agents only. Send these requests from a server or script: a request with an `Origin` header, which every browser adds, is refused with `403 wallet_sign_in_agents_only`. The dashboard does not offer wallet sign-in or wallet linking.

## 1. Request a message

Use an EVM wallet you control. Its private key stays with your signing tool and is never sent to Invoise.

```bash
curl -X POST 'https://platform.invoise.me/api/v1/auth/wallet/challenge' \
  -H 'Content-Type: application/json' \
  -d "{\"address\":\"${WALLET_ADDRESS:?}\",\"chain_id\":${CHAIN_ID:?}}"
```

Set `WALLET_ADDRESS` to your EVM address and `CHAIN_ID` to an available EVM network ID from the [API](https://docs.invoise.me/payments/networks/). The response contains `challenge_id` and `message`.

## 2. Sign the returned message

Use your wallet's EIP-191 personal-message signing method. Sign `message` exactly as received, including whitespace. This is a message signature, not a transaction.

The challenge is short-lived and single-use. If it expires or is consumed, request a new one.

## 3. Exchange the signature for a session

```bash
curl -X POST 'https://platform.invoise.me/api/v1/auth/wallet/verify' \
  -H 'Content-Type: application/json' \
  -d '{"challenge_id":"<challenge-id>","signature":"<0x-signature>"}'
```

Save `token` securely and check `expires_at`, `user.mfa_required` and `user.onboarding_required` in the response.

Invoise sets no cookie. Send the session in `Authorization: Bearer <token>`; it needs no CSRF header.

## 4. Complete setup

| Condition | Next step |
| --- | --- |
| `user.mfa_required: true` | Complete the configured second factor before business requests. Wallet sign-in does not bypass MFA. |
| `user.onboarding_required: true` | Ask your human for their email, then create the first merchant through `/onboarding` with `name` and `email`. Without the email the answer is `400 email_required`; a disposable address returns `400 disposable_email`. |
| Sign-in complete | Continue with [Agent workflow](https://docs.invoise.me/agents/integration/) to choose a merchant, create a shop and issue a shop API key. |

Use the session for setup and the scoped API key for payment work. If a session expires, authenticate again. See [Auth reference](https://docs.invoise.me/agents/auth-reference/) for request and response fields.