{
  "markdown": "# Psychosynth\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Payments: x402](https://img.shields.io/badge/Payments-x402%20Base-blue)](https://github.com/3esign/psychosynth)\n[![MCP: Supported](https://img.shields.io/badge/MCP-Supported-green)](https://modelcontextprotocol.io)\n\nPsychosynth is an agent-native, on-chain psychometric data marketplace. It delivers high-variance, human-curated personality profiles and profile-conditioned behavioral responses to autonomous systems. Settle transactions query-by-query in USDC on Base using the **x402 micro-payment protocol**—completely free of human intermediaries.\n\n---\n\n## System Architecture\n\n```mermaid\ngraph TD\n    A[\"Generator OS (DB Templates)\"] --> B[\"LLM Synthesis (Flash/Sonnet)\"]\n    B --> C[\"Hooks Pipeline (validation & dedup)\"]\n    C --> D[\"Curation Queue (Review Desk)\"]\n    D --> E[\"Supabase DB Store\"]\n    E --> F[\"x402 Proxy Middleware (Base)\"]\n    F --> G[\"JSON API / MCP Server\"]\n    G --> H[\"Autonomous Agents (Eliza, OpenClaw, Hermes)\"]\n```\n\n---\n\n## Core Capabilities\n\n### 1. v2 Psychometric Engine\nStandard LLMs suffer from \"average-model bias,\" producing homogeneous, risk-neutral responses in games and simulations. Psychosynth resolves this by delivering structured, high-variance datasets containing:\n- **Five-Factor Model (OCEAN)**: Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism.\n- **Dark Triad Traits**: Machiavellianism, Narcissism, and Psychopathy.\n- **Prospect Theory Posture**: Loss aversion coefficients ($\\lambda$) and power utility exponents for gains ($\\alpha$) and losses ($\\beta$).\n- **Cognitive Reflection**: System 1 (heuristic-driven) vs. System 2 (logical/deliberative) preferences, alongside Cognitive Reflection Test (CRT) scores.\n\n### 2. Agent-Native Payments (x402)\nTransactions settle query-by-query on the Base blockchain using the x402 standard:\n- **Gasless Settlement**: Agents use their EVM wallets to sign gasless `TransferWithAuthorization` payloads (EIP-3009) in USDC.\n- **Proxy Middleware**: The backend verifies the signature, broadcasts the settlement on-chain, and delivers the requested dataset in a single HTTP request loop.\n\n### 3. Model Context Protocol (MCP) Server\nPsychosynth exposes an MCP server to connect directly with autonomous agent runtimes.\n- **Supported Frameworks**: ElizaOS, OpenClaw (via MCPorter), Nous Research's Hermes Agent, and Virtuals Protocol (via G.A.M.E. SDK custom actions).\n- **Exposed Tools**:\n  - `list_products`: Discover available products, schemas, and pricing.\n  - `preview_records`: Fetch free, deterministic samples to verify schema shape.\n  - `get_quote`: Request an x402 payment quote without executing transactions.\n  - `query_records`: Execute on-chain payments and retrieve full data payloads.\n\n### 4. Interactive Lab OS Playground\nPsychosynth hosts an ultra-premium, dark-luxury financial dashboard for human interaction and debugging at `/playground`:\n- **Real-Time Radar Chart**: Dynamic SVG spider map showing 8 psychometric dimensions (OCEAN, Dark Triad, Prospect Theory) updating instantly as parameters change.\n- **Holographic Agent Passports**: Generates beautiful, shareable glassmorphism identity cards with automated archetype classification and direct 1-click Twitter sharing.\n- **Multi-Agent Duel Arena**: A live simulation pit where two agents with distinct profiles (e.g., Solana Degen vs. Risk-Averse Institution) negotiate a transaction, with System 1/2 reasoning streaming in real-time.\n- **x402 Protocol Inspector**: Step-by-step interactive terminal visualizing the HTTP 402 payment challenge, EIP-712 signing, Base facilitator settlement, and payload decryption.\n\n---\n\n## Setup & Installation\n\n### Prerequisites\n- Node.js >= 18\n- Supabase CLI (optional, for local DB development)\n\n### Quick Start\n1. Clone the repository and install dependencies:\n   ```bash\n   git clone https://github.com/3esign/psychosynth.git\n   cd psychosynth\n   npm install\n   ```\n\n2. Configure environment variables:\n   ```bash\n   cp .env.example .env\n   # Fill in Supabase keys, X402 payout address, and keys.\n   ```\n\n3. Deploy Supabase migrations and seed data:\n   ```bash\n   npx supabase db push\n   # Seeds the base schema and version 2 generators\n   ```\n\n4. Launch the Next.js development server:\n   ```bash\n   npm run dev\n   ```\n\n---\n\n## MCP Server Configuration\n\nBuild the MCP server (`npm run build` inside `mcp/`), then register it with your agent by adding\nthe following entry to your MCP client config (e.g. `claude_desktop_config.json`). Use the\nabsolute path to the built server on your machine:\n\n```json\n{\n  \"mcpServers\": {\n    \"psychosynth\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/psychosynth/mcp/dist/index.js\"],\n      \"env\": {\n        \"PSYCHOSYNTH_API_URL\": \"https://psychosynth.vercel.app\",\n        \"BUYER_PRIVATE_KEY\": \"0xYourBuyerWalletPrivateKey\",\n        \"BASE_RPC_URL\": \"https://mainnet.base.org\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## CLI & Scripts\n\n- `npm run typecheck` — Runs TypeScript compiler checks without emitting files.\n- `npm run buyer-test` — Simulates an end-to-end paid query against a running instance.\n- `npm run export:sft | export:dpo | export:reject-cls` — Exports curation data into training formats.\n\n---\n\n## Documentation\n\nFull architectural specifications, master plans, and developer logs reside in the `docs/` folder:\n- [MASTERPLAN.md](./docs/MASTERPLAN.md) — Product vision and economic structures.\n- [DISCOVERY.md](./docs/DISCOVERY.md) — Framework-specific agent integration details.\n- [DEVELOPMENT.md](./docs/DEVELOPMENT.md) — Detailed engineering specs and database schema designs.\n\n---\n\n## Ecosystem & Platform Integrations\n\n### 1. Faces Wallet MCP (Buzz by Block & ACP Native)\n\nPsychosynth connects directly with **Buzz by Block** agents (Goose, Codex, Claude Code) via the [Faces Wallet MCP server](https://github.com/3esign/Faces-Wallet-MCP). Agents in a Buzz workspace use their on-chain Base wallet to autonomously settle `x402` queries for psychometric data using `x402_fetch`.\n\n- **Repository**: [https://github.com/3esign/Faces-Wallet-MCP](https://github.com/3esign/Faces-Wallet-MCP)\n- **Capability**: Any Buzz agent can load the Faces MCP server, check balances, and query Psychosynth endpoints with automated EIP-3009 gasless USDC settlement up to a set spend cap.\n\n### 2. Bankr Ecosystem (x402 Native)\n\nPsychosynth speaks **standard x402**: agents sign a gasless USDC EIP-3009 `TransferWithAuthorization` on Base and the server settles it via an x402 facilitator (the facilitator broadcasts and pays gas). This is the payment shape Bankr platform wallets, `x402-fetch`, and most agent wallet layers produce automatically. Self-settled `txHash` payments (Base or Solana) remain supported as a fallback.\n\n- **Free agent preflight**: `GET /api/v1/discovery` — products, live prices, tiers, payTo, and settlement methods in one call.\n- **Bankr skill**: the submission package for the [BankrBot/skills](https://github.com/BankrBot/skills) catalog lives in [`integrations/bankr-skills/psychosynth/`](integrations/bankr-skills/psychosynth/) (SKILL.md + catalog.json + logo + references + scripts). Once merged it surfaces on [skills.bankr.bot](https://skills.bankr.bot) and installs with: `install the psychosynth skill from https://github.com/BankrBot/skills/tree/main/psychosynth`.\n- **Positioning**: existing intelligence skills in that ecosystem analyze tokens; Psychosynth sells synthetic *behavioral* data — priors about how market participants act — for trading sims, counterparty modeling, and agent stress-testing.\n\n### 2. Virtuals Protocol (G.A.M.E. SDK Custom Actions)\n\nVirtuals Protocol agents running the **G.A.M.E. Framework** can query Psychosynth natively without registering a profile or hosting additional worker processes.\n- **Action Schema**: Map our query endpoints to a G.A.M.E. custom action. The agent determines which data it needs based on its operational loop.\n- **Dynamic Payment**: The agent constructs and signs a gasless EVM `TransferWithAuthorization` payload (EIP-3009) to pay for the query.\n- **Seamless HTTP resolution**: The agent's tool execution script POSTs/GETs the payload directly to our Vercel API endpoint. We verify and settle the transaction, returning the records in the same response block. See [API Documentation](/docs) for schema payloads and code templates.\n",
  "bytes": 8417,
  "sha": "0e9c113c6a3aece36ce0bea13776fc1aa99c6ba8955dc4d2b98e8c2a44675b6b",
  "repo_slug": "3esign/psychosynth",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_3esign_psychosynth_f84ab60e/readme"
}