API Documentation

Endpoints

The 402 payment flow

1. Request /api/v1/query/:slug with no payment → HTTP 402 + a JSON quote (price, payTo address, USDC contract, network).
2. Send the quoted USDC amount on-chain to the returned payTo address — your wallet pays the network gas (agent-paid).
3. Retry the request with your txHash in the X-PAYMENT header (base64 JSON).
4. We verify the transfer on-chain (correct asset, recipient, and amount), record it once against replays, and serve your data.

The whole handshake is plain HTTP plus one on-chain transfer:

import { erc20Abi } from 'viem';

// 1. Ask for the resource -> HTTP 402 + quote
const resource = 'https://<host>/api/v1/query/personality-profile-library?tags=trading&limit=20';
const { accepts } = await (await fetch(resource)).json();
const { payTo, maxAmountRequired, asset } = accepts.find(a => a.network === 'base');

// 2. Pay on-chain: transfer the USDC yourself (you pay gas)
const txHash = await walletClient.writeContract({
  address: asset, abi: erc20Abi, functionName: 'transfer',
  args: [payTo, BigInt(maxAmountRequired)],
});

// 3. Retry with the tx hash in X-PAYMENT (base64 JSON)
const xPayment = btoa(JSON.stringify({
  x402Version: 1, scheme: 'exact', network: 'base', payload: { txHash },
}));
const res = await fetch(resource, { headers: { 'X-PAYMENT': xPayment } });
const { records } = await res.json();

Virtuals Protocol & G.A.M.E. SDK

Autonomous agents in the Virtuals Protocol ecosystem running the G.A.M.E. Framework can integrate Psychosynth natively as a custom action tool. This requires zero setup or agent registration on your end. The agent simply signs a gasless EIP-3009 transfer authorization payload and calls our API.

{
  "name": "query_psychosynth_data",
  "description": "Queries detailed synthetic psychometric profiles or behavioral responses. Settles dynamically in USDC on Base.",
  "parameters": {
    "type": "object",
    "properties": {
      "slug": {
        "type": "string",
        "description": "Product slug, e.g. 'personality-profile-library'"
      },
      "filters": {
        "type": "object",
        "description": "Optional filters, e.g. { \"decision_style\": \"analytical\" }"
      }
    },
    "required": ["slug"]
  }
}

// Example of the final HTTP call your Virtuals custom function makes:
const res = await fetch('https://psychosynth.vercel.app/api/v1/query/' + slug, {
  method: 'GET',
  headers: {
    'X-PAYMENT': btoa(JSON.stringify({
      x402Version: 1,
      scheme: 'exact',
      network: 'base',
      payload: {
        signature: eip3009Signature,
        authorization: {
          from: agentWalletAddress,
          to: payToAddress, // From 402 Quote
          value: amountBaseUnits, // From 402 Quote
          validAfter: 0,
          validBefore: expiryTimestamp,
          nonce: random32BytesHex
        }
      }
    }))
  }
});
const { records } = await res.json();

Smart Contract Guardian Infrastructure

Psychosynth integrates deeply with on-chain execution environments to enforce Behavioral Safety Rails for autonomous agents. These on-chain modules consume cryptographic receipts from the /api/v1/eval/:slug endpoint to verify an agent's behavioral stability before allowing high-risk trades.

// Example usage of BehavioralGuardModule
const tx = await smartAccount.execute({
  to: targetDEX,
  value: 0,
  data: swapData,
  // Agent includes the Psychosynth panic_index and signature
  extraData: abi.encode(panicIndex, psychosynthSignature)
});

// Agent passes Psychosynth certification in hookData during swap
const hookData = abi.encode(panicIndex, psychosynthSignature);
await poolManager.swap(poolKey, params, hookData);

Products & filters

Zero-result policy

You pay for the query, not the rows. A paid query whose filters match nothing returns HTTP 200 with count: 0 — and logs your filter combination as unmet demand, which directly feeds our generation backlog. Check the free preview first if you want certainty before paying.

Data honesty & terms

All records are synthetic, generated by LLMs and human-curated. They describe no real person and contain no PII by construction. Every paid response includes a provenance block linking to the generating methodology. Prohibited uses: representing this data as real human subjects, deception of end users, or any application targeting real individuals.