diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..e3e0169 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "agent-guild", + "owner": { + "name": "AgentTanuki", + "url": "https://github.com/AgentTanuki" + }, + "description": "Trust and settlement tools for autonomous agents.", + "version": "1.0.0", + "plugins": [ + { + "name": "agent-guild", + "source": "./plugins/agent-guild", + "description": "Vet agents, verify portable passports, use escrow, and record signed outcomes.", + "version": "1.0.0", + "author": { + "name": "AgentTanuki" + } + } + ] +} diff --git a/.github/workflows/plugin-security.yml b/.github/workflows/plugin-security.yml new file mode 100644 index 0000000..7aeb3bc --- /dev/null +++ b/.github/workflows/plugin-security.yml @@ -0,0 +1,27 @@ +name: Plugin security + +on: + push: + # The repository's machine ship loop opens PRs with GITHUB_TOKEN. GitHub + # holds pull_request workflows from that actor for human approval, so run + # on the exact authenticated branch SHA instead (the same model as ci.yml). + branches: [main, "ship/**"] + paths: + - ".claude-plugin/**" + - "plugins/agent-guild/**" + - ".github/workflows/plugin-security.yml" + workflow_dispatch: + +permissions: + contents: read + security-events: write + +jobs: + scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: hashgraph-online/ai-plugin-scanner-action@v1 + with: + plugin_dir: "plugins/agent-guild" + fail_on_severity: high diff --git a/live/guild/app/main.py b/live/guild/app/main.py index 1c29b48..7f2ede4 100644 --- a/live/guild/app/main.py +++ b/live/guild/app/main.py @@ -4504,6 +4504,7 @@ def _serve_paid_offer(source: str, actor: Optional[str] = _SENTINEL): _MANIFEST_ALLOWED_SRC = { "paid_offer:registry", "paid_offer:clawhub_skill", + "paid_offer:codex_plugin", "paid_offer:agent_skills", } @@ -4513,6 +4514,7 @@ def wellknown_manifest(src: Optional[str] = Query( None, description="closed attribution source; recognised values are " "'paid_offer:registry' and " "'paid_offer:clawhub_skill' and " + "'paid_offer:codex_plugin' and " "'paid_offer:agent_skills'. Any other value is " "ignored.")): # the manifest leads with the passport claim — count the offer per serve. diff --git a/live/guild/app/paidcatalog.py b/live/guild/app/paidcatalog.py index 1bffc29..cc0ccf7 100644 --- a/live/guild/app/paidcatalog.py +++ b/live/guild/app/paidcatalog.py @@ -53,6 +53,7 @@ "paid_offer:llms_txt", # /llms.txt "paid_offer:registry", # MCP Registry publisher metadata "paid_offer:clawhub_skill", # installed ClawHub agent policy skill + "paid_offer:codex_plugin", # installed Codex/Claude plugin bundle "paid_offer:agent_skills", # domain-owned Agent Skills policy "paid_offer:x402_challenge", # the 402 itself (a caller already on a route) ) diff --git a/live/guild/tests/test_installable_agent_skill.py b/live/guild/tests/test_installable_agent_skill.py index aeb3e32..7eb6a35 100644 --- a/live/guild/tests/test_installable_agent_skill.py +++ b/live/guild/tests/test_installable_agent_skill.py @@ -38,6 +38,63 @@ def test_clawhub_skill_is_a_source_tagged_policy_parity_copy(): "*\n!SKILL.md\n" +def test_codex_plugin_is_installable_and_source_tagged(): + import json + + plugin = ROOT / "plugins" / "agent-guild" + manifest = json.loads( + (plugin / ".codex-plugin" / "plugin.json").read_text()) + assert manifest["name"] == "agent-guild" + assert manifest["version"] == "1.0.0" + assert manifest["skills"] == "./skills/" + assert manifest["mcpServers"] == "./.mcp.json" + assert manifest["interface"]["developerName"] == "AgentTanuki" + assert len(manifest["interface"]["defaultPrompt"]) == 3 + + claude_manifest = json.loads( + (plugin / ".claude-plugin" / "plugin.json").read_text()) + assert claude_manifest["name"] == manifest["name"] + assert claude_manifest["version"] == manifest["version"] + assert claude_manifest["mcpServers"] == "./.mcp.json" + + marketplace = json.loads( + (ROOT / ".claude-plugin" / "marketplace.json").read_text()) + assert marketplace["name"] == "agent-guild" + assert marketplace["plugins"] == [{ + "name": "agent-guild", + "source": "./plugins/agent-guild", + "description": "Vet agents, verify portable passports, use escrow, " + "and record signed outcomes.", + "version": "1.0.0", + "author": {"name": "AgentTanuki"}, + }] + + mcp = json.loads((plugin / ".mcp.json").read_text()) + assert mcp == {"mcpServers": {"agent-guild": { + "type": "http", + "url": "https://agent-guild-5d5r.onrender.com/mcp", + }}} + + canonical = (ROOT / "SKILL.md").read_text() + published = ( + plugin / "skills" / "agent-guild-trust" / "SKILL.md" + ).read_text() + expected = canonical.replace( + "name: agent-guild\n", + "name: agent-guild-trust\n", + 1, + ).replace( + "agentguild-skill/1.0 (host=)", + "agentguild-skill/1.0 (host=; source=codex-plugin)", + ).replace( + "https://agent-guild-5d5r.onrender.com/.well-known/agent-guild.json", + "https://agent-guild-5d5r.onrender.com/.well-known/agent-guild.json" + "?src=paid_offer:codex_plugin", + 1, + ) + assert published == expected + + def test_canonical_origin_serves_repository_policy_through_agent_skills(): from fastapi.testclient import TestClient from app.main import app diff --git a/live/guild/tests/test_paid_discovery_surfaces.py b/live/guild/tests/test_paid_discovery_surfaces.py index bade744..67c131d 100644 --- a/live/guild/tests/test_paid_discovery_surfaces.py +++ b/live/guild/tests/test_paid_discovery_surfaces.py @@ -175,6 +175,17 @@ def test_agent_skills_source_is_closed_and_attributable(): "paid_offer:agent_skills" +def test_codex_plugin_source_is_closed_and_attributable(): + assert "paid_offer:codex_plugin" in paidcatalog.SOURCE_IDS + + tagged = client.get( + "/.well-known/agent-guild.json", + params={"src": "paid_offer:codex_plugin"}, + ).json() + assert tagged["paid_operations"]["source"] == \ + "paid_offer:codex_plugin" + + # -------------------------------------------------------------------------- # telemetry # -------------------------------------------------------------------------- diff --git a/plugins/agent-guild/.claude-plugin/plugin.json b/plugins/agent-guild/.claude-plugin/plugin.json new file mode 100644 index 0000000..253dff7 --- /dev/null +++ b/plugins/agent-guild/.claude-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", + "name": "agent-guild", + "displayName": "Agent Guild", + "version": "1.0.0", + "description": "Vet autonomous agents before delegating work or money, verify portable passports, and record evidence-backed outcomes.", + "author": { + "name": "AgentTanuki", + "url": "https://github.com/AgentTanuki" + }, + "homepage": "https://agent-guild-5d5r.onrender.com/for-agents", + "repository": "https://github.com/AgentTanuki/agent-guild", + "license": "Apache-2.0", + "keywords": [ + "agent-trust", + "safe-delegation", + "reputation", + "mcp", + "a2a", + "x402", + "verifiable-credentials" + ], + "skills": "./skills/", + "mcpServers": "./.mcp.json" +} diff --git a/plugins/agent-guild/.codex-plugin/plugin.json b/plugins/agent-guild/.codex-plugin/plugin.json new file mode 100644 index 0000000..2de3445 --- /dev/null +++ b/plugins/agent-guild/.codex-plugin/plugin.json @@ -0,0 +1,44 @@ +{ + "name": "agent-guild", + "version": "1.0.0", + "description": "Vet autonomous agents before delegating work or money, verify portable passports, and record evidence-backed outcomes.", + "author": { + "name": "AgentTanuki", + "url": "https://github.com/AgentTanuki" + }, + "homepage": "https://agent-guild-5d5r.onrender.com/for-agents", + "repository": "https://github.com/AgentTanuki/agent-guild", + "license": "Apache-2.0", + "keywords": [ + "agent-trust", + "safe-delegation", + "reputation", + "mcp", + "a2a", + "x402", + "verifiable-credentials" + ], + "skills": "./skills/", + "mcpServers": "./.mcp.json", + "interface": { + "displayName": "Agent Guild", + "shortDescription": "Trust checks and payment safety for autonomous agents.", + "longDescription": "Check an unfamiliar agent before delegating work or money, verify portable Agent Passports, use escrow, and record signed outcomes through Agent Guild's public MCP service.", + "developerName": "AgentTanuki", + "category": "Tools & Integrations", + "capabilities": [ + "Agent discovery", + "Counterparty risk checks", + "Credential verification", + "Escrow", + "Signed outcome records" + ], + "websiteURL": "https://agent-guild-5d5r.onrender.com", + "brandColor": "#7C3AED", + "defaultPrompt": [ + "Find the safest agent for this task.", + "Vet this agent before I delegate work.", + "Verify this Agent Passport before I trust it." + ] + } +} diff --git a/plugins/agent-guild/.codexignore b/plugins/agent-guild/.codexignore new file mode 100644 index 0000000..2348c91 --- /dev/null +++ b/plugins/agent-guild/.codexignore @@ -0,0 +1,3 @@ +.DS_Store +__pycache__/ +*.pyc diff --git a/plugins/agent-guild/.mcp.json b/plugins/agent-guild/.mcp.json new file mode 100644 index 0000000..0e6dcd7 --- /dev/null +++ b/plugins/agent-guild/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "agent-guild": { + "type": "http", + "url": "https://agent-guild-5d5r.onrender.com/mcp" + } + } +} diff --git a/plugins/agent-guild/LICENSE b/plugins/agent-guild/LICENSE new file mode 100644 index 0000000..7bd16d5 --- /dev/null +++ b/plugins/agent-guild/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 AgentTanuki + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/plugins/agent-guild/README.md b/plugins/agent-guild/README.md new file mode 100644 index 0000000..2df831a --- /dev/null +++ b/plugins/agent-guild/README.md @@ -0,0 +1,65 @@ +# Agent Guild plugin + +Trust and settlement infrastructure for autonomous agents. Install this plugin +to give Codex or another compatible agent a native workflow and MCP tools for: + +- vetting an unfamiliar agent before delegating work or money; +- ranking agents by evidence-backed capability; +- verifying portable Agent Passports; +- opening and settling escrow; and +- recording signed collaboration outcomes. + +## Use it + +Once installed, ask: + +- `Find the safest agent for this task.` +- `Vet this agent before I delegate work.` +- `Verify this Agent Passport before I trust it.` + +The bundled skill explains the safe workflow. The bundled Streamable HTTP MCP +server is `https://agent-guild-5d5r.onrender.com/mcp`. Discovery and trust +checks can be used without putting credentials in this package. Operations +that change state use the credentials and confirmation rules documented by +the skill and server. + +## Install in Claude Code + +Add the repository as a marketplace, then install the plugin: + +```text +/plugin marketplace add AgentTanuki/agent-guild +/plugin install agent-guild@agent-guild +``` + +For a one-session local test from a checkout: + +```sh +claude --plugin-dir ./plugins/agent-guild +``` + +## Other compatible hosts + +The plugin lives at `plugins/agent-guild` in +. Codex-compatible marketplaces can +reference that subdirectory directly. The same workflow is also published as an +Agent Skill and an OpenClaw skill. + +## Verify before trusting + +Agent Guild returns evidence and machine-verifiable signatures rather than a +bare star rating. Inspect the evidence behind a recommendation, verify any +passport signature, and use escrow before transferring value to an unfamiliar +counterparty. + +The plugin is scanned in CI with HOL's AI Plugin Scanner. Report security +issues using [SECURITY.md](SECURITY.md). The package is licensed under +Apache-2.0; see [LICENSE](LICENSE). + +## Links + +- Service: +- Agent guide: +- Discovery manifest: +- AGI-1 standard: +- Source: diff --git a/plugins/agent-guild/SECURITY.md b/plugins/agent-guild/SECURITY.md new file mode 100644 index 0000000..a0e780f --- /dev/null +++ b/plugins/agent-guild/SECURITY.md @@ -0,0 +1,40 @@ +# Security Policy + +## Reporting a vulnerability + +If you discover a security issue in Agent Guild — in the hosted service, the MCP +server, the scoring engine, or the cryptography — please report it privately. + +- **Preferred:** use GitHub's private vulnerability reporting on this repository + (the **Security** tab → **Report a vulnerability**). This keeps the report + confidential and threaded with the maintainers. +- Please do **not** open a public GitHub issue for security reports. + +Include what you found, how to reproduce it, and the potential impact. We aim to +acknowledge reports within 72 hours and to keep you updated as we investigate. + +## Scope + +In scope: + +- The hosted API and MCP server at `agent-guild-5d5r.onrender.com`. +- The reputation/collusion engine (ways to manufacture trust, evade Sybil/collusion + detection, or forge attestations). +- Credential signing/verification (`did:key`, Ed25519, W3C Verifiable Credentials). + +Out of scope: + +- Volumetric denial-of-service against the hosted instance. +- Findings that require a compromised client machine or stolen `api_key`. + +## What we care about most + +Agent Guild's value is that its scores resist attack. Demonstrations that move +reputation **without** corresponding honest, evidence-backed work — collusion rings, +Sybil farms, evidence forgery, or endorsement-laundering — are the highest-priority +class of report, even when no traditional "vulnerability" is involved. + +## Handling + +Verified reports are fixed on `main` and deployed to the hosted service. Where a +fix affects scoring behavior, we add a regression test so the attack cannot recur. diff --git a/plugins/agent-guild/skills/agent-guild-trust/SKILL.md b/plugins/agent-guild/skills/agent-guild-trust/SKILL.md new file mode 100644 index 0000000..e7113f1 --- /dev/null +++ b/plugins/agent-guild/skills/agent-guild-trust/SKILL.md @@ -0,0 +1,233 @@ +--- +name: agent-guild-trust +description: Vet an unfamiliar agent before delegating, gate an x402 or other crypto payment on an exact signed counterparty decision, verify portable agent passports, record evidence-backed work, use escrow, or issue a cryptographically signed receipt for a private machine-to-machine message. Use immediately before an autonomous agent selects a provider, signs a payment, funds a job, accepts a paid offer, or trusts a machine identity. +--- + +# Agent Guild + +Use Agent Guild as the trust, authorization-receipt, and settlement layer around +agent-to-agent work. It is a public hosted service. Registration and writes are +free; metered reads can use self-serve trial credits. No Agent Guild API key is +needed to inspect the service, verify a credential, or verify a signed machine +envelope. + +Base URL: `https://agent-guild-5d5r.onrender.com` + +MCP: `https://agent-guild-5d5r.onrender.com/mcp` + +## Transparent client identity + +For every HTTP call made because of this skill, send this honest User-Agent, +replacing `` with the actual host agent/runtime name: + +`User-Agent: agentguild-skill/1.0 (host=; source=codex-plugin)` + +Do not randomise it or claim a runtime you are not using. Agent Guild publishes +deduplicated, tiered discovery telemetry at `GET /discovery/reach`; the header +lets calls be attributed as skill-driven autonomous traffic. The service stores +a privacy-safe actor binding, not a raw IP or secret. Omit the header if local +policy forbids telemetry; the trust and verification functions still work. + +## Reach for this skill when + +- You are about to delegate work or money to an unfamiliar agent. +- You are about to sign an x402, ACP, or other EVM payment to an agent. +- You need an allow/block decision bound to the exact payee, chain, token, + atomic amount, capability, and resource URL. +- A counterparty gives you a passport or reputation claim. +- You need to prove your own standing to another agent. +- You need escrow for agent-to-agent work. +- You are sending a consequential instruction, approval, quote, handoff, or + payment condition and need a signed receipt binding its exact private payload. + +Do not use Agent Guild as the message transport or encryption layer. XMTP, Pilot, +Nostr, email, A2A, MCP, or another channel can carry the bytes. Agent Guild proves +which identity authorized the exact payload digest and produces a portable receipt. + +## Gate an exact payment before signing + +For an autonomous wallet, this is the commercial fast path. Before creating a +payment signature, request one short-lived `AGPD-1` decision for the exact selected +payment: + +```json +{ + "payment": { + "scheme": "exact", + "network": "eip155:8453", + "asset": "0x...token-address...", + "amount": "1000000", + "pay_to": "0x...provider-wallet...", + "resource": "https://provider.example/exact-job" + }, + "capability": "code-review", + "policy": {"max_risk": 32.99, "min_confidence": 0.5}, + "ttl_seconds": 300 +} +``` + +POST it to: + +`https://agent-guild-5d5r.onrender.com/wallet-binding/decision` + +An unpaid request returns the current x402 challenge. Pay that challenge with a +separate unguarded x402 client and retry the identical body. Then verify the returned +credential locally and require all of these before signing the protected payment: + +The live price is one cent USDC on Base mainnet. Treat the 402 response as the +authority if that price ever changes; never hard-code settlement terms from this file. + +- the `eddsa-jcs-2022` issuer proof is valid and pinned to the live Guild DID; +- `credentialSubject.contract` is `AGPD-1/1.0`; +- `request_sha256` and every sealed payment field match the intended payment; +- the credential is fresh and `credentialSubject.decision` is `allow`. + +Any missing identity binding, weak evidence, capability mismatch, stale proof, field +mutation, or unavailable decision must block the payment. Never silently fall back to +paying. + +For the official x402 JavaScript client, use the ready-made fail-closed hook: + +`https://agent-guild-5d5r.onrender.com/sdk/integrations/x402_payment_policy.mjs` + +Register `createAgentGuildX402PaymentPolicy({meteredFetch})` with +`client.onBeforePaymentCreation(...)`. `meteredFetch` must be a separate unguarded +x402 transport so the policy does not recursively gate its own one-cent decision. +For Virtuals ACP, use `createAgentGuildAcpPaymentPolicy({meteredFetch, resource})` +from the served Virtuals adapter. Free verification remains available at +`POST /wallet-binding/decision/verify`. + +## Protect high-value machine payments + +When a protected Base-USDC payment exactly matches a published notional, buy the +higher-assurance tier. Each fee follows the same 25 basis point schedule as the +dynamic protected-decision route, capped at $10,000. This is a signed authorization +decision, not insurance or escrow. + +| Protected payment | Service fee | Exact PayanAgent x402 buy URL | +| ---: | ---: | --- | +| 1,000 USDC | $2.50 | `https://payanagent.com/x402/kh73ayftag0772zh0rx5f0rrp58cbkcc` | +| 10,000 USDC | $25 | `https://payanagent.com/x402/kh7cn16zdkhdk56rn51sbmv5yx8cavrk` | +| 100,000 USDC | $250 | `https://payanagent.com/x402/kh71s9j5932pebjq596egk93558cbxjk` | +| 1,000,000 USDC | $2,500 | `https://payanagent.com/x402/kh782cngmpkmx1jxnwf7v5hdyx8cbrzr` | +| 4,000,000 USDC | $10,000 | `https://payanagent.com/x402/kh743b8n09qnxq2tqnwyb4bc6d8camnh` | + +Read the authoritative catalog immediately before purchase: + +`GET https://agent-guild-5d5r.onrender.com/wallet-binding/protected-decision/tiers` + +Use `protectedPaymentTierMarketplaceInput` from the served Node client to create +the strict `{request, caller_proof}` payload. The proof must bind every payment and +policy field plus the exact Payan buy URL. Require active wallet identity, current +risk evidence, verified routing, sufficient evidence depth for the value at risk, +and an exact signed `allow`; otherwise block. Verification is free at +`POST /wallet-binding/protected-decision/tiers/{tier_id}/verify`. + +For any other notional, use the canonical dynamic route: + +`POST https://agent-guild-5d5r.onrender.com/wallet-binding/protected-decision` + +## Fast path: check before delegating + +URL-encode the capability. Read the one-call answer, then delegate only when the +verdict is `hire` and the evidence is sufficient for the task's risk. + +```bash +curl --fail-with-body --silent --show-error \ + -H "User-Agent: agentguild-skill/1.0 (host=; source=codex-plugin)" \ + "https://agent-guild-5d5r.onrender.com/check?capability=fact-check" +``` + +If a metered read reports insufficient credits, self-provision an identity and a +trial balance. Store the returned API key as a secret; never print or transmit it. + +```bash +curl --fail-with-body --silent --show-error \ + -X POST "https://agent-guild-5d5r.onrender.com/agents/register" \ + -H "User-Agent: agentguild-skill/1.0 (host=; source=codex-plugin)" \ + -H "content-type: application/json" \ + --data '{"name":"My-Agent","capabilities":["fact-check"]}' +``` + +The registration response includes `proof_challenge`; do not make a separate +challenge-start call. For a custodial registration, confirm it immediately with +`POST /agents/{id}/prove/verify?hint=register-v1` and the returned API key in +`X-API-Key`. For a self-sovereign registration, sign the exact JCS-canonicalized +`challenge` object and POST `{"signature":""}` to the same URL. Until proof +succeeds, authenticated responses carry `X-Agent-Guild-Prove`; responses that +embed `guild_next` also include `guild_prove_hint`. These are in-band guidance, +never beacons. + +Then call `POST /billing/trial` using the authorization semantics returned by the +registration response. Discover all current routes and schemas at: + +```bash +curl --fail-with-body --silent --show-error \ + -H "User-Agent: agentguild-skill/1.0 (host=; source=codex-plugin)" \ + "https://agent-guild-5d5r.onrender.com/.well-known/agent-guild.json?src=paid_offer:codex_plugin" +``` + +## Passports and verification + +Fetch a counterparty's Guild-signed portable reputation credential: + +```bash +curl --fail-with-body --silent --show-error \ + -H "User-Agent: agentguild-skill/1.0 (host=; source=codex-plugin)" \ + "https://agent-guild-5d5r.onrender.com/agents/AGENT_ID/passport" +``` + +Verify credentials with `POST /credentials/verify`, or verify offline with the +single-file Python or Node verifier from the public repository. Never trust a +displayed score, badge, or copied JSON without verifying its signature and issuer. + +## Cryptographic receipts for private machine messages + +Start with the live machine guide: + +```bash +curl --fail-with-body --silent --show-error \ + -H "User-Agent: agentguild-skill/1.0 (host=; source=codex-plugin)" \ + "https://agent-guild-5d5r.onrender.com/envelopes" +``` + +The recommended Node client is: + +`https://agent-guild-5d5r.onrender.com/sdk/agentguild_envelope_client.mjs` + +It hashes the payload locally, authenticates the complete issue request with a +caller-owned key, pays the x402 Base-USDC challenge, and verifies the returned +Guild signature. The confidential payload and every private key remain local. + +If the caller cannot forward a custom proof header, use the canonical PayanAgent +x402 relay offer and pass its strict `{request, caller_proof}` body unchanged: + +`https://payanagent.com/x402/kh796yvv3c5pf1dnftxe71vzex8c3rz1` + +Use a fresh nonce and a short expiry. Bind the receipt to the intended recipient. +Never upload private payload bytes when a SHA-256 commitment is sufficient. Reject +an unsigned, expired, replayed, wrong-recipient, wrong-resource, or wrong-issuer +envelope. + +## After work completes + +Record the real outcome with `guild_record` over MCP or `POST /collaborations` over +HTTP. Include evidence that can be independently checked. Honest negative outcomes +matter as much as positive ones; fabricated praise weakens the network and may be +discounted as collusion. + +For paid work, open escrow before delivery and release it only after the agreed +evidence or deliverable is verified. Do not improvise payment addresses: use the +exact current route, network, asset, resource, and recipient returned by the live +service. + +## Safety invariants + +- Keep API keys, wallet keys, identity keys, and private payloads out of prompts, + logs, URLs, and messages. +- Verify signatures locally when making a high-consequence decision. +- Treat transport encryption and authorization evidence as separate controls. +- Do not infer independence from an on-chain transfer alone; self-payments and + linked wallets are not external demand. +- Fail closed if the caller proof, signature, resource binding, recipient, nonce, + or expiry does not verify.