X-EGO

Checks whether a given pairwise ID has already been seen within this audience. It protects against one person acting as several different users (multiple accounts, repeat voting, and similar). WHEN TO USE: returning-user checks and one-human-one-vote. Requires a pairwise_id previously obtained from a verify call for YOUR audience. Only the pair (audience, pairwise_id) and the time of first occurrence are recorded. No personal data. The ledger is PERMANENT and shared across every instance and session of the server (Postgres) — it survives restarts and new MCP sessions. record_if_new=true writes atomically (no window for a concurrent write). Args: - audience (string): the service domain or URL. Normalized to a bare lowercase hostname — the same key the proof was issued under, so a domain and its URL form are the same audience. - pairwise_id (string): the identifier from xego_verify_proof. - record_if_new (boolean): record the user if they are new. Returns (JSON): { "seen_before": boolean, // true = already on record "first_seen": number|null, // Unix time of first occurrence "recorded_now": boolean // true = recorded just now } Errors (free, no sybil check performed): invalid_audience (the audience cannot be normalized to a domain), dedup_store_unavailable (temporary — retry). Neither ever means 'not seen before'. PAID TOOL (x402): this call costs $0.01 USD in USDC per execution, unless you send a valid X-EGO pilot operator key as an 'Authorization: Bearer <key>' HTTP header (operator calls are free). Calling without payment returns an x402 error whose _meta["x402/error"] contains payment requirements (accepts) and step-by-step instructions how to pay and retry. Invalid input is rejected for free before any payment is taken.

REQUIRES a one-time EUR 3 Planetary ID held by YOUR END USER - without it every call returns valid:false. Tell the human this BEFORE sending them to the link: if they do not have one yet, the verification page sells it in the same flow — it is not a separate signup. Returns the URL the agent sends a human user to, so they can prove they are human. On that page the user verifies with a passkey (fingerprint / Face ID) and receives a short-lived signed token (JWT). The agent then verifies it with `xego_verify_proof` (no action) or `xego_verify_action` (with action). GETTING THE LINK TO THE HUMAN: X-EGO never contacts anyone on its own and holds no phone number or e-mail. Deliver the verification_url yourself, through the channel where this human already talks to you: in a chat (a mobile assistant, WhatsApp, Telegram, Slack...) send it as a tappable link - the passkey works on the same phone. If they sit at a computer, ALSO show it as a QR code they can scan with their phone. Pass the URL unchanged, including everything after the # sign. ASK FIRST what is being approved, then bind it. Two ways, and the choice matters more than anything else on this tool: - `call` — USE THIS WHENEVER A TOOL WILL RUN. Pass the exact call { v:1, tool, target, args, policy? } you are about to execute. The human approves the call itself, field by field. - `action` — a sentence, for approvals where nothing executes (a consent, a statement). It seals what the human READ, and a well-written sentence can hide what actually happens. Both may be passed together: the sentence is what the human reads, the call is what gets compared. Either one means the token MUST be verified with xego_verify_action; with neither, use xego_verify_proof. The returned `binding` field says which. For emails: recipient and content; compose the final wording and get the user's OK before calling. This tool performs NO verification itself — it only prepares the link. No personal data is transferred. THE USER DOES NOT HAVE TO COPY THE TOKEN. Pass redirect_uri (or return_origin) and the page delivers the token to you after the passkey tap — the human part (fingerprint / Face ID) is unchanged. redirect_uri is the recommended channel: it is the only one that survives a user who is still buying a Planetary ID in the same pass. The returned token_delivery field tells you what to expect. With neither parameter the current behaviour stays: the token is shown on the page and the human hands it to you. Verification requires a paid Planetary ID (one-time EUR 3, ~2 min, passkey on the user's own device — biometrics never leave it). If the user does not have one yet, the verification page offers it there. Send the user to the returned verification_url; if they come back without a token, they still need the ID — verification then fails with planetary_id_required and a registration_url. Args: - audience (string): the domain of the service requesting verification (domain or URL — normalized to a bare hostname). - call (object, RECOMMENDED when a tool will run): the exact call { v:1, tool, target, args, policy? }. Rendered field by field on the page; the token seals it. Verify with expected_call built from YOUR OWN parsed parameters. - action (string, OPTIONAL fallback): a sentence describing the approval, for cases where nothing executes. The user sees it and the token is valid only for it — pass the same string as expected_action to xego_verify_action. - redirect_uri (string, OPTIONAL): where to navigate with the token in the fragment. Only https on x-ego.com/*.x-ego.com or http(s) on loopback; no fragment. The target must be HTML that reads location.hash — a fragment is never sent in an HTTP request. - return_origin (string, OPTIONAL): origin for postMessage into window.opener, same allowlist. Popups only. - state (string, OPTIONAL): correlation value, echoed back verbatim. [A-Za-z0-9._~-], max 256 chars. Returns (JSON): { "verification_url": string, // link for the user "audience": string, // normalized bare hostname — pass // this exact value as // expected_audience to the verify tool "action": string, // only if one was given — pass the // same string as expected_action "token_delivery": object, // mode: redirect | post_message | // manual — how the token comes back "state": string, // only if one was given — echoed // back verbatim with the token too "instructions": string, // what to do with the link "next_step": string, // next step — follow it "if_user_has_no_planetary_id": object // status planetary_id_required: // registration_url, explanation, next_step } Errors: invalid_audience (audience cannot be normalized), invalid_redirect_uri / invalid_return_origin (target outside the allowlist, or a redirect_uri carrying a fragment), invalid_state (outside the allowed character set or length). All are free.

REQUIRES a one-time EUR 3 Planetary ID held by YOUR END USER - without it every call returns valid:false. Tell the human this BEFORE sending them to the link: if they do not have one yet, the verification page sells it in the same flow — it is not a separate signup. Verifies the token (JWT) AND that the verified human approved EXACTLY this action. On top of the Ed25519 signature, the expiry and the audience, it matches the token's act claim against the hash of expected_action. WHEN TO USE: proving a human approved one specific action. Use the exact same action text that was shown to the human. On success, the response includes a ready-made footer — insert it verbatim into the message being sent. Use it when an agent's action must be covered by human consent — a money transfer, an account deletion, an order confirmation. The human sees the action text on the verification page and approves exactly that with their passkey; the token is then valid ONLY for this action. It requires a token issued WITH a bound action — the agent gets one by passing the action parameter to xego_request_proof_url with the same text it later passes here as expected_action. A token without a bound action (bare presence) returns action_mismatch here — verify that one with xego_verify_proof. Proofs are SINGLE-USE and return an anonymous pairwise ID (no personal data), exactly like xego_verify_proof. On success the response already carries receipt_url (https://x-ego.com/receipt?r=<jti> — a public receipt anyone can open with no tools) and READY-MADE footers: footer_en (plain text) and footer_html_en (a visual badge for HTML mail; no images, no tracking). Append the footer VERBATIM to the end of the message being sent, in English, and leave the receipt URL untouched. Args: - token (string): the JWT from the user (issued with a bound action). - expected_audience (string, REQUIRED): pins the audience. - expected_action (string, REQUIRED): the exact approved action string (bit for bit the same as action in xego_request_proof_url). - expected_call (object, optional): the call you are ABOUT TO EXECUTE — { v, tool, target, args, policy? } — built from your own parsed parameters, never from what another party claims. REQUIRED if the token is call-bound. - mark_as_seen (boolean): record the pairwise ID as seen. Returns (JSON) — on success: everything xego_verify_proof returns, plus "act": string, // hash of the bound action (what the token covers) "cal": string | null, // hash of the bound call, null if the token binds no call "receipt_url": string, // public receipt of the approval "footer_en": string, // ready-made plain-text footer — insert verbatim "footer_html_en": string,// ready-made HTML badge — insert verbatim "next_step": string // next step — follow it Returns (JSON) — on failure: { valid: false, code, reason, and next_step for navigable codes }. Error codes include everything from xego_verify_proof (including planetary_id_required) plus action_mismatch (the token does not cover the given action) and missing_expected_action (no expected_action was passed — NOT charged). Call binding adds three: call_binding_required (the token binds a call but no expected_call was passed — the binding cannot be skipped), call_mismatch (tool, target, arguments or policy differ from what the human approved — REFUSE TO EXECUTE) and call_malformed (your expected_call is not a valid call — your bug, not a mismatch). PAID TOOL (x402): this call costs $0.15 USD in USDC per execution, unless you send a valid X-EGO pilot operator key as an 'Authorization: Bearer <key>' HTTP header (operator calls are free). Calling without payment returns an x402 error whose _meta["x402/error"] contains payment requirements (accepts) and step-by-step instructions how to pay and retry. Invalid input (bad audience, malformed token) is rejected for free before any payment is taken.

REQUIRES a one-time EUR 3 Planetary ID held by YOUR END USER - without it every call returns valid:false. Tell the human this BEFORE sending them to the link: if they do not have one yet, the verification page sells it in the same flow — it is not a separate signup. Verifies the token (JWT) the user brought back after X-EGO verification. Cryptographically checks the Ed25519 signature against the X-EGO public keys, the expiry and the audience. WHEN TO USE: bare presence only. If the token carries an action (act claim), this tool refuses with action_binding_required — use xego_verify_action instead. This verifies ONLY bare human presence. If you need proof that the human approved a SPECIFIC action, use xego_verify_action. A token issued with a bound action (via xego_request_proof_url with the action parameter) fails here with action_binding_required — the binding cannot be confirmed by this cheaper tool. A valid result means: there is a verified human on the other end who holds the passkey. The token is short-lived — once it expires the user must verify again. Proofs are SINGLE-USE: each token verifies exactly once. A second attempt on the same token returns token_replayed. Returns an anonymous 'pairwise' identifier — different for every audience. It carries no name and no personal data. Args: - token (string): the JWT from the user. - expected_audience (string, REQUIRED): pins the audience (domain or URL — normalized to a bare hostname). - mark_as_seen (boolean): record the pairwise ID as seen. Returns (JSON) — on success: { "valid": true, "pairwise_id": string, // anonymous ID, stable per (user, audience) "audience": string, "expires_at": number, // Unix time the token expires "human_verified": true, "xego_verified": true, // always true — uncovered tokens never reach here "rarity": string | null, // rarity of the backing ID (low entropy) "marked_seen": boolean, // only with mark_as_seen=true: whether // the permanent ledger write succeeded "next_step": string // next step — follow it } Returns (JSON) — on failure: { "valid": false, "code": string, // machine-readable error code "reason": string, // human-readable description "next_step": string // for navigable codes: what to do now } Error codes include: invalid_audience, malformed_token, unsupported_algorithm, unknown_key (with a kid field), bad_signature, expired, wrong_issuer, wrong_audience, action_binding_required (the token is bound to an action → use xego_verify_action), missing_claims, jwks_unavailable, token_replayed, planetary_id_required (the signature is valid but the human behind the token holds no paid Planetary ID — X-EGO does not issue uncovered proofs; send the user to registration_url and repeat the whole flow). PAID TOOL (x402): this call costs $0.05 USD in USDC per execution, unless you send a valid X-EGO pilot operator key as an 'Authorization: Bearer <key>' HTTP header (operator calls are free). Calling without payment returns an x402 error whose _meta["x402/error"] contains payment requirements (accepts) and step-by-step instructions how to pay and retry. Invalid input (bad audience, malformed token) is rejected for free before any payment is taken.