> For the complete documentation index, see [llms.txt](https://ocx.gitbook.io/ocx-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ocx.gitbook.io/ocx-doc/ocx/authentication/siwe.md).

# siwe

OCX uses [EIP-4361: Sign-In With Ethereum (SIWE)](https://eips.ethereum.org/EIPS/eip-4361) for wallet-native login. Sign-in is gas-free — you produce a standard off-chain signature that proves you control the wallet.

## The flow

```
1. Client  → POST /auth/nonce  { walletAddress }
2. Server  → { nonce }
3. Client constructs a SIWE message containing the nonce
4. User signs the message in their wallet
5. Client  → POST /auth/siwe   { message, signature }
6. Server verifies signature, mints JWT, sets session cookie
7. Server → { userId, walletAddress }
```

{% stepper %}
{% step %}

### Request a nonce

```http
POST /auth/nonce
Content-Type: application/json

{ "walletAddress": "0xYourAddress" }
```

```json
{ "nonce": "a1b2c3d4..." }
```

A nonce is valid for a short window and single-use. Don't cache it.
{% endstep %}

{% step %}

### Build the SIWE message

The SIWE message is a plain-text block following the EIP-4361 format. Using the official `siwe` npm package:

```ts
import { SiweMessage } from 'siwe';

const message = new SiweMessage({
  domain: 'api.ocx.global',
  address: walletAddress,
  statement: 'Sign in to OCX to continue.',
  uri: 'https://api.ocx.global',
  version: '1',
  chainId: 84532,
  nonce: nonce,
  issuedAt: new Date().toISOString(),
});

const messageText = message.prepareMessage();
```

Or using `viem`:

```ts
import { createSiweMessage } from 'viem/siwe';

const messageText = createSiweMessage({
  domain: 'api.ocx.global',
  address: walletAddress,
  statement: 'Sign in to OCX to continue.',
  uri: 'https://api.ocx.global',
  version: '1',
  chainId: 84532,
  nonce,
});
```

{% endstep %}

{% step %}

### Sign the message

Using the user's wallet, sign the exact message text via `personal_sign` / `eth_sign`. The `viem` and `ethers` libraries abstract this.
{% endstep %}

{% step %}

### Submit the signed message

```http
POST /auth/siwe
Content-Type: application/json

{
  "message": "api.ocx.global wants you to sign in...\n\n0xYourAddress\n\nSign in to OCX to continue.\n\nURI: https://api.ocx.global\nVersion: 1\nChain ID: 84532\nNonce: a1b2c3d4...\nIssued At: 2026-04-24T12:00:00Z",
  "signature": "0x..."
}
```

The server verifies the signature matches the claimed address and that the nonce is the one it issued. On success it mints a JWT, sets it as an httpOnly cookie, and returns:

```json
{ "userId": "01HW...", "walletAddress": "0xYourAddress" }
```

{% endstep %}

{% step %}

### Use the session

Subsequent requests simply include the cookie (handled automatically by browsers) or the JWT as `Authorization: Bearer ...`.

```http
GET /auth/me
```

```json
{ "userId": "01HW...", "walletAddress": "0xYourAddress" }
```

If the cookie is missing or expired, this endpoint returns `null` rather than a 401 to make bootstrapping UIs easier.
{% endstep %}
{% endstepper %}

## Logging out

```http
POST /auth/logout
```

Clears the session cookie and invalidates the JWT.

## Session duration

Sessions last 7 days. Re-sign in by repeating the flow.

## For production integrations

Prefer API keys (see [API Keys](broken://pages/3ef96c2ed737e95650fc76935ee64849bace54f3)) for long-running bots and backends. SIWE is best reserved for interactive logins or for short-lived backends that proxy a specific user.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ocx.gitbook.io/ocx-doc/ocx/authentication/siwe.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.