What is the PGAI Wallet?

The Pentagon AI wallet is your account for the Pentagon Games ecosystem. It comes in three forms that all hold the same account: a browser extension, a mobile app, and the Telegram mini-app. You sign in with your normal Pentagon Games account — if you already log in to pentagon.games, you are most of the way there.

It runs on Pentagon Chain (chain id 3344) only, and its currency is $PC. There is deliberately no chain picker and no way to import outside wallets — see Why you can't import a seed phrase.

Your balances, explained

• Balance — money you control on your device. Only your password can move it. This is your self-custody PGAI account.
• PG Balance — a separate account managed by Pentagon Games, created with your email sign-in. It spends on your behalf inside Pentagon games and holds your Points. Top it up with a card, $PC or USDC on the website, or Telegram Stars in the Telegram app — how many Points a top-up gives depends on the pack, and packs can carry bonus Points. Points are not a token and can’t be swapped for $PC. Points are an in-game top-up balance — bought, spent in the ecosystem, never cashed out.
• Watch-only wallet — if you connected an external wallet (e.g. MetaMask) to your PG account, the app shows its balance for convenience. The app holds no keys for it and can never move it.

Signing in and unlocking

First time: sign in with your Pentagon Games email/username and password (or sign up in the app). Then you create a wallet with its own account password.

After that, unlocking is signing in: enter your account password, and the wallet proves who you are to Pentagon Games with a cryptographic signature — no PG password needed again on that device.

Sign in on another device

Already signed in somewhere? Choose Sign in on another device there, and scan the code it shows with your new device. Scanned sessions can browse but can never export your account — that protection is deliberate.

Sending $PC

Account → Transfer. Pick a friend (fills their address for you) or paste an address. You always see the amount, network fee and total before anything is signed, and nothing moves until you tap Sign & send.

If a transfer fails you'll get a precise error code. WAL-SEND-FAIL means nothing left your account; WAL-SEND-UNCONFIRMED means it was broadcast but not yet confirmed — check your Activity before retrying so you don't pay twice.

Receiving funds

Account → Receive shows your address and a scannable code. Your address is public information — safe to share with anyone.

Friends and “My card”

Friends are other Pentagon Games players. Adding one lets you send $PC by name — no address copying — and appear in each other's games.

My card is your shareable QR code: anyone who scans it adds you as a friend and opens your agent, exactly like tapping your physical Pentagon NFC card. Each code works once and refreshes every ~30 seconds, so an old screenshot of it is useless.

Collectibles (NFTs) and trading

Account → Collectibles shows your items and the market13 marketplace. Each trade carries a 2.5% marketplace fee — buyers pay it on top, sellers receive the price minus it — plus a small network fee. Every price and fee is shown for confirmation before anything is signed.

Some prices are in WPC (wrapped $PC): it is always worth exactly 1 $PC = 1 WPC — a technical wrapper the marketplace uses for offers, not a different token with a different price.

Topping up Points

On the PG Balance card, tap Top up Points. It opens the official pentagon.games top-up page already signed in as you (inside Telegram, Stars packs are right on the card). How many Points you get depends on the pack — packs can carry bonus Points. Points live on your PG Balance and are spent inside Pentagon games.

Signing in with Telegram

Inside Telegram, opening the wallet is signing up: your Telegram account becomes your Pentagon account on first open — no email, no password to invent. If an email already belongs to a Pentagon account, you'll see a masked hint and can sign in to link the two rather than creating a duplicate.

A Telegram session works like an email magic-link session: it can play, spend Points and top up. Moving value out of self-custody — sending from your PGAI wallet or binding a new external wallet — always asks for your wallet password. Under Complete your profile you can add and verify an email so the account is yours even outside Telegram.

Telegram Stars and the $1 starter pack

Inside Telegram, the Points packs on the Account tab are paid with Telegram Stars, without leaving the app. The cheapest is the $1 starter — 25 Points; it's shown once per account and disappears after you've taken it. If you don't have Stars yet, Telegram will ask you to buy them first. On Telegram Desktop that in-invoice purchase currently fails (a Telegram bug, not ours): buy Stars from Telegram → Settings → My Stars or @PremiumBot, then tap the pack again — on iOS and Android it works directly. If the sheet is cancelled, a Pay by card instead button appears right there with the same pack preselected; it opens the web top-up page in your browser, already signed in, so a Telegram-only account can finish by card without an email or password. Points arrive within a minute or two of a successful payment.

Points are a spending balance inside Pentagon games, not a token: they can't be swapped for $PC, cashed out or transferred. How many Points a pack gives you depends on the pack, and packs can carry bonus Points.

Invite friends (referrals)

Under Invite friends on the Account tab you'll find your referral code (your username today) and your link pentagon.games/sign-up/<your-username>, with a count of who joined through it. Anyone who creates their account through your link is recorded as your referral, permanently.

Referral rewards are not switched on yet. When they are, they'll be paid in Points on what the people you invited top up — never for merely signing up — and this page will state exactly what pays out. Nothing is lost by inviting now.

Add to your home screen

In Telegram, the Account tab offers Add to home screen. It uses Telegram's own install prompt, so one tap puts Pentagon AI on your phone's home screen — opening straight into your account, no searching for the chat. Dismiss it once and it stays out of the way.

The AI companion

The Agent tab is your own AI companion for the Pentagon ecosystem — a 3D character that idles on the tab, and a chat bar that stays pinned at the bottom. It knows your account: your Points, which games you've played, and what your next step is (top up, secure your account with an email, create your PGAI wallet). Greetings and common asks answer instantly; it only ever offers things it can actually do — open a game, open top-up, the Marketplace, Members — and does them in one tap. You can change which character represents you under About this agent.

Two honest rules:

• It is openly an AI, not a human.
• It never asks for your password and cannot move your funds — money only moves in the Account tab, signed by you. It has no value-moving tools at all.

Only you can talk to the agent in your wallet. The agent on your NFC card is the public version that greets people who tap your card.

Error codes & getting help

Every error in the wallet carries a code like WAL-SEND-FAIL. If something keeps failing, join our Discord — discord.gg/pentagongamesxp — and file a ticket including the code. That code tells the team exactly which path failed.

Common codes

Custody model — what's yours, what's managed

• Your PGAI account (Balance) is self-custody: the key is generated on your device, sealed with your password, and never leaves it unencrypted. Pentagon Games cannot move these funds and cannot recover the password.
• Your PG Balance (Points) is custodial: Pentagon Games manages that account server-side so games can spend from it with your authorization. That is why it shows “Managed by Pentagon Games” and has no Transfer button in the wallet.
• Watch-only external wallets are display-only imports of an address, not of keys.

How your key is protected (the vault)

Your key is sealed in a local vault: the password is stretched with PBKDF2 (600,000 iterations, SHA-256) and the key material encrypted with AES-256-GCM. Unlocking happens in memory only; locking wipes it. The vault never leaves your device except in the device-to-device sync, where it is re-sealed to the receiving device's key and rejected unless it derives the same address.

There is no server escrow and no recovery: lose the password on every device and the account is gone. That is the self-custody trade — the same property that means nobody else can take it.

Why you can't import a seed phrase

By design the wallet creates keys, never imports them. Imported phrases have unknowable histories — pasted into sites, stored in notes apps, phished. Refusing import means every PGAI account key was born inside the app's vault and has never existed in plaintext anywhere else. To use an existing external wallet, connect it to your PG account and it appears watch-only.

Signature auto-login

After the first sign-in, your wallet key doubles as your credential: unlocking signs a time-stamped challenge (Sign up to Pentagon Games,<unix>) which the backend verifies against your registered address. No PG password is stored on the device; the session token lives in memory only.

Moving to a new device (sync)

Device sync transfers your sealed account device-to-device with a number-match confirmation on both screens. The payload is sealed to an ephemeral key of the receiving device and is rejected unless it derives to your registered address. The old device becomes retired: it can still send its remaining balance out, but new rewards go to the current device. QR-delegated sessions can never be a sync source.

Pentagon Chain parameters

Connecting your dapp (EIP-6963)

The browser extension announces itself via EIP-6963 — no window.ethereum squatting:

• rdns: games.pentagon.ai
• name: Pentagon AI
• provider flag: isPentagonAI; also exposed as window.pentagonAI

Any 6963-aware stack (wagmi v2, RainbowKit v2, viem) discovers it automatically. Users approve each site once (connect approval), and every signature or transaction request is approved per-request in the wallet UI. Pentagon Chain (3344) only — requests for other chains are refused.

Full integration guide with a wallet-picker snippet: see WALLET-INTEGRATION.md in the wallet repository, or ask in the developer channel on Discord.

Sign in with Pentagon (overlay)

Add a Pentagon sign-in to any page on pentagon.games. It opens as an overlay over your page, like Stripe Checkout: our sign-in in a frame, your page stays put, and the user never leaves. It authenticates only: no seed, no wallet setup, no signature. The session can spend Points (signed server-side) but holds no key.

Drop-in

<script src="/pgai/web-local-app/pg-signin.js" defer></script>

<a href="/pgai/web-local-app/?continue=home2" data-pg-signin>Log in</a>

<script>
document.addEventListener('click', function (e) {
  var a = e.target.closest && e.target.closest('[data-pg-signin]')
  if (!a || !window.PGSignIn) return
  e.preventDefault()
  PGSignIn.open().then(function (r) { if (r.ok) location.reload() })
})
</script>

The href is the fallback: if the script fails, the link still signs the user in full-page and returns them to the page (allowlisted keys: home2, redeem).

Using the login

const token = PGSignIn.token()  // localStorage.pg_token
fetch('https://api.account.pentagon.games/user/info', {
  headers: { Authorization: 'Bearer ' + token },
})  // 401 -> PGSignIn.signOut(), show Log in again

How it stays safe

• The sign-in page can only be framed by pentagon.games itself (frame-ancestors 'self'). Other domains use the SSO client flow.
• The token is written to localStorage.pg_token on pentagon.games and is never sent in a message. The page gets only { type: 'pg-login', ok }, targeted at this origin.
• The helper checks each message's origin and source before trusting it.

Resolving addresses to PG identities

Ecosystem services can resolve a Pentagon Chain address to a PG username via the identity backend's address-lookup endpoint (API-key gated; covers connected, PGAI and managed addresses). This is what powers “sending to @name” in the wallet. Request access through the Pentagon developer channel.