G6 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

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

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

Blockchain Transaction

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

# 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:

# .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