API Scaffolding

API Scaffolding

API Scaffolding is a separate Valiron product for exposing existing HTTPS APIs through hosted, agent-facing URLs. It supports rapid distribution and evaluation while providing a migration path to first-party backend deployments protected by Valiron middleware.

Agent -> /wrap/{operatorId}/{path}
        -> x402 or MPP payment challenge, if price > 0
        -> optional Valiron trust gate
        -> rate limit + SSRF protection
        -> upstream API request

Dashboard Setup

1. Open valiron.co/dashboard.
2. Go to Make API Agent-Ready.
3. Enter the public path, HTTP method, upstream API base URL, price, payment protocol, payment network, and payout wallet.
4. Enable trust checks when the wrapper should require agent identity and trust evaluation before forwarding upstream.
5. For a public origin, configure HMAC upstream authentication and reject direct unsigned requests at the origin.
6. Distribute only the generated wrapper URL to agent clients.

HTTP API Setup

The dashboard uses the same JWT-authenticated endpoint you can call directly:

curl -X POST https://valiron-edge-proxy.onrender.com/operator/endpoints \
  -H "authorization: Bearer $VALIRON_JWT" \
  -H "content-type: application/json" \
  -d '{
    "path": "/weather",
    "method": "GET",
    "pricePerCall": 0.001,
    "targetUrl": "https://api.example.com",
    "paymentProtocol": "x402",
    "paymentNetwork": "eip155:8453",
    "payoutAddress": "0xYourPayoutWallet",
    "trustEnabled": false,
    "upstreamAuthType": "hmac",
    "upstreamAuthSecret": "replace-with-a-unique-shared-secret"
  }'

Calling Wrappers

Agent clients call the generated public wrapper URL. Free wrappers forward immediately. Paid wrappers return a 402 Payment Required challenge and require the caller to retry with payment.

curl -i https://valiron-edge-proxy.onrender.com/wrap/{operatorId}/weather

x402 & MPP

x402 wrappers use Base-compatible HTTP payments. An unpaid request returns a 402 challenge, and the paid retry includes an X-PAYMENT header. MPP wrappers use WWW-Authenticate: Payment and retry with Authorization: Payment ....

pnpm exec mppx account create
pnpm exec mppx https://valiron-edge-proxy.onrender.com/wrap/{operatorId}/research

Protect Your Origin

A hosted wrapper evaluates and logs only requests sent to its generated Valiron URL. It is not a network firewall for a separately public API origin. If a caller can reach the origin directly, it can bypass the wrapper's payment, trust, rate-limit, and analytics path.

For a public origin, configure upstreamAuthType: "hmac" and verify the signature plus timestamp before your origin handler runs. Publish only the generated wrapper URL in agent discovery and client configuration. Do not use the presence of x-valiron-* metadata headers as authentication; direct callers can forge ordinary headers.

1. Configure a unique HMAC secret on the wrapper and in your origin verification middleware.
2. Confirm direct, unsigned origin requests return 401 or 403.
3. Send a request through the wrapper and confirm its payment/trust result and call-log entry.

Deploy With Middleware Protection

For production deployments that require full backend control, implement Valiron middleware directly in the service using createValironGate() or ValironOperator.paywall().

import { ValironSDK, createValironGate } from '@valiron/sdk';

const valiron = new ValironSDK({ apiKey: process.env.VALIRON_API_KEY });

app.use('/api/weather', createValironGate({
  sdk: valiron,
  minScore: 70,
}));