Get Paid Per Request

The model

Orches is the coordination layer between agent intent and executable financial workflows. Providers register a capability and price it per request. Agents resolve provider selection from a machine-readable registry, settle at request level over the x402 protocol on Robinhood Chain, and take back a verifiable outcome. No key exchange, no account, no subscription.

Both sides of the exchange run on the same open packages: SDKs, an MCP server, and a registry spec, published to npm and PyPI. See what to install.

Payment is the credential

Settlement carries the authority. Rather than issuing a credential ahead of time, a provider answers with a plain HTTP 402. The agent settles in stablecoin, the transfer is verified on-chain, and the workflow continues. Nothing to provision, nothing to rotate, nobody to approve it.

The transaction hash is the authority, so the model composes across agent runtimes, MCP servers, and recursive delegation. Where software acts on its own behalf, request-level settlement is the only access control that survives the recursion.

Pick a path

The two-step exchange

Intent becomes execution in two HTTP round trips, on standard status codes:

1. Agent calls POST /api/services/[id]/call with the request payload.
2. Orches returns HTTP 402 with a payment object: recipient wallet, USDG amount, network, and a 10-minute expiry.
3. Agent submits a USDG transfer on Robinhood Chain and captures the transaction hash.
4. Agent retries with an x-payment-proof header containing the txHash and payerWallet.
5. Orches verifies the on-chain transfer and returns HTTP 200 with the provider response.

The request is checked against the capability's inputSchema before any challenge is issued, so a malformed body returns 400 and never costs anyone a settlement. fetchWithPayment collapses steps 2 to 5 into one call.

Challenge fields

The 402 body carries every term of the exchange. The same fields sit at the top level for x402 clients and under a payment key for everyone else.

Proving payment

Once settled, the agent replays the request carrying an x-payment-proof header. The evidence is a small JSON object:

1{
2  "txHash": "0x91c9…6055",      // required. The USDG transfer hash
3  "payerWallet": "0x8A05…0C08"  // recommended. The paying account
4}

Orches verifies the transfer on-chain before it routes anything to the provider. It confirms that the:

• transaction succeeded and is a USDG transfer on the expected network;
• token contract matches the canonical USDG address for that network;
• recipient equals the service's payTo wallet;
• amount is at least the registered price (underpayment is rejected);
• txHash has not been used for this service before (replay protection).

Single-use rules

Replay protection is the difference between a settlement and a bare transfer. Every proof is indexed, so one transaction unlocks one capability exactly once and the receipt stays auditable afterwards.

Via the registry

Ship a plain HTTPS endpointthat takes JSON and returns JSON. You write no payment code. Orches issues the challenge, verifies the transfer, enforces replay protection, then routes the request through. USDG lands in your wallet, not in an intermediary's balance.

1. Stand up a reachable HTTPS route (POST, JSON in and out).
2. Publish JSON Schemas for input and output. This is what an agent evaluates before it selects you.
3. Connect a payout key. Provider identity and settlement destination are the same address.
4. Submit on the Publish page. New services enter pending_review; once approved they go live in the marketplace.

On your own server

Metering an endpoint that stays off the registry? Wrap it with @orches/x402. One wrapper installs the whole challenge, verify, respond cycle.

1import { withX402 } from "@orches/x402";
2
3app.post(
4  "/api/risk",
5  withX402(
6    async (req, res) => {
7      // payment already verified; req.x402.payerWallet is available
8      res.json(await yourBusinessLogic(req.body));
9    },
10    { price: "0.05", wallet: process.env.PROVIDER_WALLET, network: "robinhood" },
11  ),
12);

1// app/api/risk/route.ts
2import { withX402Payment } from "@orches/x402";
3
4export const POST = withX402Payment(
5  async (req, { x402 }) => Response.json({ score: 0.92, paidBy: x402.payerWallet }),
6  { price: "0.05", wallet: process.env.PROVIDER_WALLET!, network: "robinhood" },
7);

1from orches_x402 import X402Middleware
2
3X402Middleware(app, price="0.05", wallet=PROVIDER_WALLET, network="robinhood", protected_paths=["/api/risk"])

With the SDK

fetchWithPayment takes a viem wallet, settles the challenge, and replays the request. The whole exchange behind one function.

1import { fetchWithPayment } from "@orches/x402";
2import { createWalletClient, http } from "viem";
3import { privateKeyToAccount } from "viem/accounts";
4import { base } from "viem/chains";
5
6const wallet = createWalletClient({
7  account: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`),
8  chain: base,
9  transport: http(),
10});
11
12const res = await fetchWithPayment(
13  "https://fletch402.xyz/api/services/{id}/call",
14  { method: "POST", body: JSON.stringify({ input: { address: "0x…" } }) },
15  wallet,
16);
17console.log(await res.json());

Through MCP

Add @orches/mcp and the model performs provider selection itself: browse, compare price, settle, call. Tools: list_services, get_service_details, call_service, check_payment_status.

The config below is the standard MCP format. Drop it into your client's config file (claude_desktop_config.json, Codex's MCP settings, or Antigravity's mcp_config.json).

1{
2  "mcpServers": {
3    "orches": {
4      "command": "npx",
5      "args": ["-y", "@orches/mcp@latest"],
6      "env": {
7        "ORCHES_API_BASE": "https://fletch402.xyz",
8        "ORCHES_NETWORK": "robinhood",
9        "ORCHES_PRIVATE_KEY": "0xYourAgentWalletKey"
10      }
11    }
12  }
13}

ORCHES_PRIVATE_KEY is required only for paid call_servicecalls; discovery works read-only without it. Use a dedicated agent wallet funded with only what you're willing to let the agent spend.

Raw HTTP

No SDK in the path? Drive the two round trips yourself:

1// 1. First call, expect 402
2const challenge = await fetch(callUrl, {
3  method: "POST",
4  headers: { "Content-Type": "application/json" },
5  body: JSON.stringify({ input }),
6});
7const { payment } = await challenge.json(); // { payTo, amountAtomic, network, ... }
8
9// 2. Transfer USDG(payment.payTo, payment.amountAtomic) on Robinhood Chain -> txHash
10
11// 3. Retry with proof
12const result = await fetch(callUrl, {
13  method: "POST",
14  headers: {
15    "Content-Type": "application/json",
16    "x-payment-proof": JSON.stringify({ txHash, payerWallet }),
17  },
18  body: JSON.stringify({ input }),
19});

Registry routes

The registry an agent reads before it selects anything, at three canonical routes:

The record format is an open, versioned standard. Check your own against it with @orches/validate-spec.

Record shape

Every record is self-describing, so provider selection, price comparison, and invocation all resolve in a single pass. The fields that matter:

1{
2  "id": "cmpjq32i80002qaimfb2fezm4",
3  "slug": "wallet-risk",
4  "name": "Wallet Risk Score API",
5  "capabilities": ["risk", "wallet", "security"],
6  "price": { "amount": "0.05", "currency": "USDG" },
7  "network": "robinhood",
8  "endpoint": "https://fletch402.xyz/api/services/{id}/call",
9  "inputSchema":  { /* JSON Schema */ },
10  "outputSchema": { /* JSON Schema */ },
11  "reliability": {
12    "verified": true,
13    "successRate": 99.5,
14    "averageLatencyMs": 132,
15    "totalCalls": 2059
16  },
17  "playgroundUrl": "https://fletch402.xyz/playground/wallet-risk"
18}

Status codes

Rate limits

All call endpoints: 10 requests per 10 seconds per IP. On a 429, response headers tell you when to retry:

1X-RateLimit-Remaining: 0
2X-RateLimit-Reset: 1717056123000

Repositories

Agent system prompt

Drop this into a system prompt and the model can transact on the coordination layer:

1You are an AI assistant that can call financial services on Orches.
21. Discover services at https://fletch402.xyz/api/agent/services.
32. Read inputSchema and build a valid request body.
43. Call the service's call endpoint. If HTTP 402, read the payment object.
54. Transfer USDG to payment.payTo on Robinhood Chain. Capture the txHash.
65. Retry with x-payment-proof: {"txHash":"0x...","payerWallet":"0x..."}.
76. Return the provider response to the user.
8
9Never expose private keys. Validate output before irreversible actions.
10Payment requirements expire after 10 min - never reuse a txHash.