--- name: x402trustlayer.xyz description: x402trustlayer.xyz provides infrastructure-layer tooling for agents operating within x402 payment ecosystems, covering endpoint health verification, spend governance, attestation trust checks, and multi-agent budget distribution. It does not execute payments or trades directly but instead handles the policy, routing, and trust verification steps that surround x402-gated API calls. All skills return decisions, scores, or recommendations rather than settling funds on-chain. host: x402trustlayer.xyz --- # x402trustlayer.xyz TrustLayer serves as a pre-execution and governance layer for agents that consume x402-gated APIs. It is designed for multi-agent pipelines where spending policy enforcement, endpoint reliability, attestation trust, and budget allocation must be resolved before any paid call is made. The host is distinct in combining spend governance, fleet budget distribution, attestation verification, and endpoint quality probing into a single addressable service, rather than offering financial data or transaction execution. ## When to use this host Use x402trustlayer.xyz when an agent needs to enforce spending policy, verify attestation trust, probe x402 endpoint health, allocate budgets across a fleet, or discover and route to x402-compatible APIs. It is the right choice for governance and pre-execution checks in multi-agent x402 pipelines. Do not use this host for executing payments or on-chain settlements — it returns decisions and recommendations only; actual payment execution must be performed by calling the returned route URLs or a separate payment settlement service. Do not use it for real-time market data, token prices, swap quotes, or continuous monitoring — it has no streaming or live financial data capabilities. For non-x402 endpoint monitoring, use a general-purpose uptime or observability service instead. ## Capabilities ### Attestation Trust Provides the ability to query the attestation registry for known valid agents and to verify individual attestation proofs by ID, enabling agents to enforce trust requirements before acting on attested claims or admitting partners into a network. - **`fetch-attestation-registry`** — Returns attestation registry records for trust-layer verification, including count, policy, and matched agent attestation entries. - **`verify-attestation-signature`** — Verifies an attestation proof by ID against the TrustLayer registry and returns validity status, confidence score, and checks passed. ### Spend Governance Enforces per-agent spending policy by checking proposed costs against daily and per-call USDC caps and allowed-host lists, and estimates whether an MPP session or per-call settlement is more cost-effective for a given call volume. - **`check-spend-governor`** — Evaluates a proposed agent spend against daily and per-call USDC caps and an allowlist of hosts, returning an allow/deny decision with remaining budget. - **`estimate-mpp-session-plan`** — Estimates MPP session cost versus per-call settlement cost for a given expected call volume and average price per call, returning savings, break-even count, and a recommendation. ### Fleet Budget Allocation Distributes a shared USDC pool across a fleet of agents in a single call, respecting each agent's priority, requested amount, and daily cap, and returns per-agent approval decisions. - **`allocate-fleet-budget`** — Distributes a shared USDC pool across a fleet of agents, respecting each agent's priority, requested amount, and daily remaining cap, and returns per-agent allocations with approval status. ### Endpoint Discovery and Routing Routes natural-language capability queries to the best-matching x402 API endpoint with network and price filters, and recommends the next logical paid API step after a completed settlement to reduce agent search overhead. - **`route-x402-capability-query`** — Routes a natural-language capability query to the best-matching x402 API endpoint, returning a selected route and ranked alternatives filtered by network and USDC price. - **`fetch-settlement-graph-next`** — Given the last API endpoint path and topic, returns recommended next paid API steps to reduce agent search overhead after a settlement. ### Endpoint Health Probing Batch-probes up to 10 x402 endpoints in a single call to verify they return correct HTTP 402 responses, computes per-URL health scores, and produces an overall pass/fail summary for pipeline readiness checks. - **`probe-x402-endpoint-quality`** — Sends regression health probes to up to 10 x402 endpoints and returns per-URL status, health scores, payment requirements, and an overall pass/fail summary. ## Workflows ### Pre-Call Trust and Spend Gate *Use when an agent needs to verify a counterpart agent's attestation and confirm its own spend policy is satisfied before making a paid x402 API call.* 1. **`fetch-attestation-registry`** — Query the attestation registry to confirm the target agent or partner holds a valid attestation at the required grade. 2. **`verify-attestation-signature`** — Verify the specific attestation ID returned from the registry to confirm it is valid and recognized by TrustLayer. 3. **`check-spend-governor`** — Check that the estimated cost of the intended paid call falls within the agent's daily cap, per-call cap, and allowed-host policy before proceeding. ### Endpoint Discovery with Health Validation *Use when an agent needs to discover the best x402 endpoint for a capability and confirm it is healthy before committing to use it in a pipeline.* 1. **`route-x402-capability-query`** — Route a natural-language capability query to identify the best-matching x402 endpoint and ranked alternatives within network and price constraints. 2. **`probe-x402-endpoint-quality`** — Probe the selected endpoint (and any alternatives) to verify they return correct HTTP 402 responses and meet health score thresholds before use. ### Fleet Budget Distribution with Spend Check *Use when an agent orchestrating a fleet needs to allocate a shared USDC pool and then verify each individual agent's spend policy before dispatching work.* 1. **`allocate-fleet-budget`** — Distribute the shared USDC pool across fleet agents, producing per-agent allocation decisions with approval status. 2. **`check-spend-governor`** — For each approved agent, confirm the allocated amount satisfies that agent's per-call and daily cap policy before authorizing the paid call. ### Payment Strategy and Post-Settlement Routing *Use when an agent needs to decide between MPP session and per-call payment before a batch of calls, then determine the next optimal endpoint after each settlement completes.* 1. **`estimate-mpp-session-plan`** — Estimate whether opening an MPP session or paying per-call is more cost-effective given the expected call volume and average price. 2. **`check-spend-governor`** — Confirm the chosen payment strategy's estimated cost falls within the agent's configured spending policy. 3. **`fetch-settlement-graph-next`** — After each settlement completes, retrieve the recommended next paid API endpoint to invoke based on the prior endpoint path and topic. ## Skill reference ### `probe-x402-endpoint-quality` **Quality Monitor Probe** — Sends regression health probes to up to 10 x402 endpoints and returns per-URL status, health scores, payment requirements, and an overall pass/fail summary. *Use when:* Use when an agent needs to verify that a batch of x402-gated endpoints are correctly returning HTTP 402 for unpaid requests, are healthy, and meet expected status classifications before relying on them in a pipeline. *Not for:* Do not use for monitoring non-x402 endpoints or for real-time streaming health checks; this is a single-shot batch probe, not a continuous monitor. **Inputs:** - `urls` (array, required) — List of up to 10 x402 endpoint URLs to probe for health and correct payment-gating behavior. **Returns:** Returns status='ok', a results array with per-URL HTTP status, health score (0–100), classification, priceUsdc, and notes, plus averageScore, overall pass/fail, and a summary string. **Example:** `{"urls":["https://x402trustlayer.xyz/api/quality-monitor/probe","https://x402trustlayer.xyz/api/guard/pre-x402","https://x402trustlayer.xyz/api/x402/proxy"]}` --- ### `allocate-fleet-budget` **Budget Allocator** — Distributes a shared USDC pool across a fleet of agents, respecting each agent's priority, requested amount, and daily remaining cap, and returns per-agent allocations with approval status. *Use when:* Use when an agent needs to distribute a shared USDC budget pool across multiple agents in a fleet, taking into account each agent's priority score, requested amount, and daily spending cap, and requires a per-agent allocation decision in a single call. *Not for:* Do not use for single-agent budget checks or real-time price feeds; this endpoint is specifically for multi-agent fleet pool distribution scenarios. **Inputs:** - `fleetId` (string, required) — Unique identifier for the agent fleet whose shared pool is being allocated. - `poolRemainingUsdc` (number, required) — Total USDC remaining in the shared pool available for distribution across all agents. - `agents` (array, required) — Array of agent objects, each specifying agentId, priority, requestedUsdc, and dailyRemainingUsdc. All four fields are required per agent. **Returns:** Returns fleetId, poolRemainingUsdc, poolAfterUsdc, and an allocations array with each agent's allocatedUsdc (capped at their daily limit), approved flag, and approval reason. **Example:** `{"fleetId":"verifier-fleet","poolRemainingUsdc":1000,"agents":[{"agentId":"a1","priority":10,"requestedUsdc":0.2,"dailyRemainingUsdc":5},{"agentId":"a2","priority":7,"requestedUsdc":0.5,"dailyRemainingUsdc":3}]}` --- ### `fetch-settlement-graph-next` **Settlement Graph Next** — Given the last API endpoint path and topic, returns recommended next paid API steps to reduce agent search overhead after a settlement. *Use when:* Use when an agent has just completed a settlement or API call and needs to determine which paid API endpoint to invoke next, based on the prior endpoint path and topic context. *Not for:* Do not use for real-time price feeds or swap quotes; this is a post-settlement routing recommendation tool, not a financial data or trading API. **Inputs:** - `lastEndpointPath` (string, required) — The path of the most recently called API endpoint, used to determine the next recommended step. - `lastTopic` (string, required) — The topic or domain of the last API call, used to contextualize the next-step recommendation. **Returns:** Returns a recommendations array with named next-hop APIs, their USDC prices, and reasons, plus a graphNote explaining integration context. **Example:** `{"lastEndpointPath": "/api/settlement/confirm", "lastTopic": "invoice_payout"}` --- ### `estimate-mpp-session-plan` **MPP Session Plan Estimator** — Estimates MPP session cost versus per-call settlement cost for a given expected call volume and average price per call, returning savings, break-even count, and a recommendation. *Use when:* Use when an agent needs to decide whether to open an MPP session or pay per-call, given a known expected call count and average per-call price in USDC, before committing to a payment strategy. *Not for:* Do not use to actually open, close, or settle an MPP session; this endpoint only estimates costs and does not execute any on-chain settlement. **Inputs:** - `action` (string, required) — Mode of the request. Use 'estimate' to compute savings projections; 'close' to request session closure metadata. - `expectedCalls` (integer, required) — Number of API calls expected in the session, used to compute total session and per-call costs. - `avgPricePerCallUsdc` (number, required) — Average price per individual API call in USDC, used as the per-call settlement baseline for comparison. **Returns:** Returns estimated MPP session cost (0.13 USDC), per-call total cost (4.62 USDC), savings (4.49 USDC), break-even call count (1), recommendation ('mpp'), and the model assumptions used. **Example:** `{"action": "estimate", "expectedCalls": 120, "avgPricePerCallUsdc": 0.0385}` --- ### `route-x402-capability-query` **TrustLayer Route API** — Routes a natural-language capability query to the best-matching x402 API endpoint, returning a selected route and ranked alternatives filtered by network and USDC price. *Use when:* Use when an agent needs to discover and select the optimal x402-compatible API endpoint for a given capability (e.g. USDC payment routing, oracle lookup) on a specific network, with a maximum price constraint. *Not for:* Do not use for executing payments or transactions directly; this endpoint only returns route options and does not execute them. For actual payment execution, call the returned route URL separately. **Inputs:** - `query` (string, required) — Natural-language description of the capability or intent to route (e.g. 'ETH USD spot price oracle' or a USDC payment routing request). - `preferNetwork` (string, required) — Preferred blockchain network to filter route options (e.g. 'polygon-mainnet', 'solana'). - `maxPriceUsdc` (number, required) — Maximum acceptable price in USDC for the routed capability. Routes exceeding this threshold are excluded. - `skipProbes` (boolean, required) — When true, skips live probing of candidate endpoints and returns cached/static route options. **Returns:** Returns status='ok', a selected route object (name, url, priceUsdc, qualityScore), an alternatives array of ranked fallback routes, executed=false, and an executionNote describing applied filters. **Example:** `{"query":"ETH USD spot price oracle","preferNetwork":"solana","maxPriceUsdc":0.1,"skipProbes":true}` --- ### `check-spend-governor` **Spend Governor Check** — Evaluates a proposed agent spend against daily and per-call USDC caps and an allowlist of hosts, returning an allow/deny decision with remaining budget. *Use when:* Use when an agent is about to make a paid API call and needs to verify the estimated cost falls within its configured daily cap, per-call cap, and allowed host policy before proceeding. *Not for:* Do not use for real-time price feeds or token quotes; use a market data API instead. Not a payment execution endpoint — it only checks policy, it does not settle funds. **Inputs:** - `agentId` (string, required) — Unique identifier for the agent making the spend request. - `estimatedCostUsdc` (number, required) — Estimated cost of the intended call in USDC (decimal, not atomic units). - `targetUrl` (string, required) — Full URL of the API endpoint the agent intends to call. - `network` (string, required) — Network identifier for the intended call context (e.g. 'base', 'solana'). - `policy` (object, required) — Spend policy object containing dailyCapUsdc, perCallCapUsdc, and allowedHosts. All three sub-fields are required. **Returns:** Returns allowed=true, a reason string, spentTodayUsdc=1.75, remainingDailyUsdc=8.25, and perCallCapUsdc=2 when the estimated cost is within both daily and per-call limits. **Example:** `{"agentId": "dexter-verifier-probe", "estimatedCostUsdc": 1.75, "targetUrl": "https://x402trustlayer.xyz/api/spend-governor/check", "network": "base", "policy": {"dailyCapUsdc": 10, "perCallCapUsdc": 2, "allowedHosts": ["x402trustlayer.xyz"]}}` --- ### `fetch-attestation-registry` **Attestation Registry** — Returns attestation registry records for trust-layer verification, including count, policy, and matched agent attestation entries. *Use when:* Use when an agent needs to query the attestation registry to verify which agents hold valid attestations, optionally filtering by minimum grade, agent ID, or result limit before enforcing attestation requirements in partner network calls. *Not for:* Do not use for real-time trust scoring or live agent reputation feeds; this returns a static registry snapshot, not a streaming or continuously updated trust signal. **Inputs:** - `minGrade` (string) — Minimum attestation grade to filter registry results by. Only records at or above this grade are returned. - `agentId` (string) — Specific agent identifier to look up in the attestation registry. - `limit` (integer) — Maximum number of registry records to return in the response. **Returns:** Returns a JSON object with count (integer), records (array of attestation entries, empty when none match), policy (string), and marketplaceNote (string) describing registry enforcement behavior. **Example:** `GET https://x402trustlayer.xyz/api/attestation/registry?agentId=agent-abc123&minGrade=A&limit=10` --- ### `verify-attestation-signature` **TrustLayer Attestation Verify** — Verifies an attestation proof by ID against the TrustLayer registry and returns validity status, confidence score, and checks passed. *Use when:* Use when an agent needs to confirm whether a given attestation ID is valid and recognized by the TrustLayer registry before trusting or acting on an attested claim. *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 against the TrustLayer registry. **Returns:** Returns ok=true, valid=false when attestation is not found, with confidence score, checks_passed array, sources consulted, and an accuracy disclaimer note. **Example:** `{"attestationId": "valid-attestation-id-00000000-0000-4000-8000-000000000001"}` ---