@arcpaylabs/somnia-x402-agent-starter 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Sammarfo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this starter kit and associated documentation files (the "Starter Kit"), to deal
+in the Starter Kit without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Starter Kit, and to permit persons to whom the Starter Kit is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Starter Kit.
+
+THE STARTER KIT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE STARTER KIT OR THE USE OR OTHER DEALINGS IN
+THE STARTER KIT.

package/README.md

@@ -0,0 +1,45 @@
+# ArcPay Somnia x402 Agent Starter
+
+This starter shows how a developer can integrate with ArcPay's live Somnia x402 server.
+
+It covers:
+
+- reading a payment quote
+- requesting a protected agent resource
+- checking HTTP 402 requirements
+- verifying an order id
+- deriving the agent id locally
+
+It does not hold private keys by default. Wallet payment is intentionally left to your app or operator wallet.
+
+## Setup
+
+```bash
+npm install
+cp src/env.example .env
+```
+
+## Commands
+
+```bash
+node src/agent-client.mjs quote research-agent
+node src/agent-client.mjs locked research-agent
+node src/agent-client.mjs verify 0xORDER_ID research-agent
+node src/agent-client.mjs unlock research-agent 0xORDER_ID
+node src/agent-client.mjs agent-id research-agent
+```
+
+## Live Server
+
+```text
+https://x402.20.208.46.195.nip.io
+```
+
+## Payment Flow
+
+1. `quote` the agent slug.
+2. Create an order in `AgentOrderBook` with the quoted `agentId`, `requestUri`, and `amountWei`.
+3. Provider fulfills the order.
+4. `unlock` the resource with `orderId`.
+
+See the main docs at `../../mintlify/x402-agent-payments.mdx`.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@arcpaylabs/somnia-x402-agent-starter",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Starter client for integrating with ArcPay Somnia x402 paid agent endpoints.",
+  "license": "MIT",
+  "type": "module",
+  "author": "Henry Sammarfo <jasonneil4040@gmail.com>",
+  "homepage": "https://arcpay-somnia.vercel.app/docs/x402-agent-payments",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArcPayLabs/arcpay-somnia.git",
+    "directory": "starter-kits/somnia-x402-agent"
+  },
+  "bin": {
+    "arcpay-somnia-x402-agent": "src/agent-client.mjs"
+  },
+  "files": [
+    "README.md",
+    "LICENSE.md",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "quote": "node src/agent-client.mjs quote research-agent",
+    "locked": "node src/agent-client.mjs locked research-agent",
+    "agent-id": "node src/agent-client.mjs agent-id research-agent",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.7",
+    "ethers": "^6.13.5"
+  },
+  "overrides": {
+    "ws": "^8.20.1"
+  }
+}

package/src/agent-client.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { id } from "ethers";
+
+const serverUrl = (process.env.ARCPAY_X402_SERVER_URL || "https://x402.20.208.46.195.nip.io").replace(/\/+$/, "");
+const [, , command = "help", arg1 = "research-agent", arg2 = "research-agent"] = process.argv;
+
+async function main() {
+  if (command === "quote") {
+    const body = await getJson(`/x402/payment-requirements/${encodeURIComponent(arg1)}`);
+    print(body);
+  } else if (command === "locked") {
+    const response = await fetch(`${serverUrl}/agent/${encodeURIComponent(arg1)}/work`);
+    const body = await response.json();
+    print({ status: response.status, body });
+  } else if (command === "verify") {
+    const body = await postJson("/x402/verify", { orderId: arg1, agentSlug: arg2 });
+    print(body);
+  } else if (command === "unlock") {
+    const body = await getJson(`/agent/${encodeURIComponent(arg1)}/work?orderId=${encodeURIComponent(arg2)}`);
+    print(body);
+  } else if (command === "agent-id") {
+    console.log(id(arg1));
+  } else {
+    console.log([
+      "ArcPay Somnia x402 Agent Starter",
+      "",
+      "Commands:",
+      "  node src/agent-client.mjs quote <agentSlug>",
+      "  node src/agent-client.mjs locked <agentSlug>",
+      "  node src/agent-client.mjs verify <orderId> <agentSlug>",
+      "  node src/agent-client.mjs unlock <agentSlug> <orderId>",
+      "  node src/agent-client.mjs agent-id <agentSlug>",
+    ].join("\n"));
+  }
+}
+
+async function getJson(path) {
+  const response = await fetch(`${serverUrl}${path}`);
+  const body = await response.json();
+  if (!response.ok && response.status !== 402) throw new Error(body.error || `HTTP ${response.status}`);
+  return body;
+}
+
+async function postJson(path, payload) {
+  const response = await fetch(`${serverUrl}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const body = await response.json();
+  if (!response.ok) throw new Error(body.error || `HTTP ${response.status}`);
+  return body;
+}
+
+function print(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/src/env.example

@@ -0,0 +1,3 @@
+ARCPAY_X402_SERVER_URL=https://x402.20.208.46.195.nip.io
+SOMNIA_RPC_URL=https://dream-rpc.somnia.network
+AGENT_ORDER_BOOK=0x6A07886d465Bd64ED3264F4e824C1dF2884a7B45