PoC Walkthrough

What You’ll See

This walkthrough demonstrates the complete RAMP transaction flow against a live reference Exchange running on AWS. By the end, you will have:

Discovered available resource offers with pricing
Executed a commercial transaction and received a signed URL
Fetched premium resource through the signed URL
Reported usage back to the Exchange
Optionally: integrated the MCP tool into Claude or another AI agent

Live Exchange endpoint: https://exchange.ramp-protocol.org

Prerequisites

curl and jq (for manual walkthrough)
Python 3.10+ (for MCP tool integration)
An AI agent that supports MCP (Claude Desktop, Claude Code, etc.)

Part 1: Manual Protocol Walkthrough

Step 1: Check Exchange Health

curl -s https://exchange.ramp-protocol.org/health | jq

{
  "status": "ok",
  "version": "0.2.0"
}

Step 2: Retrieve Exchange Public Key

The Exchange announces its Ed25519 public key. Agents and Brokers use this to verify offer signatures — see how authentication works across all RAMP boundaries.

curl -s https://exchange.ramp-protocol.org/exchange/v1/keys | jq

{
  "algorithm": "ed25519",
  "public_key": "a22b5d78a5fe1657a8c4fb7ae98da1178ccfb92b96004826be1914791ab5f3aa"
}

Step 3: Discover Supply (DiscoverResources RPC)

Query the Exchange for available resource offers. This is a Connect-Go HTTP/JSON endpoint — standard POST with JSON body. The Exchange looks up resources in its catalog, computes pricing, and signs each offer with Ed25519.

curl -s -X POST https://exchange.ramp-protocol.org/ramp.v1.ExchangeService/DiscoverResources \
  -H "Content-Type: application/json" \
  -d '{
    "ver": "1.0",
    "id": "demo-query-001",
    "aisystem": {
      "name": "DemoAgent",
      "aisysuse": {
        "lid": "LIC-DEMO-001",
        "uri": ["https://cdn.ramp-protocol.org/2024/01/15/ai-startups-funding"]
      }
    }
  }' | jq

The response contains OfferGroups — one per requested URI — each with Ed25519-signed offers:

{
  "ver": "1.0",
  "id": "demo-query-001",
  "exchange": "ramp-exchange-v1.0",
  "offerGroups": [
    {
      "uri": "https://cdn.ramp-protocol.org/2024/01/15/ai-startups-funding",
      "offers": [
        {
          "offerId": "offer-cdn.ramp-protocol.org-1773682699693224366",
          "package": {
            "id": "pkg-cdn.ramp-protocol.org/2024/01/15/ai-startups-funding",
            "retrieval": {
              "endpoint": "https://cdn.ramp-protocol.org/2024/01/15/ai-startups-funding.html"
            }
          },
          "pricing": {
            "model": "PRICING_MODEL_PER_ACCESS",
            "rate": 0.05,
            "currency": "USD",
            "estimated_quantity": 2000
          },
          "deliveryMethod": "DELIVERY_METHOD_INSTRUCTIONS",
          "reporting": {
            "required": true,
            "window": "86400s",
            "requiredFields": ["consumed_quantity"]
          },
          "exchangeSignature": "ae77b181...32607e08",
          "signatureAlgorithm": "ed25519"
        }
      ]
    }
  ]
}

Key fields in each offer:

offerId — unique identifier for this offer
pricing — rate ($0.05/article), currency, estimated tokens. Pricing models are defined in the protocol spec and follow RSL conventions
exchangeSignature — Ed25519 signature over the offer. Stateless: the Exchange can verify this signature on ExecuteTransaction without storing the offer
reporting — usage reporting is mandatory, due within 24 hours, must include consumed_quantity. See how the billing cycle works
package — IAB CoMP Package object describing the content

Step 4: Execute Transaction (ExecuteTransaction RPC)

Commit to an offer. Pass the offerId and offerSignature from Step 3. The Exchange verifies the signature, authorizes billing, writes the transaction log (WAL — write-before-sign invariant), and returns a signed URL.

curl -s -X POST https://exchange.ramp-protocol.org/ramp.v1.ExchangeService/ExecuteTransaction \
  -H "Content-Type: application/json" \
  -d '{
    "ver": "1.0",
    "id": "demo-txn-001",
    "offerId": "<offerId from Step 3>",
    "offerSignature": "<exchangeSignature from Step 3>",
    "offerSignatureAlgorithm": "ed25519",
    "aisystem": {
      "name": "DemoAgent",
      "aisysuse": { "lid": "LIC-DEMO-001" }
    }
  }' | jq

Response:

{
  "ver": "1.0",
  "id": "demo-txn-001",
  "transactionId": "txn-1773682700352684307",
  "billingId": "bill-000002",
  "package": {
    "id": "pkg-delivered",
    "retrieval": {
      "endpoint": "https://cdn.ramp-protocol.org/premium/article.html?agent_id=05f116fd...824d2d9&expires=1773683000&sig=3ab495e3...48823a14&txn_id=txn-1773682700352684307"
    }
  },
  "cost": { "amount": 0.05, "currency": "USD" },
  "deliveryMethod": "DELIVERY_METHOD_INSTRUCTIONS",
  "reportingObligation": {
    "required": true,
    "window": "86400s",
    "requiredFields": ["consumed_quantity"]
  },
  "expiresAt": "2026-03-16T17:43:20Z",
  "agentIdentityHash": "05f116fdb971e44f1c59fddc8a29954018b2c5fd6a3993cec318b12ac824d2d9"
}

Key fields:

transactionId — unique transaction reference, recorded in the transaction log before the signed URL is generated
billingId — billing record reference, managed by the Billing Adapter
package.retrieval.endpoint — the signed URL with HMAC-SHA256 signature, expiry, agent identity binding, and transaction ID
cost — $0.05 USD charged. See how money flows for the full billing lifecycle
reportingObligation — you MUST report usage within 24 hours. See budget and reporting for how the Agent SDK handles this
agentIdentityHash — SHA-256 of your license ID, bound into the signed URL to prevent URL sharing

Step 5: Fetch Resource via Signed URL

The signed URL contains four verification parameters, all verified by the CDN edge function:

sig — HMAC-SHA256 signature (Exchange↔CDN shared secret). See signed URL verification for the canonical format
expires — Unix timestamp (URL expires after 5 minutes)
agent_id — SHA-256 of your license ID (identity binding — prevents URL sharing)
txn_id — transaction ID (enables three-sided reconciliation: CDN logs + Exchange logs + agent reports)

In production, the edge function also performs bot detection — blocking unauthorized AI crawlers with a 403 and X-Content-Rules header that redirects to the Exchange.

Step 6: Report Usage (ReportUsage RPC)

Usage reporting is mandatory. The Exchange tracks compliance and will deny future transactions for agents with overdue reports (see denial reasons). The Agent SDK handles this automatically.

curl -s -X POST https://exchange.ramp-protocol.org/ramp.v1.ExchangeService/ReportUsage \
  -H "Content-Type: application/json" \
  -d '{
    "ver": "1.0",
    "id": "demo-report-001",
    "transactionId": "<transactionId from Step 4>",
    "billingId": "<billingId from Step 4>",
    "usage": { "consumed_quantity": 1500 }
  }' | jq

{ "accepted": true }

Step 7: Verify Denial Conditions

The Exchange enforces 11 denial reasons defined in the protocol:

Missing offer signature → DENIAL_REASON_SIGNATURE_INVALID:

curl -s -X POST https://exchange.ramp-protocol.org/ramp.v1.ExchangeService/ExecuteTransaction \
  -H "Content-Type: application/json" \
  -d '{"ver":"0.2","id":"deny-001","offerId":"fake","aisystem":{"name":"DemoAgent","aisysuse":{"lid":"LIC-DEMO-001"}}}' | jq .denialReason

"DENIAL_REASON_SIGNATURE_INVALID"

Zero token count → rejection:

{ "accepted": false, "rejectionReason": "consumed_quantity is required and must be > 0" }

See the full threat model for how these protections defend against replay attacks, URL sharing, billing fraud, and reporting evasion.

Part 2: MCP Tool Integration

The RAMP MCP tool (commercial_web_fetch) wraps the entire fetch flow into a single tool call that AI agents can use transparently. It implements the same flow as the Agent SDK.

How It Works

Agent calls: commercial_web_fetch(["https://cdn.ramp-protocol.org/2024/01/15/ai-startups-funding"])

MCP Tool internally:
  1. DiscoverResources → gets offers with pricing
  2. Selects best offer (cheapest rate, prefers subscriptions)
  3. ExecuteTransaction → gets signed URL + billing
  4. Fetches resource via signed URL
  5. ReportUsage → fulfills reporting obligation

Agent receives: article content + cost + transaction details

This mirrors the Agent SDK fetch flow — the MCP tool is a thin wrapper that exposes the same logic as an MCP server.

Add to Claude Desktop / Claude Code

Add to your MCP configuration (.mcp.json or Claude Desktop settings):

{
  "mcpServers": {
    "ramp-ai-buyer": {
      "type": "http",
      "url": "https://e2iwwg6o4byqlvn35pw3bkigpi0dkwll.lambda-url.us-east-1.on.aws/mcp"
    }
  }
}

Try It

In Claude, ask:

Fetch the article at https://cdn.ramp-protocol.org/2024/01/15/ai-startups-funding using the commercial_web_fetch tool

The tool negotiates with the Exchange and returns:

--- Content from https://cdn.ramp-protocol.org/2024/01/15/ai-startups-funding ---
[RAMP v1.0 | Cost: 0.0500 USD | Transaction: txn-1773682640975288995 |
 Billing: bill-000001 | Usage reported: True]

[Content delivered via signed URL with HMAC-SHA256 + agent identity binding]

--- RAMP Cost Summary ---
Total data acquisition cost: $0.0500
URLs processed: 1
Exchange: https://exchange.ramp-protocol.org

Part 3: Batch Multi-URL Query

RAMP supports querying multiple URLs in a single DiscoverResources request. Each URL gets its own OfferGroup with independent pricing:

curl -s -X POST https://exchange.ramp-protocol.org/ramp.v1.ExchangeService/DiscoverResources \
  -H "Content-Type: application/json" \
  -d '{
    "ver": "1.0",
    "id": "demo-batch-001",
    "aisystem": {
      "name": "DemoAgent",
      "aisysuse": {
        "lid": "LIC-DEMO-001",
        "uri": [
          "https://cdn.ramp-protocol.org/2024/01/15/ai-startups-funding",
          "https://cdn.ramp-protocol.org/2024/02/20/cloud-computing-trends",
          "https://cdn.ramp-protocol.org/2024/03/10/robotics-warehouse"
        ]
      }
    }
  }' | jq '.offerGroups[] | {uri, rate: .offers[0].pricing.rate}'

{ "uri": "https://cdn.ramp-protocol.org/2024/01/15/ai-startups-funding", "rate": 0.05 }
{ "uri": "https://cdn.ramp-protocol.org/2024/02/20/cloud-computing-trends", "rate": 0.03 }
{ "uri": "https://cdn.ramp-protocol.org/2024/03/10/robotics-warehouse", "rate": 0.04 }

In a real Broker deployment, the selection engine would compare offers across multiple Exchanges and select the best combination based on price, quality, and budget constraints.

Part 4: Run Your Own Exchange

The reference implementation is open source. See the Exchange component docs for architecture details, or run it locally:

git clone https://github.com/postindustria-tech/agentic-content-access.git
cd agentic-content-access/v0.2-poc/exchange

# Run directly (requires Go 1.23+)
go run ./cmd/server

# Or with Docker
docker compose up

# Test
curl http://localhost:3000/health
curl http://localhost:3000/exchange/v1/keys

For production deployment, see:

Exchange configuration — environment variables, secrets, tenant setup
Multi-tenant architecture — how one Exchange serves multiple providers
Scaling — from single instance to 10K+ RPS
Edge function deployment — CDN-specific adapters for CloudFront, Cloudflare, Akamai, Fastly

Protocol Summary

Step	RPC	What Happens	Deep Dive
0	—	Provider drops `ramp.json` on their domain	Discovery Paths
1	`DiscoverResources`	Agent queries Exchange for offers on URIs	Request Flows
2	—	Agent/Broker selects best offer	Selection Engine
3	`ExecuteTransaction`	Agent commits to offer, receives signed URL	Billing Adapter
4	—	Agent fetches resource via signed URL (edge function verifies)	Bot Detection
5	`ReportUsage`	Agent reports consumed quantity (mandatory)	Budget & Reporting

Security at every boundary (full threat model):

Agent signs requests with Ed25519 (proves identity)
Exchange signs offers with Ed25519 (stateless verification)
Signed URLs use HMAC-SHA256 (Exchange↔CDN shared secret)
Agent identity bound into signed URL (prevents URL sharing)
Transaction ID in signed URL (enables three-sided reconciliation)

Next Steps

Transaction Flow — step-by-step protocol specification
Scenario Walkthrough — multi-party narrative (Anthropic, Hearst, SSP-Alpha)
For AI Agents — build your own integration
For Exchange Operators — operate an Exchange
For Providers — monetize your resources
Authentication — Ed25519 at every boundary
Threat Model — 30 attack vectors and countermeasures