> For the complete documentation index, see [llms.txt](https://wiki.gen6.life/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.gen6.life/technology-core/developer-resources/sdk-and-tooling/gen6-mw-and-chain-api-guide.md).

# Gen6 MW & Chain API Guide

Comprehensive documentation for Gen6 dApps APIs and blockchain integrations.

### Overview

Gen6 dApps uses three main communication layers:

1. **HTTP APIs** - RESTful endpoints via middleware (`mw_url`)
2. **Blockchain Extrinsics** - On-chain transactions via Polkadot/Substrate API
3. **RPC Endpoints** - JSON-RPC 2.0 for parking pallet queries

### Architecture

**Feature-first structure:**

```
src/packages/<feature>/
├── api/
│   ├── axiosInstance.ts    # HTTP client config
│   ├── queries.ts          # GET requests
│   └── mutations.ts        # POST/PUT/DELETE requests
├── hooks/                  # React hooks for API & blockchain
└── types.ts               # TypeScript type definitions
```

### Base URLs

**Production:**

* Middleware API: `https://gen6.app/api`
* Validators API: `https://shepherd.gen6.app/api/v1`
* Blockchain RPC: WebSocket from nodes config

**Development:**

* Middleware: Auto-detected or `http://localhost:5000/api`
* Configuration: `src/data/nodes.ts`

### Authentication

**Two-tier system:**

1. **Wallet Connection** - Polkadot wallet required
2. **JWT Authentication** - Signed challenge for API access

**JWT Verification:** `GET /auth/jwt_ping` → `{ authenticated: boolean }`

### Features

#### Core APIs

* **Authentication** - JWT auth with wallet/Google OAuth signing
* **Identity** - User profiles with merkle tree verification
* **Real-Seal** - Document/text signing with blockchain anchoring
* **Ncrypt** - End-to-end encrypted messaging
* **Parking** - GSX token staking (JSON-RPC + extrinsics)
* **Finance** - Token transfers (extrinsics only)
* **Validator Dashboard** - Validator monitoring & stats

### Quick Start

#### HTTP API Request

```typescript
import { axiosInstance } from '@/packages/<feature>/api/axiosInstance'

const response = await axiosInstance.get<ResponseType>('/endpoint')
const data = response.data
```

#### Blockchain Transaction

```typescript
import { useGen6 } from '@/contexts/gen6-context'
import { useSigner } from '@/hooks/useSigner'

const { api, currentAccount } = useGen6()
const { getSigner } = useSigner()

const signerResult = await getSigner() // Works for wallet + Google auth
const extrinsic = api.tx.pallet.method(params)

await extrinsic.signAndSend(
  currentAccount.address,
  { signer: signerResult.signer },
  ({ status }) => {
    if (status.isFinalized) console.log('Done')
  }
)
```

### Technology Stack

* **Frontend**: React 19, TypeScript, Vite
* **Routing**: TanStack Router (file-based)
* **State**: TanStack Query (server) + Zustand (client)
* **HTTP**: Axios with interceptors
* **Blockchain**: Polkadot.js API
* **Auth**: JWT (HttpOnly cookies) + Polkadot/Google signing

### Environment Variables

```bash
# Required (Those ones are set by default in data/nodes but in case you want to overwrite them, you will need to set these variables in you .env file)
VITE_API_URL            # Backend API base URL (middleware)
VITE_NODE_URL           # Blockchain WebSocket URL (wss://...)
VITE_RPC_URL            # Blockchain HTTP RPC URL (https://...)
VITE_BLOCK_EXPLORER_URL # Block explorer URL
VITE_VALIDATORS_API_URL # Validators monitoring API URL

# Optional
VITE_IS_DEV             # Development mode flag ('true'/'false')
VITE_ADD_LOCAL_NODE     # Add local dev node to node selector
VITE_GOOGLE_CLIENT_ID   # Google OAuth client ID for auth
```

**Default Values**: If not set, defaults are loaded from src/data/nodes.ts based on environment.

**Development Setup**:

```bash
# .env.local
VITE_API_URL=http://localhost:5000/api
VITE_NODE_URL=ws://localhost:9944
VITE_RPC_URL=http://localhost:9944
VITE_BLOCK_EXPLORER_URL=https://explorer.gen6.dev
VITE_IS_DEV=true
VITE_ADD_LOCAL_NODE=true
VITE_GOOGLE_CLIENT_ID=your_google_client_id
```

### Important Notes

* All middleware endpoints use `withCredentials: true` for JWT cookies
* Parking uses separate JSON-RPC endpoint (no credentials)
* Blockchain decimals: 18 (use `api.registry.chainDecimals[0]`)
* Address format: SS58-355 (Gen6 addresses start with `g6x`)
* Signing: Unified via `useSigner()` - supports both wallet extension and Google OAuth