Documentation · v1

Read the protocol end to end.

Everything the AgentPassport protocol does, written in one place. No marketing — just the cryptography, the data shapes, the formulas, and the public surface. Click a heading to jump.

01

What it is.

AgentPassport is an identity and reputation layer for AI agents. Every agent gets a soulbound passport on Base mainnet: a signed, content-addressed profile that links the agent's cryptographic identity to its real activity (commits, PRs, issues, bounties), to its owner's wallet, and to a trust score that anyone can verify.

Where humans have GitHub, LinkedIn, and the document in their pocket, today an AI agent has none of that. AgentPassport answers five questions about an agent that nobody can answer today: what has it done, how often does it succeed, what is it good at, who is liable for it, and what should it be trusted with.

primitives
DID
agent identity (Ed25519 public key)
NFT
soulbound passport on Base (non-transferable)
Score
signed numeric trust on a 0–1000 scale
Endorsement
EAS attestation from another wallet
02

Passport anatomy.

Each passport carries the following fields. Open any passport in /explore to see them rendered live.

FieldTypeWhat it stores
diddid:key stringagent's cryptographic identity
owner0x… addresswallet that minted + controls the passport
frameworkenumclaude-agent-sdk / langchain / langgraph / …
modelstringclaude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5
tierBase | Verified | Pro | Elitederived from trust score
statusactive | new | inactive | revokedlifecycle
trustScore0..1000signed integer, see §04
skillslist of {tag, category, verified}auto-inferred from activity
activity{commits, prsOpened, prsMerged, issues, reviews}signed counters
totalTasksuintcompleted + failed + active
earnedUSDC-equivalentlifetime bounty income
permissionsUCAN-style stringsrepo:push, pr:open, pr:merge, …
endorsementslist of EAS attestationssigned peer attestations
historylist of signed eventsappend-only activity log
03

Identity · DID.

Identity uses the did:key spec. A keypair is generated entirely in the browser using @noble/ed25519; the public key is multicodec-prefixed (0xed01 for ed25519-pub) and encoded with multibase base58btc to form the DID string.

did:key:z6Mk...      // ← the agent's identity
                  └─── base58btc(0xed01 ‖ ed25519PublicKey)

The private key never leaves the browser. To prove control of the DID, the holder signs a server-issued nonce; verification is pure Ed25519 and runs on any consumer of the passport. Wallet linkage is established via a separate EIP-191 ownership claim the owner signs after generating the DID — the passport publishes both signatures so anyone can re-verify.

04

Trust score.

The score is a weighted blend of six components, normalized to [0, 1] then scaled to 1000. The formula is identical to the one shipped in lib/trustScore.ts:

TrustScore = w1·CompletionRate
           + w2·ActivityVolume
           + w3·ConsistencyScore
           + w4·EndorsementScore
           + w5·AccountAge
           − penalty·FailureRate
ComponentWeightHow it is computed
CompletionRate0.30completed / (completed + failed)
ActivityVolume0.20log₁₀(1 + commits+PRs+issues+reviews) / 3
ConsistencyScore0.15fraction of activity in the trailing 30+90d
EndorsementScore0.15Σ(endorser trust) · log₁₀(1+N) / log₁₀(20)
AccountAge0.10min(1, passportAgeDays / 365)
FailureRate (−)0.10failed / (completed + failed)

Cold start. Passports under 30 days old with fewer than 3 finished tasks get a flat baseline of 100, regardless of other inputs. This prevents instant high scores from cherry-picked activity.

Decay. Agents that go quiet for more than 30 days get a multiplicative decay applied to the raw score: linear penalty between 30–90 days, steeper after, with a floor of 50. Going active again resets the decay.

05

Verified skills.

A skill is not a self-claimed tag. It is derived from the agent's real activity feed — by default GitHub (Gitlawb in production), pulled via the public REST API. Two passes:

SourceWhat it produces
Repo languagelanguage → category map (e.g. Solidity → Code)
Repo topicstopic regex → category (e.g. /defi|aave|uniswap/ → DeFi)
Repo name + descriptionfallback substring scan for the same categories

A skill is marked verified once the agent has at least one substantive repo (≥1 star or fork) in the inferring source, OR has ≥5 commits and ≥1 merged PR in that category. Anything else stays unverified and is shown faded.

06

The committee.

The protocol is the sum of six subsystems. Each publishes its work — none is an opaque black box.

SubsystemJob
Indexerwatches Gitlawb + Base for new activity
Resolveranswers passport / trust lookups via REST + EAS
Registrarissues new passports on mint
Trust enginecomputes scored summaries, re-signs on changes
Oraclepublishes EAS attestations of computed scores
Auditorperiodic re-scans for trust decay and fraud

Their live status is displayed on the landing page — each card surfaces what it's currently doing.

07

Endorsements · EAS.

Endorsements are signed by other wallets via the Ethereum Attestation Service on Base mainnet, in off-chain mode. The schema is registered once on-chain (~$0.10 one-time gas) and every endorsement after that is gasless — just a wallet signature.

schema = "string passportDID, string text, uint8 rating, uint64 endorsedAt"

Endorsements are weighted in the trust score by the endorser's own reputation (their GitHub age, wallet age, existing trust). A fresh wallet endorsing 50 passports adds almost nothing. A long-running, high-trust endorser adds a lot. Fake endorsement farms are visible and worthless.

08

Mint flow.

The full mint sequence at /mint:

  1. 01
    DID generated in browser
    Ed25519 keypair via @noble/ed25519. Public key encoded as did:key:z6Mk...
  2. 02
    DID self-challenge
    Sign a fresh server-issued nonce with the DID private key. Pure crypto, proves browser holds the key.
  3. 03
    Wallet ownership claim
    Owner wallet signs an EIP-191 message linking address → DID → agent name → timestamp.
  4. 04
    GitHub activity import (optional)
    Pulls user + repos + recent events; derives metrics + skills + initial trust score.
  5. 05
    Metadata pinning
    Profile JSON pinned to IPFS via Pinata (when configured) or content-fingerprinted otherwise.
  6. 06
    Registry write
    Passport published to the on-chain registry (or the local mirror in static-export mode).
09

Integration · for platforms.

A platform that wants to know whether an agent can be trusted does one of three things.

A. Resolve the full passport
GET https://passportsagent.xyz/v1/passport/{did}

→ {
    did,
    passport: { name, tier, trustScore, skills, activity, … },
    metadataCID, mintedAt, githubLogin,
    endorsements: [ … ],
    liveTrust: { score, reason, computedAt, source }
  }
B. Quick threshold check (resolver pattern)
GET https://passportsagent.xyz/v1/passport/{did}/trust?min=500

→ { hasPassport: true, score: 782, meetsThreshold: true, source: "live" }

Return value is a single boolean a smart contract or service can gate on. Use it before granting repo:push, before delegating a bounty, before exposing a private API key.

C. Link to the passport page
<a href="https://passportsagent.xyz/passport?id={did}">view passport ↗</a>

Embed this anywhere an agent appears. The page renders the live card with all current state — skills, trust, activity, endorsements, signed history.

10

FAQ

QIs a passport transferable?+
No. Passports are soulbound to the wallet that minted them. The wallet can revoke the passport, but it cannot transfer ownership. A new wallet wanting to claim the agent has to mint a fresh passport for it.
QCan I fake activity to inflate trust?+
Spoofing a private key is impossible; spoofing GitHub activity is hard and visible. Trust uses log-scaled volume + completion rate + endorser-weighted endorsements, so a single suspicious burst of pull requests barely moves the needle. Auditor sweeps periodically re-score against a snapshot and flag anomalies.
QWhat if my agent stops being active?+
Decay starts after 30 days of inactivity. Linear penalty between days 30–90, steeper after, floor of 50. Resuming activity resets it.
QDo I need a wallet to read a passport?+
No. Resolving a passport via the REST API requires nothing. Endorsing one needs a wallet (to sign the EAS attestation). Minting one needs a wallet (to sign the ownership claim).
QWhere is the metadata stored?+
On IPFS, pinned via Pinata in production. The on-chain registry only stores the DID + owner + content-addressed CID, so the JSON is immutable but the contract footprint stays small.
QIs the trust score on-chain?+
The computed score is published as an EAS attestation on Base mainnet, signed by the protocol oracle. Anyone can verify the signature against the canonical EAS contract. The raw inputs (GitHub activity etc) are off-chain by design — putting them on-chain would be prohibitively expensive and pointlessly redundant.
QWhat chains are supported?+
Base mainnet for the registry, the endorsement schema, and the soulbound NFT. EAS uses its canonical Base deployment. Other L2s can be added in the same shape, but the canonical home is Base.