@agentlayer.tech/wallet 0.1.100 → 0.1.102

package/connectors/examples/reference-crypto-data/Dockerfile

@@ -0,0 +1,21 @@
+FROM node:24-alpine AS build
+
+WORKDIR /app/connectors
+COPY connectors/package.json connectors/package-lock.json ./
+COPY connectors/sdk-typescript ./sdk-typescript
+COPY connectors/conformance ./conformance
+COPY connectors/templates/read-only ./templates/read-only
+COPY connectors/examples/reference-crypto-data ./examples/reference-crypto-data
+RUN npm ci
+RUN npm run build --workspace @agentlayer.tech/connector-sdk
+RUN npm run build --workspace @agentlayer.tech/reference-crypto-data-connector
+
+FROM node:24-alpine
+
+ENV NODE_ENV=production
+WORKDIR /app/connectors
+COPY --from=build --chown=node:node /app/connectors /app/connectors
+USER node
+EXPOSE 3000
+
+CMD ["npm", "run", "start", "--workspace", "@agentlayer.tech/reference-crypto-data-connector"]

package/connectors/examples/reference-crypto-data/README.md

@@ -0,0 +1,51 @@
+# AgentLayer crypto-data reference connector
+
+This is a neutral, read-only reference implementation for Connector Protocol
+v1. It exposes public spot-price and asset-metadata tools. It does not receive a
+wallet address, construct transactions, make payments, sign, or broadcast.
+
+The upstream is Coinbase Exchange's public market-data API. The reference uses
+the documented public ticker and currency endpoints and requires no API key:
+
+- https://docs.cdp.coinbase.com/api-reference/exchange-api/rest-api/products/get-product-ticker
+- https://docs.cdp.coinbase.com/api-reference/exchange-api/rest-api/currencies/get-a-currency
+
+Run locally:
+
+```bash
+npm ci --prefix connectors
+npm run build --workspace @agentlayer.tech/reference-crypto-data-connector --prefix connectors
+npm run start --workspace @agentlayer.tech/reference-crypto-data-connector --prefix connectors
+```
+
+The reviewed beta deployment is available at
+`https://reference-crypto-data-production.up.railway.app`. Its manifest is
+already pinned to that exact HTTPS endpoint. Re-run its live conformance check
+after any immutable version release:
+
+```bash
+cd connectors
+node conformance/dist/cli.js \
+  --manifest examples/reference-crypto-data/connector.json \
+  --fixture examples/reference-crypto-data/conformance.json \
+  --endpoint https://reference-crypto-data-production.up.railway.app
+```
+
+## Railway deployment
+
+Deploy this directory as one stateless service in a new, isolated Railway
+project. Keep the repository root as the Docker build context and point the
+service Dockerfile at
+`connectors/examples/reference-crypto-data/Dockerfile` (for a root deployment,
+set Railway's `RAILWAY_DOCKERFILE_PATH` service variable to that value).
+Configure the Railway deployment health-check path as `/healthz` with a
+10-second timeout and an `ON_FAILURE` restart policy. The service needs no
+application variables, volume, database, wallet material, or connection to the
+AgentLayer provider gateway.
+
+After Railway generates the public domain:
+
+1. update `connector.json` to that exact HTTPS URL;
+2. redeploy the immutable manifest version;
+3. run both live conformance and wallet invocation tests;
+4. install the reviewed manifest with `wallet connectors install ... --enable --yes`.

package/connectors/examples/reference-crypto-data/conformance.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "tools": {
+    "get_spot_price": {
+      "arguments": { "base": "BTC", "quote": "USD" }
+    },
+    "get_asset_metadata": {
+      "arguments": { "asset": "BTC" }
+    }
+  }
+}

package/connectors/examples/reference-crypto-data/connector.json

@@ -0,0 +1,95 @@
+{
+  "schema_version": 1,
+  "id": "tech.agentlayer.crypto-data",
+  "name": "AgentLayer Crypto Data Reference",
+  "version": "0.1.0-beta.1",
+  "publisher": {
+    "id": "agentlayer",
+    "name": "AgentLayer",
+    "url": "https://agentlayer.tech"
+  },
+  "agentlayer": {
+    "protocol_version": 1,
+    "runtime_range": ">=0.1.101"
+  },
+  "trust": "community_read_only",
+  "transport": {
+    "type": "https",
+    "url": "https://reference-crypto-data-production.up.railway.app",
+    "timeout_ms": 10000
+  },
+  "permissions": {
+    "wallet_address": false,
+    "transaction_intents": false,
+    "network_hosts": ["api.exchange.coinbase.com"]
+  },
+  "tools": [
+    {
+      "name": "get_spot_price",
+      "description": "Get a public spot ticker snapshot for a crypto/fiat or crypto/crypto product.",
+      "read_only": true,
+      "risk_level": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "base": { "type": "string", "pattern": "^[A-Za-z0-9]{2,12}$" },
+          "quote": { "type": "string", "pattern": "^[A-Za-z0-9]{2,12}$" }
+        },
+        "required": ["base", "quote"],
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "type": "object",
+        "properties": {
+          "product_id": { "type": "string", "minLength": 5, "maxLength": 25 },
+          "base_currency": { "type": "string", "minLength": 2, "maxLength": 12 },
+          "quote_currency": { "type": "string", "minLength": 2, "maxLength": 12 },
+          "price": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "bid": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "ask": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "last_size": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "volume_24h": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "observed_at": { "type": "string", "minLength": 10, "maxLength": 64 },
+          "source": { "const": "coinbase_exchange" }
+        },
+        "required": [
+          "product_id", "base_currency", "quote_currency", "price", "bid", "ask",
+          "last_size", "volume_24h", "observed_at", "source"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "get_asset_metadata",
+      "description": "Get public metadata and network status for a currency code.",
+      "read_only": true,
+      "risk_level": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "asset": { "type": "string", "pattern": "^[A-Za-z0-9]{2,12}$" }
+        },
+        "required": ["asset"],
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "type": "object",
+        "properties": {
+          "asset": { "type": "string", "minLength": 2, "maxLength": 12 },
+          "name": { "type": "string", "minLength": 1, "maxLength": 120 },
+          "status": { "type": "string", "minLength": 1, "maxLength": 40 },
+          "type": { "type": ["string", "null"], "maxLength": 40 },
+          "min_size": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "max_precision": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "default_network": { "type": ["string", "null"], "maxLength": 80 },
+          "source": { "const": "coinbase_exchange" }
+        },
+        "required": [
+          "asset", "name", "status", "type", "min_size", "max_precision",
+          "default_network", "source"
+        ],
+        "additionalProperties": false
+      }
+    }
+  ]
+}

package/connectors/examples/reference-crypto-data/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@agentlayer.tech/reference-crypto-data-connector",
+  "version": "0.1.0-beta.1",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "check": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@agentlayer.tech/connector-sdk": "0.1.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  }
+}

package/connectors/examples/reference-crypto-data/railway.toml

@@ -0,0 +1,9 @@
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "connectors/examples/reference-crypto-data/Dockerfile"
+
+[deploy]
+healthcheckPath = "/healthz"
+healthcheckTimeout = 10
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 3

package/connectors/examples/reference-crypto-data/src/connector.ts

@@ -0,0 +1,137 @@
+import { readFileSync } from "node:fs";
+
+import {
+  ConnectorSdkError,
+  defineReadOnlyConnector,
+  type ConnectorManifest,
+  type JsonObject,
+} from "@agentlayer.tech/connector-sdk";
+
+const manifest = JSON.parse(
+  readFileSync(new URL("../connector.json", import.meta.url), "utf8")
+) as ConnectorManifest;
+const UPSTREAM_ORIGIN = "https://api.exchange.coinbase.com";
+const MAX_UPSTREAM_BYTES = 256 * 1024;
+const ASSET_PATTERN = /^[A-Z0-9]{2,12}$/;
+
+function assetCode(value: unknown, field: string): string {
+  const normalized = String(value ?? "").trim().toUpperCase();
+  if (!ASSET_PATTERN.test(normalized)) {
+    throw new ConnectorSdkError("invalid_arguments", `${field} must be a 2-12 character asset code.`);
+  }
+  return normalized;
+}
+
+function requiredString(value: unknown, field: string, maxLength = 120): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+    throw new ConnectorSdkError("invalid_upstream", `Upstream ${field} is invalid.`, 502);
+  }
+  return value;
+}
+
+function optionalString(value: unknown, maxLength = 80): string | null {
+  return typeof value === "string" && value.length > 0 && value.length <= maxLength ? value : null;
+}
+
+async function readObject(response: Response): Promise<Record<string, unknown>> {
+  const contentLength = Number(response.headers.get("content-length") ?? 0);
+  if (Number.isFinite(contentLength) && contentLength > MAX_UPSTREAM_BYTES) {
+    throw new ConnectorSdkError("upstream_too_large", "Upstream response exceeds the size limit.", 502);
+  }
+  if (!response.body) {
+    throw new ConnectorSdkError("invalid_upstream", "Upstream response body is missing.", 502);
+  }
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_UPSTREAM_BYTES) {
+      await reader.cancel();
+      throw new ConnectorSdkError("upstream_too_large", "Upstream response exceeds the size limit.", 502);
+    }
+    chunks.push(value);
+  }
+  let payload: unknown;
+  try {
+    payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new ConnectorSdkError("invalid_upstream", "Upstream response is not valid JSON.", 502);
+  }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new ConnectorSdkError("invalid_upstream", "Upstream response root is invalid.", 502);
+  }
+  return payload as Record<string, unknown>;
+}
+
+async function fetchObject(
+  path: string,
+  fetchImpl: typeof fetch
+): Promise<Record<string, unknown>> {
+  const url = new URL(path, UPSTREAM_ORIGIN);
+  if (url.origin !== UPSTREAM_ORIGIN || !manifest.permissions.network_hosts.includes(url.hostname)) {
+    throw new ConnectorSdkError("upstream_not_allowed", "Upstream host is not allowlisted.", 500);
+  }
+  const response = await fetchImpl(url, {
+    headers: {
+      accept: "application/json",
+      "cache-control": "no-cache",
+      "user-agent": "AgentLayer-Reference-Connector/0.1",
+    },
+    redirect: "error",
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!response.ok) {
+    throw new ConnectorSdkError("upstream_http_error", `Upstream returned HTTP ${response.status}.`, 502);
+  }
+  return readObject(response);
+}
+
+export function createCryptoDataConnector(fetchImpl: typeof fetch = fetch) {
+  return defineReadOnlyConnector({
+    manifest,
+    responseTtlSeconds: 30,
+    handlers: {
+      async get_spot_price(arguments_: JsonObject): Promise<JsonObject> {
+        const base = assetCode(arguments_.base, "base");
+        const quote = assetCode(arguments_.quote, "quote");
+        const productId = `${base}-${quote}`;
+        const ticker = await fetchObject(`/products/${encodeURIComponent(productId)}/ticker`, fetchImpl);
+        return {
+          product_id: productId,
+          base_currency: base,
+          quote_currency: quote,
+          price: requiredString(ticker.price, "price", 80),
+          bid: requiredString(ticker.bid, "bid", 80),
+          ask: requiredString(ticker.ask, "ask", 80),
+          last_size: requiredString(ticker.size, "size", 80),
+          volume_24h: requiredString(ticker.volume, "volume", 80),
+          observed_at: requiredString(ticker.time, "time", 64),
+          source: "coinbase_exchange",
+        };
+      },
+      async get_asset_metadata(arguments_: JsonObject): Promise<JsonObject> {
+        const asset = assetCode(arguments_.asset, "asset");
+        const currency = await fetchObject(`/currencies/${encodeURIComponent(asset)}`, fetchImpl);
+        const details =
+          currency.details && typeof currency.details === "object" && !Array.isArray(currency.details)
+            ? (currency.details as Record<string, unknown>)
+            : {};
+        return {
+          asset: requiredString(currency.id, "id", 12),
+          name: requiredString(currency.name, "name"),
+          status: requiredString(currency.status, "status", 40),
+          type: optionalString(details.type, 40),
+          min_size: requiredString(currency.min_size, "min_size", 80),
+          max_precision: requiredString(currency.max_precision, "max_precision", 80),
+          default_network: optionalString(currency.default_network, 80),
+          source: "coinbase_exchange",
+        };
+      },
+    },
+  });
+}
+
+export const connector = createCryptoDataConnector();

package/connectors/examples/reference-crypto-data/src/server.ts

@@ -0,0 +1,13 @@
+import { startConnectorServer } from "@agentlayer.tech/connector-sdk";
+
+import { connector } from "./connector.js";
+
+const server = await startConnectorServer(connector);
+console.log(
+  JSON.stringify({
+    event: "connector_started",
+    connector_id: connector.manifest.id,
+    connector_version: connector.manifest.version,
+    address: server.address(),
+  })
+);

package/connectors/examples/reference-crypto-data/test/connector.test.mjs

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createCryptoDataConnector } from "../dist/connector.js";
+
+function request(connector, tool, arguments_) {
+  return {
+    protocol_version: 1,
+    request_id: `reference-${tool}`,
+    connector: { id: connector.manifest.id, version: connector.manifest.version },
+    tool,
+    arguments: arguments_,
+    context: {},
+  };
+}
+
+test("normalizes public ticker data without wallet context", async () => {
+  const connector = createCryptoDataConnector(async (url, options) => {
+    assert.equal(url.href, "https://api.exchange.coinbase.com/products/BTC-USD/ticker");
+    assert.equal(options.redirect, "error");
+    assert.equal(options.headers["cache-control"], "no-cache");
+    return new Response(
+      JSON.stringify({
+        price: "78000.12",
+        bid: "78000.11",
+        ask: "78000.13",
+        size: "0.01",
+        volume: "1234.5",
+        time: "2026-08-27T00:00:00Z",
+      }),
+      { status: 200, headers: { "content-type": "application/json" } }
+    );
+  });
+  const response = await connector.invoke(request(connector, "get_spot_price", {
+    base: "btc",
+    quote: "usd",
+  }));
+  assert.deepEqual(response.result, {
+    product_id: "BTC-USD",
+    base_currency: "BTC",
+    quote_currency: "USD",
+    price: "78000.12",
+    bid: "78000.11",
+    ask: "78000.13",
+    last_size: "0.01",
+    volume_24h: "1234.5",
+    observed_at: "2026-08-27T00:00:00Z",
+    source: "coinbase_exchange",
+  });
+});
+
+test("normalizes public asset metadata", async () => {
+  const connector = createCryptoDataConnector(async (url) => {
+    assert.equal(url.href, "https://api.exchange.coinbase.com/currencies/BTC");
+    return new Response(
+      JSON.stringify({
+        id: "BTC",
+        name: "Bitcoin",
+        min_size: "0.00000001",
+        max_precision: "0.00000001",
+        status: "online",
+        default_network: "bitcoin",
+        details: { type: "crypto" },
+      }),
+      { status: 200, headers: { "content-type": "application/json" } }
+    );
+  });
+  const response = await connector.invoke(request(connector, "get_asset_metadata", { asset: "btc" }));
+  assert.deepEqual(response.result, {
+    asset: "BTC",
+    name: "Bitcoin",
+    status: "online",
+    type: "crypto",
+    min_size: "0.00000001",
+    max_precision: "0.00000001",
+    default_network: "bitcoin",
+    source: "coinbase_exchange",
+  });
+});
+
+test("rejects oversized and malformed upstream responses", async () => {
+  const oversized = createCryptoDataConnector(async () =>
+    new Response("{}", { status: 200, headers: { "content-length": "999999" } })
+  );
+  await assert.rejects(
+    oversized.invoke(request(oversized, "get_asset_metadata", { asset: "BTC" })),
+    /size limit/
+  );
+
+  const malformed = createCryptoDataConnector(async () =>
+    new Response("not-json", { status: 200, headers: { "content-type": "application/json" } })
+  );
+  await assert.rejects(
+    malformed.invoke(request(malformed, "get_asset_metadata", { asset: "BTC" })),
+    /not valid JSON/
+  );
+});

package/connectors/examples/reference-crypto-data/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}