Pentagon Identity API

🚀 Getting Started

Before you can use the Pentagon Identity API, you must have an App Key. Requests without a valid key will be rejected starting May 28, 2026.

X-PG-App-Key: pk_live_your_key

Overview

The Pentagon Identity API provides unified authentication and user management for all Pentagon Games products. One account works across pentagon.games, Gunnies, EtherFantasy, PentaSwap, and all partner apps.

Base URL

https://api.account.pentagon.games

All endpoints are prefixed with /user/ unless otherwise noted.

Authentication Pattern

Most endpoints require a JWT Bearer token obtained from login:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Authentication

Frontend Routes

Login Methods

Email/Password Login

POST /user/login
Content-Type: application/json
X-PG-App-Key: pk_live_your_key

{
  "type": "email",
  "username": "player@example.com",
  "password": "securepassword",
  "login_from": "your_app_name"
}

Wallet Signature Login

For web3 wallet login, the client signs a message and the backend verifies the signature matches the wallet address.

POST /user/login
Content-Type: application/json
X-PG-App-Key: pk_live_your_key

{
  "type": "wallet",
  "address": "0x1234...abcd",
  "signature": "0xsigned...",
  "message": "Logging into Pentagon Games,1745812345",
  "login_from": "your_app_name"
}

Message format: Logging into Pentagon Games,{unix_timestamp_seconds}

Timestamp window: Must be within 5 minutes of server time. The backend does not require a particular message prefix — it requires that the signature recovers to address and that the timestamp after the last comma is under 5 minutes old.

Prerequisite: The address must already be registered on an account — either as mm_address (via /user/bind_metamask) or as penai_address (via /user/penai/bind).

Successful Login Response

{
  "status": true,
  "result": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

PNS (Pentagon Name Service) Login

Users with a PNS username NFT can log in using their on-chain name instead of their email or PG username. The backend resolves the PNS name to a wallet address via the on-chain contract, then matches it to the PG account with that wallet bound.

POST /user/login
Content-Type: application/json
X-PG-App-Key: pk_live_your_key

{
  "type": "email",
  "username": "king",
  "password": "userpassword",
  "login_from": "your_app_name"
}

Resolution flow: PNS name → on-chain contract → wallet address → PG account lookup → password verification → JWT token

Contract: 0xf97EB9f8293D1FD5587a809Eb74518c300738d07 on Pentagon Chain (3344)

Requirements: The PNS name must be minted AND spatially bound to a wallet that is connected to a PG account.

Login Methods Summary

Error Responses

🧭 Resolving Users (Handle → Account)

"Resolution" means turning a handle a user typed (or that another service passes in) into a concrete account. The identity backend supports several handle types, and they must always be tried in the same canonical order. Getting this wrong is the single most common identity bug: a partial resolver matches current username but misses PNS or legacy, and silently fails to find a real user.

Why the order matters: the same string can be valid at multiple layers (e.g. nftprof is a PNS name AND a legacy username of nftprof1). PNS is the primary identity system, so it must win before legacy. Email is checked first because it is unambiguous and cheapest.

Internal (in-process) vs. Login resolution

There are two contexts where resolution happens, and they share the same order but differ in scope:

One canonical resolver

All paths — login, the card-spend handler, and any public lookup endpoint — must call a single shared resolve_account(handle) function. Three separate copies of "resolve a handle" previously existed and drifted apart (login did the full chain; info_by_username/public did username + legacy only, missing PNS; a third was added ad hoc). Duplicated resolvers will diverge. Centralize one, reuse it everywhere.

# Canonical internal resolver (user/pns.py) — call this, do not reimplement
account = resolve_account(handle)   # tries email → PNS → username → legacy
if account is None:
    # handle did not resolve at ANY layer — fail loudly, do not assume username-only
    ...

Normalization rules

• Handles are case-insensitive. Normalize input before matching (lowercase email and username comparisons).
• PNS names are lowercase on-chain. Always lowercase a PNS name before the contract lookup (e.g. king, not King).
• Legacy usernames are mapping-only. They resolve an account for internal lookups and airdrop mapping, but are NOT valid login credentials.

🤖 PGAI Wallet (Pentagon AI)

A Pentagon account can carry three different addresses, and integrators keep confusing them. They have different custody models and are not interchangeable. Read this table before you touch any wallet field.

Which one do I use?

• "Who is this user?" → the PG account id from GET /user/info. Not an address.
• "Where do in-app rewards land / what does the user spend from?" → aa_wallet_address (PG Balance), via the identity endpoints. Never derive it from a seed, never fetch it from mining.
• "What external wallet did the user connect?" → mm_address. Read-only.
• "What is the user's on-device Pentagon AI wallet?" → penai_address.

Binding & rotating the PGAI address

POST /user/penai/bind
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "address":    "0xabc...",
  "signature":  "0x...",
  "message":    "Sign up to Pentagon Games,1753400000",
  "login_from": "pentagon-ai-extension"
}

Message format: Sign up to Pentagon Games,{unix_timestamp_seconds} — the same personal_sign (EIP-191) scheme as /user/bind_metamask.

Timestamp window: the signature is rejected once the trailing timestamp is more than 5 minutes old. Sign at call time; never cache a signed message.

login_from: optional, recorded in the address history so a client can later tell the user which app set up their account.

Success response:

{
  "status": true,
  "result": { "penai_address": "0xabc..." }
}

Rotation limits

Both caps are checked before anything is written — a refused rotation leaves the current address untouched. Hitting either returns {"status": false, "message": "You have changed your Pentagon AI address too many times. Contact support."}

GET /user/penai/history

{
  "status": true,
  "result": {
    "current": "0xnew...",
    "addresses": [
      { "address": "0xnew...", "bound_at": "2026-08-01T09:12:44.318Z", "released_at": null,                       "login_from": "pentagon-ai-telegram"  },
      { "address": "0xold...", "bound_at": "2026-06-14T20:03:01.552Z", "released_at": "2026-08-01T09:12:44.318Z", "login_from": "pentagon-ai-extension" }
    ],
    "rotations_used": 2,
    "rotations_remaining": 3
  }
}

PGAI as a login credential

POST /user/login with type: "wallet" matches the signed address against either mm_address or penai_address. A device-held PGAI key is therefore a full login credential — this is what powers silent re-login after unlock in the Pentagon AI clients. See Authentication.

login_from values

Sent on POST /user/login, POST /user/bind_metamask and POST /user/penai/bind. On the PGAI bind it is persisted into the address history.

It is client-supplied and unvalidated — treat it as a display hint, never as an authorisation signal. Third-party integrators should send their own app name.

Cross-device wallet sync

Moving a self-custodial PGAI wallet from a device that has it (source) to a device that wants it (target), without the seed ever reaching Pentagon.

POST /user/sync/open        { "target_pubkey": "<base64>", "target_label": "Chrome on Windows", "safety_code": "0042" }
        →                    { "status": true, "result": { "channel_id": "...", "expires_in": 600 } }

GET  /user/sync/pending
        →                    { "status": true, "result": [ { "channel_id": "...", "target_pubkey": "<base64>",
                                                            "target_label": "Chrome on Windows", "safety_code": "0042",
                                                            "created_at": "2026-08-05T11:20:03.114Z" } ] }

POST /user/sync/approve     { "channel_id": "...", "ciphertext": "<opaque base64>" }   → { "status": true }
POST /user/sync/reject      { "channel_id": "..." }                                  → { "status": true }

POST /user/sync/fetch       { "channel_id": "..." }
        waiting →            { "status": true,  "result": { "state": "pending" } }
        approved →           { "status": true,  "result": { "state": "approved", "ciphertext": "<base64>" } }
        second fetch →       { "status": false, "message": "Already delivered" }
        rejected →           { "status": false, "message": "Request was rejected on the other device" }

target_pubkey is required (≤200 chars); target_label (≤120) and safety_code (≤12) are optional and exist only so the source device can render a useful prompt. Channel ids are generated server-side — a caller cannot choose or guess one. Opening a channel supersedes the user's other pending channels, so the source only ever sees the latest request.

Channel states: pending → approved → delivered, with rejected and expired as terminal side-exits.

The ciphertext is opaque to the backend — the encryption scheme is entirely a client concern. The reference Pentagon AI clients seal with ephemeral X25519 key agreement → HKDF-SHA256 (bound to both public keys) → XChaCha20-Poly1305, and show a 4-digit safety code derived from the public keys so the user can number-match both devices before approving.

API Endpoints

User Info

Wallet Binding

Cross-Device Wallet Sync

NFT Data

Social Auth & Connections

Email & Password

Friends System

VIP & Referrals

SSO (Single Sign-On)

2FA & Security

Signup

🖼️ NFT Data Platform

What You Get After User Login

A single login gives your application access to the user's entire Pentagon ecosystem data:

The Developer Flow

// 1. User logs in via your app (using Pentagon Identity)
const loginRes = await fetch('https://api.account.pentagon.games/user/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PG-App-Key': 'pk_live_your_key'
  },
  body: JSON.stringify({
    type: 'email',
    username: 'player@example.com',   // or PNS name like "nftprof"
    password: '***'
  })
});
const { access_token } = (await loginRes.json()).result;

// 2. Get user profile + wallet addresses
const userInfo = await fetch('https://api.account.pentagon.games/user/info', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
// Returns: username, email, mm_address, social accounts, profile picture...

// 3. Get ALL their NFTs across every supported chain
const nfts = await fetch('https://api.account.pentagon.games/user/nfts', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
// Returns: paginated list of every NFT the user owns

// 4. Filter by collection
const gunnies = await fetch('https://api.account.pentagon.games/user/nfts?collection=Gunnies%20PFP', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});

NFT API Endpoints

NFT Response Format

// GET /user/nfts response
{
  "success": true,
  "result": {
    "items": [
      {
        "id": 12345,
        "token_id": "4521",
        "name": "Gunnies PFP #4521",
        "type": "ERC-721",
        "image": "https://storage.googleapis.com/...",
        "desc": "A unique Gunnies PFP character"
      },
      {
        "id": 67890,
        "token_id": "1337",
        "name": "BCSH #1337",
        "type": "ERC-721",
        "image": "https://...",
        "desc": ""
      }
    ],
    "total_item": 47,
    "total_page": 5
  }
}

Supported Collections & Chains

The Pentagon oracle syncs NFT ownership data from 15+ blockchains. Below are the active collections with NFTs currently tracked:

Total: 368,522 NFTs tracked across 2.1M+ metadata records and 353,712 ownership records. 36 collections, 112 contracts, 15+ chains.

Use Cases

Internal / Approved Application Access

🔗 Integration Patterns

Pentagon Identity supports multiple integration patterns depending on what your app needs. Some apps need full identity + wallet verification, others just need login for data access, and some work wallet-first without requiring login at all. Choose the pattern that fits your use case.

Recommended: Direct In-Page Login

Build a login form directly on your page. The form lives in YOUR HTML/React/Vue app, collects credentials, calls the API, done. No external windows, no redirects, no popups to other sites.

Reference Implementation

Drop-in login components supporting all 4 sign-in methods. Uses your own App Key, no redirect needed. Full source on GitHub: pentagon-login-widget

// PentagonLoginModal.tsx — Drop-in popup login for any React/Next.js app
import { useState } from 'react';
import { useAccount, useSignMessage } from 'wagmi';
import { useConnectModal } from '@rainbow-me/rainbowkit';

const PG_API = 'https://api.account.pentagon.games';
const APP_KEY = process.env.NEXT_PUBLIC_PG_APP_KEY;

export function PentagonLoginModal({ isOpen, onClose, onLogin }) {
  const [tab, setTab] = useState('email');     // 'email' | 'wallet'
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');
  const { address, isConnected } = useAccount();
  const { signMessageAsync } = useSignMessage();
  const { openConnectModal } = useConnectModal();

  // Email + Password login (also works with PNS name or username)
  const handleEmailLogin = async (e) => {
    e.preventDefault();
    setLoading(true); setError('');
    try {
      const res = await fetch(`${PG_API}/user/login`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-PG-App-Key': APP_KEY
        },
        body: JSON.stringify({
          type: 'email',
          username: email,   // email, PNS name, or username all work
          password,
          login_from: 'your_app'
        })
      });
      const data = await res.json();
      if (data.status) {
        onLogin(data.result);  // { access_token, refresh_token }
        onClose();
      } else {
        setError(data.message || 'Login failed');
      }
    } catch (err) { setError('Network error'); }
    finally { setLoading(false); }
  };

  // Wallet signature login
  const handleWalletLogin = async () => {
    if (!isConnected) { openConnectModal?.(); return; }
    setLoading(true); setError('');
    try {
      const message = `Logging into Pentagon Games,${Math.floor(Date.now()/1000)}`;
      const signature = await signMessageAsync({ message });
      const res = await fetch(`${PG_API}/user/login`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-PG-App-Key': APP_KEY
        },
        body: JSON.stringify({
          type: 'wallet',
          signature,
          address: address.toLowerCase(),
          message,
          login_from: 'your_app'
        })
      });
      const data = await res.json();
      if (data.status) {
        onLogin(data.result);
        onClose();
      } else {
        setError(data.message || 'Wallet not linked to an account');
      }
    } catch (err) { setError('Signature rejected or failed'); }
    finally { setLoading(false); }
  };

  if (!isOpen) return null;
  return (
    <div style={{
      position:'fixed', inset:0, zIndex:9999,
      background:'rgba(0,0,0,0.6)', backdropFilter:'blur(4px)',
      display:'flex', alignItems:'center', justifyContent:'center'
    }} onClick={onClose}>
      <div onClick={e => e.stopPropagation()} style={{
        background:'#12121a', border:'1px solid #2a2a3a', borderRadius:16,
        padding:32, width:400, maxWidth:'90vw', color:'#e0e0e8'
      }}>
        <h2 style={{margin:'0 0 20px', fontSize:20}}>⛠ Sign In</h2>

        {/* Tabs */}
        <div style={{display:'flex', gap:0, borderBottom:'1px solid #2a2a3a', marginBottom:20}}>
          <button onClick={() => setTab('email')} style={{
            padding:'8px 20px', background:'none', border:'none', cursor:'pointer',
            color: tab==='email' ? '#7c5cff' : '#8888a0',
            borderBottom: tab==='email' ? '2px solid #7c5cff' : '2px solid transparent'
          }}>Email</button>
          <button onClick={() => setTab('wallet')} style={{
            padding:'8px 20px', background:'none', border:'none', cursor:'pointer',
            color: tab==='wallet' ? '#7c5cff' : '#8888a0',
            borderBottom: tab==='wallet' ? '2px solid #7c5cff' : '2px solid transparent'
          }}>Wallet</button>
        </div>

        {error && <div style={{color:'#ff4c6a', fontSize:14, marginBottom:12}}>{error}</div>}

        {tab === 'email' ? (
          <form onSubmit={handleEmailLogin}>
            <input placeholder="Email, PNS name, or username" value={email}
              onChange={e => setEmail(e.target.value)} style={inputStyle} />
            <input type="password" placeholder="Password" value={password}
              onChange={e => setPassword(e.target.value)} style={inputStyle} />
            <button type="submit" disabled={loading} style={btnStyle}>
              {loading ? 'Signing in...' : 'Sign In'}
            </button>
          </form>
        ) : (
          <button onClick={handleWalletLogin} disabled={loading} style={btnStyle}>
            {loading ? 'Confirming...' : isConnected
              ? `Sign with ${address.slice(0,6)}...${address.slice(-4)}`
              : 'Connect Wallet'}
          </button>
        )}

        <button onClick={onClose} style={{
          marginTop:16, background:'none', border:'none',
          color:'#8888a0', cursor:'pointer', width:'100%', textAlign:'center'
        }}>Cancel</button>
      </div>
    </div>
  );
}

const inputStyle = {
  width:'100%', padding:'10px 14px', marginBottom:12, borderRadius:8,
  border:'1px solid #2a2a3a', background:'#0a0a0f', color:'#e0e0e8',
  fontSize:14, outline:'none'
};
const btnStyle = {
  width:'100%', padding:'12px', borderRadius:8, border:'none',
  background:'#7c5cff', color:'white', fontSize:15,
  fontWeight:600, cursor:'pointer'
};

// Usage in your app:
// const [showLogin, setShowLogin] = useState(false);
// <button onClick={() => setShowLogin(true)}>Sign In</button>
// <PentagonLoginModal
//   isOpen={showLogin}
//   onClose={() => setShowLogin(false)}
//   onLogin={({ access_token }) => { saveToken(access_token); loadUser(); }}
// />

// Vanilla JS popup modal — no framework needed
// Add to any HTML page

const PG_API = 'https://api.account.pentagon.games';
const APP_KEY = 'pk_live_your_key';

function showPentagonLogin(onSuccess) {
  // Create overlay
  const overlay = document.createElement('div');
  overlay.style.cssText = `
    position:fixed; inset:0; z-index:9999;
    background:rgba(0,0,0,0.6); backdrop-filter:blur(4px);
    display:flex; align-items:center; justify-content:center;
  `;

  overlay.innerHTML = `
    <div style="background:#12121a; border:1px solid #2a2a3a; border-radius:16px;
      padding:32px; width:400px; max-width:90vw; color:#e0e0e8;">
      <h2 style="margin:0 0 20px; font-size:20px;"⛠ Sign In</h2>
      <input id="pg-email" placeholder="Email, PNS name, or username"
        style="width:100%; padding:10px 14px; margin-bottom:12px; border-radius:8px;
        border:1px solid #2a2a3a; background:#0a0a0f; color:#e0e0e8;" />
      <input id="pg-pass" type="password" placeholder="Password"
        style="width:100%; padding:10px 14px; margin-bottom:12px; border-radius:8px;
        border:1px solid #2a2a3a; background:#0a0a0f; color:#e0e0e8;" />
      <div id="pg-error" style="color:#ff4c6a; font-size:14px; margin-bottom:8px;"></div>
      <button id="pg-submit" style="width:100%; padding:12px; border-radius:8px;
        border:none; background:#7c5cff; color:white; font-size:15px;
        font-weight:600; cursor:pointer;">Sign In</button>
      <button id="pg-cancel" style="margin-top:12px; width:100%; background:none;
        border:none; color:#8888a0; cursor:pointer;">Cancel</button>
    </div>
  `;

  overlay.querySelector('#pg-cancel').onclick = () => overlay.remove();
  overlay.onclick = (e) => { if (e.target === overlay) overlay.remove(); };

  overlay.querySelector('#pg-submit').onclick = async () => {
    const email = overlay.querySelector('#pg-email').value;
    const pass = overlay.querySelector('#pg-pass').value;
    const errEl = overlay.querySelector('#pg-error');
    try {
      const res = await fetch(`${PG_API}/user/login`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'X-PG-App-Key': APP_KEY },
        body: JSON.stringify({ type:'email', username:email, password:pass, login_from:'your_app' })
      });
      const data = await res.json();
      if (data.status) {
        overlay.remove();
        onSuccess(data.result);  // { access_token, refresh_token }
      } else {
        errEl.textContent = data.message || 'Login failed';
      }
    } catch(e) { errEl.textContent = 'Network error'; }
  };

  document.body.appendChild(overlay);
}

// Usage:
// document.getElementById('login-btn').onclick = () => {
//   showPentagonLogin(({ access_token }) => {
//     localStorage.setItem('pg_token', access_token);
//     loadUserData();
//   });
// };

// Server-side or API-only login (no popup needed)
// Good for backends, CLI tools, or server-rendered apps

async function pgLogin(email, password) {
  const res = await fetch('https://api.account.pentagon.games/user/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-PG-App-Key': 'pk_live_your_key'
    },
    body: JSON.stringify({
      type: 'email',
      username: email,      // works with email, PNS name, or username
      password: password,
      login_from: 'your_app'
    })
  });
  const data = await res.json();
  if (data.status) {
    return data.result;  // { access_token, refresh_token }
  }
  throw new Error(data.message || 'Login failed');
}

Login Methods (All Patterns)

Before choosing a pattern, understand the available login methods. All use POST /user/login with X-PG-App-Key header:

Pattern 1: PG Login + Wallet Match (Strict Identity)

User logs in via PG Identity, then connects their browser wallet. The app verifies the connected wallet matches the wallet registered to their PG account. This ensures the person controlling the wallet is the verified account holder.

Flow:

1. User logs in via any PG login method → gets JWT access_token
2. App calls GET /user/info with Bearer token → gets mm_address (registered wallet)
3. User connects browser wallet via RainbowKit/WalletConnect
4. Frontend compares: if connected.toLowerCase() !== mm_address.toLowerCase() → block, show mismatch warning
5. All transactions must come from the matched wallet

// After PG login, verify wallet match
const userInfo = await fetch('/user/info', {
  headers: { Authorization: `Bearer ${token}` }
});
const { mm_address } = (await userInfo.json()).result;

// Compare with connected wallet (from wagmi useAccount)
if (connectedAddress.toLowerCase() !== mm_address.toLowerCase()) {
  showError("Please connect the wallet registered to your Pentagon account");
  return;
}
// Wallet verified — proceed with transactions

When to use: DeFi apps, staking, token swaps, any app where on-chain actions must be tied to verified identity. Transactions go directly to smart contracts from user's wallet.

Transaction handling: Direct contract calls from user's wallet. No backend fulfillment needed. Frontend uses wagmi/viem writeContract. User pays gas from their own wallet.

Pattern 2: PG Login + Any Wallet (Flexible Wallet)

User logs in via PG Identity to pull their NFT data and account info, but can connect ANY wallet for mining operations. This is intentional — users shouldn't have to use their sensitive NFT-holding wallet for mining.

Flow:

1. User logs in via PG Identity → gets JWT → app fetches their NFTs via GET /user/nfts
2. User connects any wallet for mining (does NOT need to match mm_address)
3. Mining rewards are tracked by the connected mining wallet, not the PG wallet
4. NFT ownership is verified from PG account data, not from the connected wallet

When to use: Apps where NFT ownership verification is needed but the operational wallet can differ. Protects users from exposing high-value wallets.

Transaction handling: Backend-driven fulfillment. User submits mining action, backend verifies NFT ownership from PG data, and either:

• Backend watches for tx from user's mining wallet (tx hash or nonce tracking)
• Backend fulfills reward distribution to the mining wallet

Pattern 3: PG Login Only (No Wallet)

Pure PG Identity login with no external wallet connection needed. The app uses the user's internal PG wallet (also called the AA wallet / NPC wallet; field centralised_wallet_address) for any on-chain interactions, using NPC points as gas.

Read flow (load the wallet + balance after login):

1. User logs in via PG Identity → gets JWT (one token, one backend, one secret)
2. App calls GET /user/walletinfo with Authorization: Bearer <login JWT>
3. Response returns the internal wallet_address plus live pc_balance (queried from Pentagon Chain RPC by the identity backend) and npc_points
4. Conversion: 1 PC = 1000 NPC points (npc_points = pc_balance × 1000)

GET https://api.account.pentagon.games/user/walletinfo
Authorization: Bearer <login JWT>

// 200 OK
{
  "wallet_address": "0xc9e2D370...",   // the internal AA/NPC wallet, from user_wallet
  "pc_balance": 2.949,                  // live PC, read from Pentagon RPC (chain 3344)
  "npc_points": 2949,                   // pc_balance × 1000
  "live_balance": true
}

Spend flow (deduct NPC / move funds from the user's internal wallet):

1. User triggers a paid action (the card example: candy, cookie, flower, email, gift)
2. App POSTs the action to the identity backend with the login JWT
3. The identity backend validates the action + amount against a server-side allowlist (e.g. candy=5 NPC, gift up to 1000), resolves the recipient, then decrypts the user's stored private key (using the backend's own WALLET_PASSWORD / decrypt function) and signs the transaction itself
4. It returns the tx hash + remaining balance

For the ID Card spend, the signed tx calls the on-chain CardSpendSplitter contract 0xf6f7b1615f7d3d2a0997848078dd200270304776, which splits each payment 30% to the recipient / 20% platform / 50% held for the spender. The contract is on-chain and not mining-owned, so any stack may call it directly with the user's stored key — no mining involvement.

POST https://api.account.pentagon.games/user/wallet/card-spend
Authorization: Bearer <login JWT>
Content-Type: application/json

{
  "action": "candy" | "cookie" | "flower" | "email" | "gift",
  "owner_handle": "nftprof",
  "amount": 5
}
// → validate (allowlist) → resolve owner wallet → decrypt spender key
//   → CardSpendSplitter.pay(owner) → returns { tx_hash, remaining_balance, split }

When to use: The Pentagon ID Card, social features, points systems, profile management, any feature that uses the user's managed internal wallet rather than a user-signed external wallet.

Transaction handling: Fully backend-managed within the identity stack. The user never signs and never sees a seed. The identity backend already has everything it needs natively — web3, the Pentagon Chain config (chain 3344, RPC), the user_wallet record, and the decrypt-and-sign function. NPC points act as the gas/spend abstraction. Zero dependency on mining or any other product backend.

Pattern 4: Wallet-First (PG Account Check)

User connects wallet first via RainbowKit (no PG login required). The app checks if the connected wallet belongs to a verified PG account. This allows NFT purchases without requiring full PG login — just wallet.

Flow:

1. User connects wallet via RainbowKit modal
2. App sends wallet signature to POST /user/login with type="wallet"
3. If wallet is bound to a PG account → auto-login, load user data
4. If wallet is NOT bound → user can still buy NFTs (purchase-only mode) or prompted to create account
5. After successful wallet login, app checks mm_address match

// Wallet-first login
const message = `Logging into Pentagon Games,${Math.floor(Date.now() / 1000)}`;
const signature = await signMessageAsync({ message });
const result = await signIn('wallet-login', {
  signature,
  address: address.toLowerCase(),
  message,
  redirect: false
});
// If user has PG account → logged in
// If not → show signup or continue in wallet-only mode

When to use: NFT marketplaces, purchase flows, game clients where wallet presence matters more than full identity verification. Lowers friction for buyers.

Transaction handling: Direct contract calls from user's connected wallet. For purchases that need backend fulfillment (minting, reward distribution), backend watches for the tx hash or catches wallet + nonce to verify payment and fulfill.

Pattern 5: Wallet-First + PG Optional (Zero Friction)

User connects any wallet with zero PG account required. Their NFTs are loaded directly from the NFT data API by wallet address. They can use the app immediately. If they later create a PG account (or already have one), the experience upgrades automatically.

How it differs from Pattern 4: Pattern 4 (Gunnies.io) connects wallet then silently checks if it's a PG account and auto-logs in. Pattern 5 doesn't require or check for a PG account at all. The wallet IS the identity. PG login is purely an optional enhancement layer.

1. User connects wallet via RainbowKit (no signup, no PG account needed)
2. App loads NFTs from NFT data API: GET nft-data.pentagon.games/api/v1/nft/owner/{address}
3. User can start using the app immediately (e.g., mining with on-chain mode)
4. App shows CTA to create PG account for enhanced features
5. If user creates account or logs in, experience upgrades: faster indexed NFT loading, offchain modes, free gas, PNS identity

// Pattern 5: Wallet-first, PG optional
import { useAccount } from 'wagmi';

const { address, isConnected } = useAccount();

// Load NFTs directly by wallet address (no PG login needed)
const nfts = await fetch(`https://nft-data.pentagon.games/api/v1/nft/owner/${address}`);

// Check if they have a PG account (optional enhancement)
const pgCheck = await fetch(`https://api.account.pentagon.games/user/info_by_username/public/${address}`);
const hasPGAccount = pgCheck.status === true;

if (hasPGAccount) {
  // Unlock enhanced features: offchain mining, faster data, free gas
} else {
  // Show CTA to create PG account
}

When to use: Apps targeting web3-native users who may not have a Pentagon account. Eliminates signup friction entirely. The PG account becomes a value-add, not a gate.

Transaction handling: User wallet handles all transactions directly (on-chain). For PG-enhanced features (offchain mining), backend fulfillment via managed wallet.

Pattern Comparison

Wallet Connection Toolkit

Pentagon ecosystem uses RainbowKit v2 + wagmi v2 + viem for wallet connections.

// Web3Provider.tsx
import { getDefaultConfig } from '@rainbow-me/rainbowkit';
import { skaleNebula, coreDao, mainnet } from 'wagmi/chains';

const PentagonChain = {
  id: 3344, name: 'Pentagon Chain',
  nativeCurrency: { name: 'PC', symbol: 'PC', decimals: 18 },
  rpcUrls: { default: { http: ['https://rpc.pentagon.games'] } },
  blockExplorers: { default: { name: 'Explorer', url: 'https://explorer.pentagon.games' } }
};

export const config = getDefaultConfig({
  appName: 'Your App Name',
  projectId: 'YOUR_WALLETCONNECT_PROJECT_ID',
  chains: [mainnet, PentagonChain, skaleNebula, coreDao],
});

Dependencies:

{
  "@rainbow-me/rainbowkit": "2",
  "wagmi": "^2.15.3",
  "viem": "2.x",
  "@wagmi/core": "^2.17.1"
}

Transaction Handling

Two models depending on who fulfills:

Direct Contract (Patterns 1 & 4):

User wallet calls contract directly. Frontend uses wagmi writeContract or sendTransaction. No backend tracking needed — contract events handle fulfillment. User pays gas.

import { useWriteContract } from 'wagmi';
const { writeContract } = useWriteContract();
await writeContract({
  address: '0xContractAddress',
  abi: contractABI,
  functionName: 'mint',
  args: [tokenId],
  value: parseEther('0.01')
});

Backend Fulfillment (Patterns 2 & 3):

Backend needs to know when user has paid or taken action. Two approaches:

1. TX Hash tracking: User submits tx, frontend sends tx hash to backend, backend watches for confirmation
2. Wallet + Nonce tracking: Backend knows the user's wallet and expected nonce, watches for matching tx on-chain

Backend then fulfills (mints reward, updates state, distributes tokens) using a service wallet.

// Frontend: send tx hash to backend for tracking
const tx = await writeContract({ ... });
await fetch('/api/submit-mining', {
  method: 'POST',
  headers: { Authorization: `Bearer ${pgToken}` },
  body: JSON.stringify({ txHash: tx, walletAddress: connectedAddress })
});
// Backend watches chain for tx confirmation, then fulfills

SSO Login Widget (OAuth2 Redirect Flow)

How It Works

1. Your site redirects user to https://pentagon.games/sso-login-widget with OAuth2 parameters
2. User logs in on Pentagon Games (if not already authenticated)
3. User sees an approval screen: "Allow [Your App] to access your Pentagon Games account?"
4. User clicks Approve
5. Pentagon Games redirects back to your redirect_uri with an authorization code
6. Your backend exchanges the code for an access token via POST /sso/token

Step 1: Register Your SSO Client

Contact Pentagon Games team to register your app and get a client_id and client_secret. Provide:

• App name: "Your App Name"
• Redirect URI(s): https://yourapp.com/auth/callback (must be HTTPS in production)
• App description: Brief description shown on approval screen

Step 2: Redirect User to SSO Login Widget

// When user clicks "Sign in with Pentagon Games" on your site:
const params = new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://yourapp.com/auth/callback',
  response_type: 'code',
  state: generateRandomState()  // CSRF protection, verify this on callback
});
window.location.href = `https://pentagon.games/sso-login-widget?${params}`;

Step 3: Handle the Callback

After user approves, Pentagon Games redirects to your redirect_uri with query params:

https://yourapp.com/auth/callback?code=AUTH_CODE_HERE&state=YOUR_STATE

Your backend extracts the code and exchanges it for a token:

// Backend endpoint: /auth/callback
const { code, state } = req.query;

// Verify state matches what you sent (CSRF protection)
if (state !== req.session.oauthState) {
  return res.status(400).json({ error: 'Invalid state' });
}

// Exchange code for token
const tokenResponse = await fetch('https://api.account.pentagon.games/sso/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PG-App-Key': 'YOUR_APP_KEY'
  },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: code,
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    redirect_uri: 'https://yourapp.com/auth/callback'
  })
});

const { access_token, refresh_token, expires_in } = await tokenResponse.json();

// Store tokens securely (server-side session or encrypted cookie)
req.session.pgToken = access_token;

// Redirect user to your app's main page
res.redirect('/dashboard');

Step 4: Use the Access Token

// Call Pentagon Identity API on behalf of the user
const userInfo = await fetch('https://api.account.pentagon.games/user/info', {
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'X-PG-App-Key': 'YOUR_APP_KEY'
  }
});

const { result } = await userInfo.json();
console.log(result.username, result.mm_address, result.nfts);

Refresh Token Flow

Access tokens expire after 24 hours. Use the refresh token to get a new one without requiring the user to log in again:

const refreshResponse = await fetch('https://api.account.pentagon.games/user/token/refresh', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PG-App-Key': 'YOUR_APP_KEY'
  },
  body: JSON.stringify({
    refresh: refresh_token
  })
});

const { access } = await refreshResponse.json();
// Update stored token
req.session.pgToken = access;

Security Best Practices

• Always use HTTPS for redirect URIs in production
• Verify the state parameter to prevent CSRF attacks
• Store tokens server-side (session, encrypted database), never in localStorage
• Keep client_secret private — only use it on your backend, never expose to frontend
• Handle token expiration gracefully with refresh token flow

Legacy SSO Widget (Popup-based)

For existing SSO client apps that already use the popup widget:

<!-- Legacy SSO Widget — for existing SSO clients only -->
<script src="https://login.pentagon.games/static/js/pgwidget-sdk-v1.js"></script>
<pentagon-widget clientid="YOUR_SSO_CLIENT_ID"></pentagon-widget>
<script>
  window.PentagonWidget.mount();
  window.addEventListener('PentagonGamesSignInOnSuccess', (e) => {
    const token = e.detail.token;
    // User is logged in, use token for API calls
  });
</script>

The legacy widget opens a popup to login.pentagon.games, handles auth, and fires a PentagonGamesSignInOnSuccess event with the JWT token. Currently 5 SSO clients registered. New apps should use the OAuth2 redirect flow above or the in-app login pattern.

App Keys

Every application that calls the Pentagon Identity API must include an App Key header to identify itself.

How It Works

X-PG-App-Key: pk_live_your_key_here

Add this header to all requests to the Identity API. Keys are issued per-application and tracked for analytics and security.

Key Types

Getting a Key

Contact the Pentagon Games team to register your application and receive a key:

• Email: nftprof@pentagon.games
• Discord: Pentagon Games server (reach out to a team member)

You'll need to provide:

• App name — what your app is called
• App type — web, native, or server
• Allowed origins or IPs — the domains or server IPs your app will call from
• Contact email — for security notifications and key rotation alerts

Database Reference

The Pentagon Identity system is backed by pg_identity_db, a dedicated PostgreSQL database. Below is a reference of all tables organized by domain.

Core Identity

Primary user records, wallets, login tracking, and profile data.

Social & Auth

Social platform connections, OAuth tokens, Discord role sync, and social graph.

App Key System

Application registration, key tracking, and usage analytics.

NFT Data

Cross-chain NFT ownership and metadata, synced by backend oracle.

Campaign & Rewards

Badge campaigns, referral tracking, and reward distribution.

PenXR / Metaverse

Metaverse user data, spaces, inventory, and virtual currency.

Wallet Infrastructure

Chain definitions, token lists, bridge logs, and supply tracking.

SSO

Security

Security keys, KYC, anti-sybil, and access control.

EchoVault

On-chain identity vault contract interactions.

Migration Guide

Step 1: Get Your Key

Contact Pentagon Games team or check if a key has already been generated for your app.

Step 2: Add the Header

Add X-PG-App-Key to every request that hits login/signup endpoints.

Affected endpoints:

• POST /user/login
• POST /user/login/email
• POST /user/login/ethermail
• POST /user/signup/ethermail
• POST /api/v3/user/signup
• POST /api/v4/user/signup
• POST /sso/authorize
• POST /sso/token

Code Examples

// Add to your login API call
const response = await fetch("https://api.account.pentagon.games/user/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-PG-App-Key": process.env.PG_APP_KEY,  // ← Add this
  },
  body: JSON.stringify({
    type: "email",
    username: email,
    password: password,
    login_from: "your_app",
  }),
});

const data = await response.json();
if (data.status) {
  const token = data.result.access_token;
  // Store token, use as Bearer auth for subsequent requests
}

using UnityEngine.Networking;
using System.Text;

string json = JsonUtility.ToJson(new LoginRequest {
    type = "email",
    username = email,
    password = password,
    login_from = "gunnies_pc"
});

UnityWebRequest request = new UnityWebRequest(
    "https://api.account.pentagon.games/user/login", "POST");
byte[] bodyRaw = Encoding.UTF8.GetBytes(json);
request.uploadHandler = new UploadHandlerRaw(bodyRaw);
request.downloadHandler = new DownloadHandlerBuffer();
request.SetRequestHeader("Content-Type", "application/json");
request.SetRequestHeader("X-PG-App-Key", appKey);  // ← Add this

yield return request.SendWebRequest();

import requests
import os

response = requests.post(
    "https://api.account.pentagon.games/user/login",
    headers={
        "Content-Type": "application/json",
        "X-PG-App-Key": os.environ["PG_APP_KEY"],  # ← Add this
    },
    json={
        "type": "email",
        "username": username,
        "password": password,
        "login_from": "backend_service",
    },
)

data = response.json()
if data["status"]:
    token = data["result"]["access_token"]

curl -X POST https://api.account.pentagon.games/user/login \
  -H "Content-Type: application/json" \
  -H "X-PG-App-Key: pk_test_your_key" \
  -d '{
    "type": "email",
    "username": "test@example.com",
    "password": "password123",
    "login_from": "testing"
  }'

Timeline

VIP — My Data Access

What You Get

Rate Limits

Usage

# Use your personal API key
curl -H "X-PG-User-Key: uk_live_your_key" \
  https://api.account.pentagon.games/user/info

# Get your NFTs
curl -H "X-PG-User-Key: uk_live_your_key" \
  https://api.account.pentagon.games/user/nfts

# Get a friend's public info
curl -H "X-PG-User-Key: uk_live_your_key" \
  https://api.account.pentagon.games/user/friends/friendname/info

🏗️ Architecture & Shared API

Why "Account" = Identity + Payments

The domain is api.account.pentagon.games, not api.identity.pentagon.games. That's because an account encompasses both who you are (identity) and what you've paid for (payments). In the accounting sense: your account is your full ledger.

What Lives on This API

Server Topology

Database Separation

Identity and payments use separate databases even though they share an API server:

• pg_identity_db — user accounts, auth, profiles, wallets, social, VIP
• pg_payments_db — payment intents, Stripe sessions, fulfillment status, mint records

This means the payment system can be extracted to its own server cleanly when the time comes, no schema entanglement.

Related Documentation

For payment-specific details (Stripe integration, fulfillment flow, scanner architecture), see the Payment Processor Docs.