Sell from a Noosphere agent

The Noosphere agent has a built-in x402 seller: point it at any Docker container and it serves paid HTTP routes and MCP tools for it — 402 challenges, payment verification, settlement, and receipts all handled for you. No server code, unlike the SDK quickstart where you wire the middleware yourself.

This is independent of the Noosphere compute network: no subscriptions, no on-chain requests — just per-call x402 payments settled by the HPP facilitator directly to your wallet, with gas sponsored.

Selling requires no funds. An empty wallet works — you only ever receive.

From a free model to your first payment

About 10 minutes end-to-end, starting from a free HuggingFace model.

1. Wrap the model — one endpoint is the whole contract

POST /computation   { "input": "<raw>", ...buyer JSON }  →  { "output": "<string>" }

The agent repo's examples/hf-sentiment does this for a sentiment model in ~30 lines of FastAPI (the interface is Noosphere's standard container contract):

git clone https://github.com/hpp-io/noosphere-agent-js.git
cd noosphere-agent-js && npm install
cd examples/hf-sentiment
docker build -t hf-sentiment:latest .

2. Configure the seller

Add the container and a service to the agent's config.json:

{
  "containers": [
    { "id": "hf-sentiment", "name": "hf-sentiment",
      "image": "hf-sentiment:latest", "port": "8090" }
  ],
  "x402Seller": {
    "enabled": true,
    "payTo": "0xYourReceivingWallet",        // where the USDC.e lands
    "facilitators": { "eip155:181228": "https://facilitator-sepolia.hpp.io" },
    "defaultAsset": {
      "eip155:181228": {
        "address": "0x401eCb1D350407f13ba348573E5630B83638E30D",
        "extra": { "name": "Bridged USDC", "version": "2" }
      }
    },
    "services": [
      {
        "name": "sentiment",                 // → POST /paid/compute/sentiment
        "containerId": "hf-sentiment",
        "settlement": "direct",
        "network": "eip155:181228",
        "schemes": ["exact"],
        "x402Price": "5000",                 // atomic USDC.e → $0.005 per call
        "inputSchema": {                     // validated BEFORE payment
          "type": "object", "required": ["text"],
          "properties": { "text": { "type": "string" } }
        },
        "receipt": true,
        "description": "Sentiment analysis, per call"
      }
    ]
  }
}

Mainnet: use eip155:190415 with https://facilitator.hpp.io — see Networks & Token.

3. Run and earn

npm run init          # creates the agent's keystore (its signing key)
npm run agent         # paid routes live on :4000

Payments land at x402Seller.payTo (falling back to chain.wallet.paymentAddress if unset) — the seller refuses to start with neither configured.

When a buyer calls POST /paid/compute/sentiment with a valid payment:

{
  "jobId": "6b2c1e5e-…",
  "service": "sentiment",
  "output": "POSITIVE (0.9998)",
  "receipt": { "settlement": { "transaction": "0xb83a…" }, "…": "…" }
}

…and the USDC.e is already in your wallet. Track earnings in the agent dashboard (npm run dev → the x402 Seller tab) or GET /api/seller/summary.

What buyers can rely on

• Invalid input → HTTP 400 before payment. Your inputSchema gates every request; nobody pays for a call your container can't serve.
• Compute failure → no charge. Settlement happens only after a successful response.
• You never custody funds. Payment moves buyer → your wallet directly on-chain; the agent holds no spending keys.

Execution receipts

With "receipt": true the response embeds a deterministic receipt binding the advertised price, the on-chain settlement transaction, and sha256 hashes of the exact request and result — verifiable proof of what the payment bought.

How buyers reach you

• HTTP — any x402 client; see the buyer quickstart.
• MCP — every service doubles as a compute_<service> tool at /mcp (StreamableHTTP) and /mcp/sse; AI agents pay through the x402 MCP bridge. A failed tool call cancels the payment.
• Explorer — after your first settled sale, the x402 Explorer indexes your service automatically. To be listed before the first sale, register from the config:

"x402Seller": {
  "discovery": {
    "enabled": true,
    "apiUrl": "https://x402-explorer.hpp.io",
    "publicBaseUrl": "https://your-public-host.example.com",
    "register": true          // signed by the keystore wallet — payTo must equal it
  }
}

publicBaseUrl (your domain or tunnel) is your responsibility in production. New listings start pending and become publicly visible once approved — see selling on the explorer.

For local testing only, "demoTunnel": true auto-starts an ephemeral Cloudflare Quick Tunnel. Never use it in production.

Pricing

x402Price is in atomic USDC.e (6 decimals): "1000" = $0.001, "5000" = $0.005, "10000" = $0.01 — charged per call, on success only.

Operating tips

Symptom	Fix
Buyer gets 400 before paying	Working as intended — their body failed your inputSchema
Buyer gets 402 repeatedly	Their wallet lacks USDC.e on the right network, or their client doesn't speak the advertised scheme
Buyer gets 502, not charged	Your container failed — docker logs noosphere-<container-name>
Explorer registration skipped (log warning)	payTo must be the agent's keystore wallet to sign — or rely on auto-listing after the first sale
demoTunnel fails	cloudflared not installed — and remember it's test-only