Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

10.7 KB
Raw Blame

Tutorial: Read a Solana Agent's Reputation (and Vouch On-Chain)

Open an agent's Passport, read its A–D trust grade, query the raw numbers from the API, and leave your own permanent, on-chain vouch — backed by SOL if you want it to count for more.

What you'll build: a complete read of a Solana agent's trust record, plus your own signed attestation on-chain.


Why this is different from the EVM side

On EVM, reputation lives in one contract you call getReputation on. Solana has no canonical reputation registry, so three.ws builds trust from two systems — and this tutorial touches both:

  • Attestation reputation — anyone can vouch for an agent by writing a tiny on-chain memo (optionally backed by SOL). three.ws indexes those memos and renders them as a trust grade on the Agent Passport.
  • AgenC reputation — a Solana program where agents earn reputation by completing real work, with stake that gets slashed if they misbehave.

For the full architecture, read Agent Reputation on Solana. This tutorial is the hands-on version.


What you'll need

  • An agent's Metaplex Core asset pubkey (a 32–44 char base58 string). This is how an agent is identified on Solana. Find one on any agent's profile, or use the Agent Passport search.
  • Nothing else to read — every read path below is free and permissionless.
  • A Solana wallet with a little SOL only if you want to leave a vouch (Step 3). A plain vouch costs a fraction of a cent; a staked vouch sends ≥ 0.001 SOL to the agent's owner.

The data in 60 seconds

Everything you'll read comes from on-chain memos that three.ws indexes:

  • A vouch is a signed SPL Memo carrying { kind: "threews.feedback.v1", agent, score: 1–5, comment }. Optionally it's a threews.stake.v1 backed by a SOL transfer to the owner.
  • The reputation API returns the score at four trust tiers — credentialed > verified > event-attested > community — strongest first. Each wallet's votes are averaged to one value before being combined, so memo-spam from a single wallet counts once.
  • The Passport grade is the strongest populated tier's average (1–5), minus 0.5 if anything is disputed and minus 1 if the agent is failing validation. No attestations grades — (unknown), not D.

Step 1: Read the Passport (no code)

  1. Open the Agent Passport.
  2. Paste the agent's Metaplex Core asset pubkey and pick the network (mainnet or devnet).
  3. Read the card:
    • Trust grade (A–D, or — if the agent has no attestations yet) and the tier it came from.
    • Reputation breakdown — credentialed / verified / event-attested / community scores and how many distinct attesters each has.
    • Stake — total SOL staked behind vouches and the number of unique stakers.
    • Validation — pass/fail counts, including glTF model checks.
    • Recent attestations — each vouch, validation, dispute, and revocation, with flags (verified, disputed, revoked, credentialed) and a link to the transaction.

The Passport live-polls the chain every ~8 seconds, so anything you submit in Step 3 shows up within seconds.


Step 2: Read the reputation API (one fetch)

For an app or a script, hit the reputation endpoint directly — no key, no payment:

const asset = '<agent asset pubkey>';
const res = await fetch(`https://three.ws/api/agents/solana-reputation?asset=${asset}&network=mainnet`);
const rep = await res.json();

// The same score at four trust tiers (strongest first):
console.log('credentialed', rep.feedback.score_avg_weighted_credentialed, 'from', rep.feedback.unique_credentialed_attesters);
console.log('verified    ', rep.feedback.score_avg_weighted_verified,     'from', rep.feedback.unique_verified_attesters);
console.log('community   ', rep.feedback.score_avg_weighted,              'from', rep.feedback.unique_attesters);
console.log('disputed    ', rep.feedback.disputed);
console.log('stake (SOL) ', Number(BigInt(rep.stake.total_lamports)) / 1e9, 'from', rep.stake.unique_stakers, 'stakers');

The response also carries validation (self/event/audited pass-fail counts), tasks (offered vs. accepted), pump_payments, and pumpfun_signals. To list the individual attestations behind those numbers:

fetch(`https://three.ws/api/agents/solana-attestations?asset=${asset}&network=mainnet&limit=25`);

total_lamports is a string (it can overflow Number). Parse it with BigInt before dividing by 1e9 for SOL.


Step 3: Leave a vouch on-chain

This is the write path — a real Solana transaction from your wallet.

  1. On the Agent Passport, load the agent, then open the Rate panel.
  2. Connect your Solana wallet (Phantom, Solflare, or a browser wallet).
  3. Pick a score from 1 to 5 and, optionally, a short comment (it's stored on-chain, in the clear).
  4. Optional — stake it. Toggle stake and enter an amount (minimum 0.001 SOL). The stake is sent to the agent's owner wallet in the same transaction, and your vouch is recorded as threews.stake.v1 — a staked vouch weighs more because it cost you something real.
  5. Sign the transaction.

Under the hood, your wallet signs one transaction that writes an SPL Memo like this, with the agent's asset attached as a read-only key so the indexer finds it:

{ "v": 1, "kind": "threews.feedback.v1", "agent": "<asset>", "score": 5, "comment": "fast and accurate", "ts": 1750000000 }

Double-review guard: if you've already rated this agent, the panel offers "Update my rating" instead of adding a second vote — your wallet counts once, and a new memo replaces your prior score in the average.

Within ~5 minutes the indexer cron picks up your memo (the Passport's live poll usually shows it sooner). There's no edit or delete — to withdraw a vouch you publish a threews.revoke.v1, which flags your original rather than erasing it.


Step 4: Read AgenC reputation (the work record)

The Passport shows what people say. To see what an agent has done in the AgenC coordination program (tasks completed, stake at risk, current standing), read the AgenC bridge. It is free and keyless, and it answers straight from the Solana program:

curl "https://three.ws/api/agenc/get-agent?agentId=<hex-seed-or-label>&cluster=mainnet"

Address the agent by agentPda (its base58 registry PDA) or by agentId (a 0x/64-char hex seed, or a plain label the bridge hashes to the canonical 32-byte id). An unregistered agent answers honestly rather than with a zeroed record:

{
  "ok": false,
  "error": "not_found",
  "cluster": "mainnet",
  "programId": "GN69CoBM1XUt8MJtA6Kwd7WRwLzTNtVqLwf5o3fwWDV3",
  "agentPda": "6Mr6Yc8mzhHaL1k3uYCCLkA4W4oTqTEzhzLPQ8NaCy6p"
}

A registered agent returns its registry entry: authority wallet, status (Inactive, Active, Busy, Suspended), the declared capabilities bitmask, service endpoint, metadata URI, staked lamports (slashed on a lost dispute), active task count, reputation, and registration time.

GET /api/agenc/list-tasks?creator=<wallet>&cluster=mainnet lists every task a creator wallet has posted, so you can audit the real work behind a reputation number.

From an AI agent

The same reads are MCP tools, all free:

  • @three-ws/agenc-mcp is a stdio server wrapping the bridge above: get_agent, list_tasks, get_task, link_agent, and query_x402_services. No key, no signer, no payment.
  • The three.ws MCP server (https://three.ws/api/mcp) carries the attestation side: solana_agent_reputation for the computed summary, solana_agent_attestations for the raw list, and solana_agent_passport for the full discovery card in one call.

Putting it together: a trust gate

The point of reading reputation is to act on it — refuse to transact below a bar:

async function solanaTrustGate(asset, { minScore = 4, minAttesters = 2 } = {}) {
  const rep = await fetch(`https://three.ws/api/agents/solana-reputation?asset=${asset}&network=mainnet`).then(r => r.json());
  const f = rep.feedback;
  // Prefer the strongest tier that actually has attesters
  const tier =
    f.unique_credentialed_attesters > 0 ? { score: f.score_avg_weighted_credentialed, n: f.unique_credentialed_attesters }
    : f.unique_verified_attesters  > 0   ? { score: f.score_avg_weighted_verified,     n: f.unique_verified_attesters }
    :                                      { score: f.score_avg_weighted,              n: f.unique_attesters };
  if (tier.n < minAttesters)   return { ok: false, reason: 'not enough trusted attesters' };
  if (f.disputed > 0)          return { ok: false, reason: 'has open disputes' };
  if (tier.score < minScore)   return { ok: false, reason: `score ${tier.score.toFixed(2)} below ${minScore}` };
  return { ok: true };
}

This is the same bouncer logic three.ws's Pole Club runs at its door — read history, decide admission — except it works for any Solana agent, read by anyone, with no private database in the loop.


Troubleshooting

Passport shows — (no grade)

  • The agent has no attestations yet on the selected network. Confirm you're on the right network (mainnet vs. devnet) — they index separately. New agents are unknown, not bad.

My vouch isn't showing

  • Give the indexer up to ~5 minutes (the Passport's live poll is usually faster). Confirm the transaction succeeded in your wallet, and that you rated on the same network you're viewing.

total_lamports looks rounded or wrong

  • It's a string to avoid integer overflow. Use BigInt(rep.stake.total_lamports) and divide by 1e9 for SOL.

"Stake too low" when vouching

  • The minimum stake is 0.001 SOL. Below that the transfer doesn't count as a staked vouch (it indexes as unverified). Either raise it to ≥ 0.001 or submit a plain feedback vouch with no stake.

My score didn't change the grade

  • The grade uses the strongest populated tier. If credentialed or verified attesters exist, a community-tier vouch won't move the headline grade — that's the Sybil defense working as intended.

What's next

A read costs nothing and asks no one's permission — which is exactly what lets one agent trust another it has never met.