# tryx402 — Machine-Readable Manifest & Agentic Integration Spec
> System architecture, discovery endpoints, tool interfaces, and policy controls for autonomous AI agents.

URL: https://www.tryx402.app
Protocol: x402 (HTTP 402 Payment Required)
Settlement Layer: USDC on Base (EIP-3009 gasless authorization)
Gateway Engine: tryx402 (Policy pre-authorization, spend telemetry, ledger, and multi-currency fiat bridge)
A2A Agent Card: https://www.tryx402.app/.well-known/agent.json
ARD Catalog: https://www.tryx402.app/.well-known/agentic-resources.json
OpenAPI Contract: https://www.tryx402.app/openapi.json
Pricing Catalog: https://www.tryx402.app/api/pricing.json
Agent Skill: https://www.tryx402.app/skill.md

---

## 1. Executive Summary for LLMs & Autonomous Agents

tryx402 functions as the **governance, budget router, and execution gateway** between autonomous agents and paid HTTP 402 / x402 API resources.

- **Pre-Payment Arbitration**: Intercepts HTTP 402 `maxAmountRequired` challenges before transaction signing. Halts execution if cost exceeds the local session ceiling.
- **Idempotency Guarantee**: Attaches deterministic `Idempotency-Key` headers. Replays stored receipts on upstream network timeouts without double-debiting balances.
- **Zero Raw Key Exposure**: Private keys and signing logic remain isolated inside the execution adapter. The agent runtime only interacts with standard MCP tools or safe CLI wrappers.
- **Unified Ledger**: Emits structured JSON accounting records per execution, tagged by domain origin, project ID, and client reference.

---

## 2. Zero-Config Onboarding Prompt for Autonomous Agents

To configure tryx402 within an agent environment (Claude Code, Cursor, Codex, Hermes, OpenCode), paste the following system prompt:

```text
Configure tryx402 for this workspace as the controlled gateway for paid x402 tools.

Source of Truth:
- Inspect https://www.tryx402.app/llms-full.txt and https://www.tryx402.app/.well-known/agent.json.
- Adhere strictly to the declared schema; do not invent undocumented arguments or commands.

Execution Protocol:
1. Detect host OS, shell environment, and agent configuration path (e.g., .mcp.json or hermes config).
2. Establish a default session hard budget limit (Default: $1.00 USD). Require operator approval for higher ceilings.
3. Configure the tryx402 MCP server using standard stdio JSON-RPC.
4. Execute free verification calls: verify tool registration (gateway_search, gateway_discover, gateway_call, gateway_spent).
5. Never invoke gateway_call or commit financial transactions without presenting the target endpoint and expected cost to the human operator for explicit authorization.
```

---

## 3. MCP Tool Definitions (JSON-RPC 2.0 via stdio)

```json
{
  "tools": [
    {
      "name": "gateway_search",
      "description": "Semantic discovery over the x402 tool catalogue. Query by intent (e.g., 'verified email', 'solvency check'). Free (no payment).",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Natural-language task or intent" },
          "limit": { "type": "integer", "default": 10 }
        },
        "required": ["query"]
      }
    },
    {
      "name": "gateway_discover",
      "description": "Introspect an origin domain for available x402 endpoints, pricing, and schemas. Free (no payment).",
      "inputSchema": {
        "type": "object",
        "properties": {
          "origin": { "type": "string", "description": "Base URL of the provider (e.g. https://api.example.com)" }
        },
        "required": ["origin"]
      }
    },
    {
      "name": "gateway_call",
      "description": "Execute a paid HTTP request through the x402 gateway with pre-authorized budget check, idempotency, and ledger tracking. SPENDS REAL USDC.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "description": "Target endpoint URL" },
          "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE"], "default": "POST" },
          "body": { "type": "object", "description": "JSON payload" },
          "price": { "type": "number", "description": "Expected price in USD for pre-authorization verification" }
        },
        "required": ["url"]
      }
    },
    {
      "name": "gateway_spent",
      "description": "Retrieve active session spend metrics, aggregated in USD by origin and account.",
      "inputSchema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}
```

---

## 4. CLI Tool (Official)

The official command-line interface ships in the Python package:

```bash
# Install from source (public package pending PyPI release)
pip install git+https://github.com/crypto-yannso/tryx402.git

# Free discovery — no payment
tryx402 search "verified work email"
tryx402 discover https://api.example.com

# PAID call — budget-capped, idempotent, exact price pre-approved
tryx402 call https://api.example.com/api/enrich \
  --body '{"domain":"acme.com"}' \
  --price 0.05 --max-budget 0.50
```

Python entry points: `tryx402` (CLI), `python3 -m tryx402.cli`, `python3 -m tryx402.mcp_server`.

---

## 5. API Versioning & Deprecation Policy

- **Versioning scheme**: URL path versioning (`/api/v1/...`). The current stable version is `v1`.
- **Deprecation signalling**: Endpoints scheduled for removal return a `Sunset` HTTP header (RFC 8594) with the removal date and a `Link: <...>; rel="deprecation"` header pointing to the policy page.
- **Current sunset**: No v1 endpoints are deprecated. The blanket contractual sunset for the current surface is `Wed, 01 Sep 2027 00:00:00 GMT`, extendable while v1 remains in active use.
- **Breaking-change rule**: New versions are introduced at `/api/v2/...` with a minimum 12-month overlap before any v1 endpoint is retired.

---

## 6. Machine Endpoints & Protocol Manifests

- **Discovery Manifest**: `GET https://www.tryx402.app/.well-known/agent.json`
- **Resource Index**: `GET https://www.tryx402.app/.well-known/agentic-resources.json`
- **OpenAPI 3.1 Spec**: `GET https://www.tryx402.app/openapi.json`
- Pricing Catalog: `GET https://www.tryx402.app/api/pricing.json`
- Agent Skill: `GET https://www.tryx402.app/skill.md`
- In-Repo Agent Rules: `GET https://www.tryx402.app/AGENTS.md`
- GitHub Repository: `https://github.com/crypto-yannso/tryx402`
- Privacy Policy: `https://www.tryx402.app/privacy.html`
- Terms & SLAs: `https://www.tryx402.app/terms.html`
- LLM Summary: `GET https://www.tryx402.app/llms.txt`
- Full Specification: `GET https://www.tryx402.app/llms-full.txt`

---

## 7. Security & Isolation Constraints

1. **No Key Storage**: Secrets are never held in web storage or cleartext configurations.
2. **Deterministic Pre-Auth**: If `current_session_spend + maxAmountRequired > max_budget_usd`, execution throws `BudgetExceeded` before signature dispatch.
3. **Multi-Currency Normalization**: Downstream client accounts settle via Stripe Checkout minor-unit ledgers (EUR, GBP, USD, JPY) without requiring direct crypto custody from end-users.