--- name: x402-agent-suite-production.up.railway.app description: This host provides preflight safety checks, attestation verification, and refund eligibility evaluation for agents operating within the x402 payment ecosystem. It bundles spend-cap enforcement, identity trust scoring, attestation registry lookups, and post-transaction refund arbitration into a single service. It does not execute payments, issue attestations, or process financial settlements. host: x402-agent-suite-production.up.railway.app --- # x402-agent-suite-production.up.railway.app x402-agent-suite-production is a security and compliance middleware host designed for agents that make or receive x402 micropayments. It serves agent developers who need to gate payments behind risk checks, verify partner agent credentials via an attestation registry, and evaluate whether failed transactions qualify for refunds. Its distinct value is combining preflight spend/identity/URL safety checks with post-hoc refund arbitration and attestation verification in one host, purpose-built for the x402 protocol context. ## When to use this host Use this host when an agent is operating in the x402 payment ecosystem and needs to: gate payments behind preflight spend and risk checks, verify partner agent attestations before trusting their responses, or evaluate refund eligibility after a transaction. Do not use this host for executing or settling actual payments — it provides decisions and recommendations only. Do not use it for general-purpose identity verification outside the x402 attestation ecosystem, real-time price feeds, token operations, or streaming risk monitoring. For payment execution itself, use the x402 protocol client directly. For non-x402 HTTP risk assessment, use a general web security or fraud-detection service. ## Capabilities ### Preflight Payment Safety Runs spend-cap, identity-trust, and URL-safety checks before committing to an x402 payment, returning an allow/deny decision with a security grade and per-check breakdown. - **`check-pre-x402-guard`** — Runs spend, identity, and risk checks in a single preflight call before executing an x402 payment, returning an allow/deny decision with security grade and per-check details. ### Attestation Registry and Verification Looks up which agents hold valid attestations in the registry and verifies individual attestation IDs for validity, confidence score, and checks passed — enabling agents to gate partner interactions on credential status. - **`fetch-attestation-registry`** — Queries the attestation registry and returns a list of attested agent records, policy notes, and a marketplace notice about attestation requirements. - **`verify-attestation-signature`** — Verifies an attestation by ID against a registry and returns validity status, confidence score, and a list of checks passed. ### Refund Eligibility Arbitration Evaluates whether a completed or failed x402 transaction qualifies for a refund based on seller verification signals such as endpoint reachability, response quality, and scoring, returning a graded eligibility decision with buyer guidance. - **`evaluate-refund-eligibility`** — Evaluates refund eligibility for a transaction given verification signals such as score, response quality, and endpoint reachability, returning a decision with grade and buyer guidance. ## Workflows ### Safe Paid API Call with Attestation Gate *Use when an agent needs to verify a target agent's attestation credentials and pass preflight safety checks before executing an x402 payment to that agent.* 1. **`fetch-attestation-registry`** — Query the attestation registry to confirm the target agent holds a valid attestation, optionally filtering by minimum grade. 2. **`verify-attestation-signature`** — Verify the specific attestation ID returned from the registry to confirm its validity and confidence score before proceeding. 3. **`check-pre-x402-guard`** — Run spend-cap, identity, and URL safety checks against the target endpoint to get a final allow/deny decision before committing to payment. ### Post-Transaction Refund Assessment *Use when an agent needs to determine refund eligibility after a paid x402 call returned a poor or empty response, by first checking the seller endpoint and then arbitrating eligibility.* 1. **`check-pre-x402-guard`** — Retrieve endpoint reachability and identity trust signals for the seller URL, which feed into the verification score inputs required by the refund arbiter. 2. **`evaluate-refund-eligibility`** — Submit the verification score, endpoint reachability, and response quality signals to receive a graded refund eligibility decision and buyer guidance. ## Skill reference ### `evaluate-refund-eligibility` **Refund Arbiter** — Evaluates refund eligibility for a transaction given verification signals such as score, response quality, and endpoint reachability, returning a decision with grade and buyer guidance. *Use when:* Use when an agent needs to determine whether a refund request qualifies for reimbursement based on seller verification signals, such as after running endpoint checks and scoring a seller's response quality. *Not for:* Do not use for initiating or processing actual refund payments; this endpoint only evaluates eligibility and provides a recommendation, not a financial transaction. **Inputs:** - `verificationScore` (number, required) — Numeric score representing the quality or trustworthiness of the seller/endpoint verification, typically 0–100. - `responseEmpty` (boolean, required) — True if the seller's response was empty; false if a non-empty response was received. - `responseGeneric` (boolean, required) — True if the seller's response was generic/templated rather than specific; false if the response was substantive. - `endpointReachable` (boolean, required) — True if the seller's endpoint was reachable during verification; false if it was unreachable. **Returns:** Returns refundEligible (boolean), a protectionTier string, a letter grade, an array of reasons, and a buyerGuidance string explaining the refund decision. **Example:** `{"verificationScore": 93, "responseEmpty": false, "responseGeneric": false, "endpointReachable": true}` --- ### `check-pre-x402-guard` **Pre-X402 Guard** — Runs spend, identity, and risk checks in a single preflight call before executing an x402 payment, returning an allow/deny decision with security grade and per-check details. *Use when:* Use when an agent is about to make a paid x402 API call and needs to verify that the wallet is within daily/per-call spend caps, passes identity trust checks, and that the target URL is safe — all before committing to payment. *Not for:* Do not use as a guarantee of downstream API quality or payment settlement success; this is a heuristic preflight only. Do not use for non-x402 HTTP calls or for streaming/continuous risk monitoring. **Inputs:** - `agentId` (string) — Identifier for the calling agent. - `walletAddress` (string) — Wallet address (Base or Solana) of the agent making the payment. - `targetUrl` (string) — The URL of the x402-gated endpoint the agent intends to call. - `estimatedCostUsdc` (number) — Estimated cost of the target call in USDC. - `network` (string) — Network identifier for the payment (e.g. solana or eip155 chain). - `policy` (object) — Spend policy object with dailyCapUsdc, perCallCapUsdc, and allowedHosts constraints. **Returns:** Returns allowed=true, securityGrade A, spend/identity/risk sub-results, checks_passed array, and a confidence score of 0.86 when all preflight gates pass. **Example:** `{"agentId": "dexter-verifier-probe", "walletAddress": "9c7tE587KpGYBjiNQrjw3nGvxQHhSYKU4Ba6WRgQsHkt", "targetUrl": "https://api.myceliasignal.com/oracle/price/eth/usd", "estimatedCostUsdc": 0.05, "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "policy": {"dailyCapUsdc": 10, "perCallCapUsdc": 0.5, "allowedHosts": ["myceliasignal.com"]}}` --- ### `verify-attestation-signature` **Attestation Signature Verify** — Verifies an attestation by ID against a registry and returns validity status, confidence score, and a list of checks passed. *Use when:* Use when an agent needs to confirm whether a given attestation ID is valid, check its registry status, and retrieve a confidence score and reason before trusting or acting on an attestation. *Not for:* Do not use for issuing or creating new attestations; this endpoint only verifies existing ones by ID. **Inputs:** - `attestationId` (string, required) — The unique identifier of the attestation to verify. **Returns:** Returns ok=true, valid=false when attestation is not found, with a confidence score of 0.65, checks_passed list, sources consulted, and a reason string explaining the result. **Example:** `{"attestationId": "att_valid_8b4d2f7c9a3e4c0a9f1b2d3e4f506172"}` --- ### `fetch-attestation-registry` **Attestation Registry** — Queries the attestation registry and returns a list of attested agent records, policy notes, and a marketplace notice about attestation requirements. *Use when:* Use when an agent needs to look up which agents hold valid attestations in the registry, optionally filtered by minimum grade, agent ID, or result limit, before deciding whether to require an X-Suite-Attestation header in partner network calls. *Not for:* Do not use for real-time price feeds, token swaps, or identity verification outside the x402 agent attestation ecosystem. **Inputs:** - `minGrade` (string) — Minimum attestation grade to filter registry results by. - `agentId` (string) — Specific agent identifier to look up in the registry. - `limit` (integer) — Maximum number of registry records to return. **Returns:** Returns count, records array (empty if none match), a policy string describing attestation rules, and a marketplaceNote about partner agent rejection behavior. **Example:** `GET https://x402-agent-suite-production.up.railway.app/api/attestation/registry?agentId=agent-abc123&minGrade=A&limit=10` ---