> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet access and SIWE verification

> Use SIWE for existing-wallet access and API key management, or x402 to create a paid wallet plan before credentials are issued.

Sign in to an existing wallet account and manage its API keys with SIWE, or pay for a new plan from a wallet with x402. Market-data requests still use a dashboard-created API key in `X-API-Key`.

Dashboard-created API keys are the default for servers, scripts, SDKs, CLI, Skill, REST, and WebSocket clients. Hosted MCP uses client-managed OAuth and requires no 0xArchive API key. New free accounts use [standard signup](https://0xarchive.io/signup); a wallet by itself does not create a free account or API key.

0xArchive never requests or stores private keys or seed phrases. It does not hold funds, submit orders, approve transactions, or connect to exchange accounts. Wallet signatures happen outside the API.

## Choose the right path

| Workflow | Path |
| - | - |
| Server REST calls | Create a dashboard key and send `X-API-Key` |
| WebSocket clients | Configure the same API key during connection setup |
| SDK, CLI, and Skill jobs | Use environment variables backed by dashboard-created keys |
| Hosted MCP jobs | Use the client's built-in OAuth flow; no 0xArchive API key |
| Existing wallet sign-in | SIWE challenge plus `/v1/auth/web3/verify` |
| Existing wallet key management | Fresh SIWE challenge plus `/v1/web3/keys` or `/v1/web3/keys/revoke` |
| New free account | Google, GitHub, or email through standard signup |
| New paid wallet plan | x402 through `/v1/web3/subscribe` |

## Existing wallet access

<Steps>
  <Step title="Create a SIWE challenge">
    Call `POST /v1/auth/web3/challenge` with the wallet address.
  </Step>

  <Step title="Sign with the wallet">
    Sign the returned message with `personal_sign` in the wallet environment.
  </Step>

  <Step title="Verify the existing account">
    Send the signed message to `POST /v1/auth/web3/verify`. An existing active wallet account receives its normal session. An unknown wallet receives HTTP 403 with `wallet_account_required`; no account, key, subscription, or credits are created.
  </Step>

  <Step title="Manage existing keys when needed">
    Use a fresh signed challenge with `POST /v1/web3/keys` or `POST /v1/web3/keys/revoke`.
  </Step>
</Steps>

## New wallet-only paid plan

A new wallet can create a paid plan through `POST /v1/web3/subscribe`, using the [x402 facilitator](/facilitator) for the payment protocol. The plan sets capacity and request windows; route availability is the same on every plan and depends on the route, venue family, symbol, and schema.

1. Call the route with `tier` set to `build` or `pro` and no payment header. The server returns HTTP 402 with the x402 payment requirements.
2. Sign the quoted USDC authorization on Base outside the API.
3. Retry with the base64 x402 payload in the `payment-signature` header.
4. After successful verification and settlement, the response contains the paid subscription and API key.

If the wallet belongs to an existing disabled account, the request returns `account_disabled` before settlement. Unknown and active wallets still require full payment verification and settlement before the subscription and API key are issued.

## Retired free wallet signup

`POST /v1/web3/signup` returns HTTP 410 with `wallet_free_signup_retired` and makes no account or key change. Use standard signup for a new free account, SIWE for an existing wallet account, or `/v1/web3/subscribe` for a new paid wallet plan.

## Handle the responses

Keep `request_id` from every failure, and handle `wallet_account_required` and `wallet_free_signup_retired` explicitly. Never send a private key to 0xArchive, check it into an example, or copy it into an agent prompt. Treat every issued API key like any other credential: store it in a secret manager, rotate it when access changes, and keep it out of browser code and prompt transcripts.

## Next step

Open the [Wallet and SIWE endpoint reference](/api-reference/auth-and-keys) for the exact request and response schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.