Section 01
Quickstart
Oryn is a marketplace of MCP capabilities for AI agents. Install one into your client and use it immediately.
Install deep-research into Claude Desktop:
$ npx oryn install deep-research --client claude
→ Resolving capability...
→ Verified on-chain at 0xB9a2…BAB5d
✓ Installed deep-research@1.2.0Or print the config snippet to paste manually (no file writes):
$ npx oryn install deep-research
# Add to your MCP-aware client config:
{
"mcpServers": {
"oryn-deep-research": {
"type": "http",
"url": "https://api.oryn.works/v1/skills/deep-research/call"
}
}
}Make a direct call for testing (production agents go through their MCP client):
$ npx oryn call deep-research --prompt "summarize latest base ecosystem trends"Section 02
For operators
You build AI agents. Oryn lets your agent install third-party capabilities and pay per use, with an audit trail.
>Browse the hub
Visit /browse to filter by type (skill / knowledge), category, or price. Free capabilities are tagged.
>Install into your MCP client
On any capability detail page, copy the install command. The SDK writes an entry to your client config (Claude Desktop, Cursor) or prints it for manual paste.
# Auto-write into Claude Desktop config
$ npx oryn install <slug> --client claude
# Cursor
$ npx oryn install <slug> --client cursor
# Just print the JSON
$ npx oryn install <slug>>Pay per use
When your agent calls a paid capability, the gateway returns 402 Payment Required with an x402 challenge. Your wallet signs an EIP-712 payment payload, the gateway verifies the signature against your USDC allowance, and forwards the call.
Free capabilities work end-to-end without a payment header. No wallet, no approval, no friction.
Section 03
For builders
You have an MCP server or curated dataset. Publish it to Oryn, earn USDC per call, build on-chain reputation.
>Connect your wallet
Sign in via SIWE on /build. Your wallet address becomes your builder identity. Edit your public profile from /me.
>Publish a capability
Fill the form at /build/new. On submit, your wallet signs a transaction registering the capability on CapabilityRegistry. Gas is roughly $0.01 on Base.
Required: name, slug, type, category, description, host URL, price. Host URLs pointing to private/internal IPs are rejected.
>Earn and claim
Every paid call accrues to your balance in RevenueEscrow. The protocol takes 10%. Builders earn 90% of every call.
Operator pays 1.0000 USDC
→ 0.9000 USDC → builderBalance[you]
→ 0.1000 USDC → protocolTreasuryWithdraw any time from /build. The Claim button sends RevenueEscrow.claim() from your wallet, transferring USDC to your address.
Section 04
x402 payment
The Coinbase-led open protocol for HTTP-native micropayments. We use it for per-call billing.
x402 piggybacks on HTTP 402 Payment Required, with EIP-712 signed payment payloads carried in an X-Payment header.
1. Agent calls a paid capability:
POST /v1/skills/<slug>/call
2. Gateway returns 402 with a challenge:
WWW-Authenticate: X402 realm="oryn", amount="0.0200"
3. Agent's client builds an EIP-712 payment for amount,
signs with the operator's wallet key, retries with:
X-Payment: <signed-payload>
4. Gateway verifies signature, nonce uniqueness, USDC
allowance. Forwards the call to the builder's host URL.
5. Off-chain ledger records the usage event.
Settlement worker batches per-builder accruals and
pushes them to RevenueEscrow on a schedule.Nonces are stored per-payer for replay protection. The settlement worker uses an idempotent lock-and-finalize pattern: events are locked before broadcast, finalized after on-chain confirmation, and reconciled at startup if a prior run crashed mid-flight.
Section 05
API reference
Two proxy endpoints. Both require a SIWE session cookie and, for paid capabilities, an X-Payment header.
>POST /v1/skills/:slug/call
Invoke a skill (MCP server).
curl -X POST https://api.oryn.works/v1/skills/deep-research/call \
-H "Content-Type: application/json" \
-H "Cookie: oryn_session=..." \
-H "X-Payment: <eip712-signed-payload>" \
-d '{"prompt": "..."}'>POST /v1/knowledge/:slug/query
Query a knowledge pack.
curl -X POST https://api.oryn.works/v1/knowledge/alpha-feed/query \
-H "Content-Type: application/json" \
-H "Cookie: oryn_session=..." \
-H "X-Payment: <eip712-signed-payload>" \
-d '{"prompt": "..."}'>Response shapes
// 200 OK
{
"ok": true,
"data": <upstream response>,
"costUsdc": "0.0200",
"latencyMs": 412
}
// 402 Payment Required
{
"error": "payment required",
"priceUsdc": "0.0200",
"protocol": "x402",
"version": "1"
}
// 502 Bad Gateway
{
"error": "upstream_502" |
"upstream_host_blocked" |
"upstream_timeout"
}>CLI
oryn install <slug> [--client claude|cursor|print] [--gateway URL]
oryn call <slug> --prompt "..." [--gateway URL] [--auth TOKEN]
oryn query <slug> --prompt "..." [--gateway URL] [--auth TOKEN]
oryn ping [--gateway URL]
oryn --version>Programmatic
import { OrynClient } from "oryn";
const client = new OrynClient({
gatewayUrl: "https://api.oryn.works",
authToken: process.env.ORYN_AUTH_TOKEN,
});
const result = await client.query("alpha-feed", {
prompt: "trending on base, last 24h"
});>Environment
>CapabilityRegistry
Catalog of registered capabilities. Each entry is keyed by keccak256(slug) and records the builder address, price, type, status, and metadata hash.
>RevenueEscrow
Holds USDC from paid calls. Splits 90/10 between builder and protocol on every settle(). Builders call claim() to withdraw their balance.