# StrateFai — Authentication Guide

> How to authenticate with StrateFai APIs, register as an agent, and initiate OAuth flows.

For full product documentation, see: **https://stratefai.gitbook.io/stratefai-docs**

## Overview

StrateFai uses a **wallet-nonce authentication model** as its primary auth mechanism, with optional Twitter (X) and Discord OAuth for quest verification. All authenticated API requests use a **Bearer JWT token**.

API base URL: `https://whitelisting.stratefai.com`

---

## Authentication Flow 1 — Ethereum Wallet (Primary)

This is the main auth flow for API access.

### Step 1 — Request a nonce

```http
GET https://whitelisting.stratefai.com/user/{address}/nonce
```

**Parameters:**
- `address` (path): The user's Ethereum wallet address (hex, checksummed).

**Response:**
```json
{ "nonce": "<one-time challenge string>" }
```

### Step 2 — Sign the nonce

Sign the nonce string with the wallet's private key using EIP-191 personal sign (standard `eth_sign` / `personal_sign`). This happens client-side; the private key never leaves the wallet.

### Step 3 — Validate and receive JWT

```http
POST https://whitelisting.stratefai.com/user/validate/nonce
Content-Type: application/x-www-form-urlencoded

address=<wallet_address>&signature=<signed_nonce>
```

**Response:**
```json
{ "access_token": "<jwt>", "token_type": "Bearer" }
```

### Step 4 — Authenticate requests

```http
Authorization: Bearer <jwt>
```

Include this header on all subsequent authenticated API requests. The token is invalidated on 401 responses — re-run the nonce flow to refresh.

---

## Authentication Flow 2 — Twitter (X) OAuth

Used for identity verification and quest completion. This flow is a popup-based OAuth 2.0 handshake.

### Step 1 — Initiate

```http
POST https://whitelisting.stratefai.com/user/twitter/initiate
Authorization: Bearer <jwt>
```

**Response:**
```json
{ "authUrl": "https://twitter.com/i/oauth2/authorize?..." }
```

### Step 2 — Redirect user

Open the `authUrl` in a popup or redirect. Twitter will present the authorization screen.

### Step 3 — Callback

The external backend handles the OAuth callback and redirects the user back to the StrateFai origin with `?twitter=success|cancelled|failed`.

---

## Authentication Flow 3 — Discord OAuth

Similar popup-based OAuth 2.0 flow for Discord quest verification.

### Step 1 — Initiate

```http
GET https://whitelisting.stratefai.com/user/discord/initiate
Authorization: Bearer <jwt>
```

**Response:**
```json
{ "authUrl": "https://discord.com/api/oauth2/authorize?..." }
```

### Step 2 — Redirect user

Open the `authUrl` in a popup. Discord presents the authorization screen.

### Step 3 — Callback

The external backend handles the Discord callback and redirects back with `?discord=success|cancelled|failed`.

---

## API Endpoints Summary

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET` | `/user/{address}/nonce` | None | Request a sign challenge |
| `POST` | `/user/validate/nonce` | None | Exchange signed nonce for JWT |
| `GET` | `/user/me` | Bearer | Get authenticated user profile |
| `POST` | `/user/twitter/initiate` | Bearer | Start Twitter OAuth flow |
| `GET` | `/user/discord/initiate` | Bearer | Start Discord OAuth flow |
| `POST` | `/quest/verify/follow` | Bearer | Verify Twitter follow quest |
| `POST` | `/quest/verify/discord` | Bearer | Verify Discord join quest |
| `POST` | `/quest/verify/mention` | Bearer | Verify Twitter mention quest |
| `POST` | `/user/email` | Bearer | Register email address |
| `GET` | `/user/change/wallet` | Bearer | Initiate wallet change flow |
| `DELETE` | `/user` | Bearer | Delete account |

---

## Portfolio AI API

Portfolio analysis is a separate service — no authentication required for the free analyser.

Base URL: `https://dev-ai-portfolio.stratefai.com`

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/v1/portfolio/ocr-extract` | Extract holdings from a screenshot (multipart/form-data) |
| `POST` | `/api/v1/portfolio/analyse` | Analyse a portfolio given holdings array |
| `GET` | `/api/v1/coins/search` | Search for supported coins by symbol or name |
| `GET` | `/api/v1/coins/validate` | Validate a list of coin symbols |
| `GET` | `/health` | Health check — returns `{"status":"ok"}` |

Machine-readable API spec: `https://dev-ai-portfolio.stratefai.com/openapi.json` (OpenAPI 3.1)

---

## Contact & Support

- Full documentation: https://stratefai.gitbook.io/stratefai-docs
- Discord: https://discord.gg/wMhGqSQGHF
- Twitter/X: https://x.com/StrateFai
- Website: https://stratefai.com