Wallet-based identity system. Challenge-response authentication, multi-chain wallet linking, session management, social verification, and multi-device approval flows.
Agorix uses wallet-based authentication. Usernames are public profile aliases; your identity and account access are still anchored to wallet signatures.
Authentication follows a two-step challenge-response flow:
Step 1: Issue Challenge
The client calls issueChallenge with:
chain: BTC, ETH, or SOLaddress: The wallet address to authenticatepurpose: SESSION_BOOTSTRAP (new session) or LINK_WALLET (add wallet to existing profile)The server generates a profileLinkChallenges record containing a random nonce and a human-readable message to sign. Challenges expire after 10-15 minutes.
Step 2: Verify Signature
The client signs the challenge message using the wallet's private key and submits:
challengeId: Which challenge to verifysignature: The wallet signaturedeviceLabel: Optional device identifierThe server verifies the signature against the wallet address using verifyProof (protocol-level verification). On success:
profileSessions record. Returns a session token.profileWalletLinks record connecting the wallet to the existing profile.Sessions are stored in the profileSessions table:
| Field | Purpose |
|---|---|
tokenHash | SHA-256 hash of the session token (token never stored in plaintext) |
actingWalletChain / actingWalletAddress | Which wallet this session authenticated with |
status | ACTIVE, REVOKED, or EXPIRED |
deviceLabel / userAgent | Device metadata for session management |
lastSeenAt | Updated on every authenticated request |
expiresAt | Session expiration timestamp |
Protected API endpoints use a protectedProfileProcedure that validates the session token from request headers and injects profileId, sessionId, and db into the handler context.
A single profile can link wallets from multiple chains:
| Wallet Field | Purpose |
|---|---|
walletChain | BTC, ETH, or SOL |
walletAddress | Actual wallet address |
addressHash | Deterministic hash for lookups (prevents duplicates) |
role | PRIMARY (first wallet), ADMIN (elevated), or MEMBER (read-only) |
visibility | PUBLIC (discoverable by address) or PRIVATE (hidden) |
proofSignature / proofMessage / proofScheme | Stored challenge proof for verification |
Each (walletChain, addressHash) pair is unique -- a wallet can only be linked to one profile. Wallets can be unlinked via soft-delete (removedAt timestamp).
Profiles can verify ownership of social accounts across platforms:
| Platform | Verification Flow |
|---|---|
| X (Twitter) | Post challenge text, community votes to verify |
| Post challenge text, community votes | |
| GitHub | Create gist with challenge text |
| YouTube, TikTok, Facebook | Post challenge text |
| Website | Place challenge text at well-known URL |
The flow:
createProfileSocialLink with platform and handleverificationHash challenge text to post publiclyverifyVotes / rejectVotes) to confirm ownershipEach (profileId, platform, normalizedHandle) combination is unique.
For linking new devices to an existing profile:
createDeviceLinkRequest -- generates a one-time requestTokenHashapproveDeviceLinkRequest (requires active session)issuedSessionEncrypted) for the new deviceconsumeDeviceLinkRequestRequests expire and can be rejected. Status flow: PENDING -> APPROVED -> CONSUMED (or REJECTED / EXPIRED).
resolvePublicProfileByAddress: Look up a profile by chain + wallet address (only returns PUBLIC wallets)Each profile has a profileNotificationSettings record with a JSONB settings field for custom notification preferences. Changes are tracked by updatedBySessionId for audit purposes.