agentex-creator-sdk 1.0.0

package/dist/packages/workflow/src/registry.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import type { AnyEvidenceItem } from '../../contracts/src/kinds.js';
+import { type WorkflowManifest, type WorkflowToolDeclaration } from '../../contracts/src/workflow.js';
+import type { RpcTransport } from '../../research/src/index.js';
+/**
+ * Deterministic tool interface implemented by packages/tools (`TOOL_REGISTRY`). The engine depends only on this shape.
+ * Tools receive a policy-guarded transport: every request needs a prior `beforeRpc` permit and stays inside the version's
+ * address/domain scope, and `onEvidence` accepts only envelopes matching responses the transport actually returned.
+ */
+export interface ToolContext {
+    chain: string;
+    signal: AbortSignal;
+    transport: RpcTransport;
+    beforeRpc(op: {
+        method: string;
+        step: string;
+    }): Promise<void>;
+    onEvidence(evidence: AnyEvidenceItem): Promise<void>;
+    /**
+     * Adds addresses the tool derived deterministically from in-scope values (for example a Solana program-derived address of the input mint) to
+     * the run's address scope. Honoured only for `input-derived` versions, exactly like addresses in captured evidence; absent outside workflows.
+     */
+    deriveAddresses?(addresses: readonly string[]): void;
+}
+export interface ToolDefinition<I, O> {
+    id: string;
+    version: string;
+    capability: 'evm.read' | 'solana.read' | 'http.read';
+    chains: readonly string[];
+    inputSchema: z.ZodType<I>;
+    outputSchema: z.ZodType<O>;
+    maximumCalls: number;
+    /** Fixed platform contracts (lowercase EVM or base58 Solana addresses) this tool may read on each chain, reviewed with the tool. In scope for this tool only. */
+    curatedAddresses?: Readonly<Record<string, readonly string[]>>;
+    /** One-line description for creators and the workflow assistant. */
+    description?: string;
+    execute(input: I, ctx: ToolContext): Promise<{
+        output: O;
+        evidenceIds: string[];
+    }>;
+}
+export type WorkflowToolRegistry = ReadonlyMap<string, ToolDefinition<unknown, unknown>>;
+/** Registry lookup by `id@version` key, or by matching id and version on any entry. */
+export declare function resolveTool(registry: WorkflowToolRegistry, declaration: Pick<WorkflowToolDeclaration, 'id' | 'version'>): ToolDefinition<unknown, unknown> | undefined;
+/** Rejects impossible registry combinations before any version exists: unknown tools, capability or chain mismatches, raised ceilings, unknown arguments and output paths. */
+export declare function validateWorkflowTools(manifest: WorkflowManifest, registry: WorkflowToolRegistry): {
+    path: string;
+    message: string;
+}[];
+/** Public catalog of approved tools for editors and assistants. Schemas are rendered as JSON Schema; unrepresentable parts become open. */
+export declare function describeToolRegistry(registry: WorkflowToolRegistry): {
+    curatedAddresses?: Readonly<Record<string, readonly string[]>> | undefined;
+    description?: string | undefined;
+    id: string;
+    version: string;
+    capability: "evm.read" | "http.read" | "solana.read";
+    chains: string[];
+    maximumCalls: number;
+    inputSchema: {};
+    outputSchema: {};
+}[];

package/dist/packages/workflow/src/registry.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { workflowBindings } from '../../contracts/src/workflow.js';
+/** Registry lookup by `id@version` key, or by matching id and version on any entry. */
+export function resolveTool(registry, declaration) {
+    const keyed = registry.get(`${declaration.id}@${declaration.version}`) ?? registry.get(declaration.id);
+    if (keyed?.id === declaration.id && keyed.version === declaration.version)
+        return keyed;
+    for (const tool of registry.values())
+        if (tool.id === declaration.id && tool.version === declaration.version)
+            return tool;
+    return undefined;
+}
+const objectShape = (schema) => schema instanceof z.ZodObject ? schema.shape : null;
+/** Rejects impossible registry combinations before any version exists: unknown tools, capability or chain mismatches, raised ceilings, unknown arguments and output paths. */
+export function validateWorkflowTools(manifest, registry) {
+    const issues = [];
+    const definitions = new Map();
+    manifest.tools.forEach((tool, position) => {
+        const definition = resolveTool(registry, tool);
+        const path = `tools.${position}`;
+        if (!definition) {
+            issues.push({ path, message: `Tool ${tool.id}@${tool.version} is not in the approved tool registry` });
+            return;
+        }
+        definitions.set(tool.id, definition);
+        if (definition.capability !== tool.capability)
+            issues.push({ path, message: `Tool ${tool.id} has capability ${definition.capability}, not ${tool.capability}` });
+        for (const chain of tool.chains)
+            if (!definition.chains.includes(chain))
+                issues.push({ path, message: `Tool ${tool.id} does not support ${chain}` });
+        if (tool.maximumCalls > definition.maximumCalls)
+            issues.push({ path, message: `Tool ${tool.id} allows at most ${definition.maximumCalls} calls` });
+    });
+    manifest.workflow.forEach((node, position) => {
+        if (node.type === 'tool') {
+            const definition = definitions.get(node.tool);
+            const shape = definition ? objectShape(definition.inputSchema) : null;
+            if (shape) {
+                for (const key of Object.keys(node.arguments))
+                    if (!Object.hasOwn(shape, key))
+                        issues.push({ path: `workflow.${position}.arguments`, message: `Tool ${node.tool} has no argument ${key}` });
+                for (const [key, field] of Object.entries(shape))
+                    if (!Object.hasOwn(node.arguments, key) && !field.safeParse(undefined).success)
+                        issues.push({ path: `workflow.${position}.arguments`, message: `Tool ${node.tool} needs argument ${key}` });
+            }
+        }
+        for (const binding of workflowBindings(node)) {
+            if (binding.source !== 'node' || !binding.path)
+                continue;
+            const target = manifest.workflow.find((item) => item.id === binding.nodeId);
+            if (target?.type !== 'tool')
+                continue;
+            const definition = definitions.get(target.tool);
+            const shape = definition ? objectShape(definition.outputSchema) : null;
+            const head = binding.path.split('.')[0];
+            if (shape && !Object.hasOwn(shape, head))
+                issues.push({ path: `workflow.${position}`, message: `Tool ${target.tool} output has no field ${head}` });
+        }
+    });
+    return issues;
+}
+/** Public catalog of approved tools for editors and assistants. Schemas are rendered as JSON Schema; unrepresentable parts become open. */
+export function describeToolRegistry(registry) {
+    const json = (schema) => { try {
+        return z.toJSONSchema(schema, { unrepresentable: 'any', io: 'input' });
+    }
+    catch {
+        return {};
+    } };
+    const seen = new Set();
+    return [...registry.values()].filter((tool) => { const key = `${tool.id}@${tool.version}`; if (seen.has(key))
+        return false; seen.add(key); return true; })
+        .map((tool) => ({ id: tool.id, version: tool.version, capability: tool.capability, chains: [...tool.chains], maximumCalls: tool.maximumCalls, inputSchema: json(tool.inputSchema), outputSchema: json(tool.outputSchema),
+        ...(tool.description ? { description: tool.description } : {}), ...(tool.curatedAddresses ? { curatedAddresses: structuredClone(tool.curatedAddresses) } : {}) }))
+        .sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}

package/examples/README.md

@@ -0,0 +1,34 @@
+# Examples
+
+## Buyer (TypeScript, ESM)
+
+Install the package and `tsx` (or run the files with Node 22.18+ type stripping), then set `AGENTEX_API_KEY` to a key from
+<https://agentex.sh/developers>. Every example quotes first and spends only after an explicit consent step.
+
+| File | What it shows |
+| --- | --- |
+| `quickstart.mts` | SOL: list agents, quote, accept with the contract hash, poll, print findings with their evidence, sources and the receipt |
+| `pay-with-usdc.mts` | USDC on Solana with the one-call `research()` helper and a `maxDebitAtomic` consent bound |
+| `pay-with-eth-robinhood.mts` | ETH on Robinhood Chain with an `approve(quote)` consent callback |
+| `cli-usage.sh` | The `agentex-buyer` CLI end to end |
+
+```sh
+npm install agentex-creator-sdk tsx
+cp node_modules/agentex-creator-sdk/examples/quickstart.mts .
+AGENTEX_API_KEY=agx_live_... npx tsx quickstart.mts
+```
+
+## Creator: Base token metadata and proxy controls
+
+`focused-researcher.json` is an importable **manifest**, authored using the SDK. It selects Base, required ERC-20 metadata/bytecode, and the three standard EIP-1967 proxy slots. It intentionally skips the optional `owner()` probe and states that omission in reports. The 16-call ceiling includes room beyond its 11-call nominal fresh run, but never gives each retry a separate allowance.
+
+```sh
+npx agentex validate --file node_modules/agentex-creator-sdk/examples/focused-researcher.json
+npx agentex test --file node_modules/agentex-creator-sdk/examples/focused-researcher.json
+npx agentex estimate --file node_modules/agentex-creator-sdk/examples/focused-researcher.json
+npx agentex pack --file node_modules/agentex-creator-sdk/examples/focused-researcher.json --out focused-package.json
+```
+
+After authenticated import and the normal server test/review steps, a buyer supplies an ordinary input such as Base WETH at `0x4200000000000000000000000000000000000006` (`fixtures/base-weth-input.json`). The manifest accepts another supported address as input; it is not hard-coded to WETH. Address labels are not issuer authentication, and empty slots do not establish safety or immutability. Nothing in this example requests a trade or transaction.
+
+The local test suite uses synthetic fixtures only. A separate server creator test requires configured Base RPC coverage; actual provider cost remains unpriced. Buyer execution uses the server quote and consent flow, with its own disclosed fees and coverage.

package/examples/cli-usage.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env sh
+# AGENTEX buyer CLI walkthrough (agentex-buyer ships with agentex-creator-sdk). Output is JSON on stdout; the key is never printed.
+# PowerShell: $env:AGENTEX_API_KEY = 'agx_live_...' and the same commands.
+set -eu
+
+export AGENTEX_API_KEY="${AGENTEX_API_KEY:?create a key at https://agentex.sh/developers}"
+# export AGENTEX_API_ORIGIN=https://agentex.sh   # the default
+# export AGENTEX_ASSET=sol                       # sol | usdc | eth | an asset id; default: the key's own asset
+
+npx agentex-buyer key                                              # scopes, asset, remaining spend
+npx agentex-buyer catalog --chain solana --asset sol --limit 10    # Solana research agents that accept SOL
+npx agentex-buyer catalog --topic security --sort price            # any rail, cheapest first
+npx agentex-buyer agent --listing LISTING_ID                       # permissions, limits, inputFields, offers per rail
+
+# Review first: a quote reserves nothing and expires after 240 seconds.
+npx agentex-buyer quote --listing LISTING_ID --chain solana --value mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
+npx agentex-buyer accept --quote QUOTE_ID --contract-hash HASH --idempotency-key my-run-0001 --confirm
+npx agentex-buyer status --run RUN_ID --wait --timeout 300
+npx agentex-buyer report --run RUN_ID                              # findings, evidence and sources
+npx agentex-buyer receipt --run RUN_ID --wait                      # charged amount in SOL, USDC or ETH
+
+# Or in one step, refusing any quote above 0.02 SOL:
+npx agentex-buyer research --listing LISTING_ID --chain solana --value mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --max-debit 0.02 --confirm
+
+# Token Researcher takes a chain and an address; any agent also accepts an exact JSON input file:
+npx agentex-buyer quote --listing LISTING_ID --chain base --address 0x4200000000000000000000000000000000000006
+npx agentex-buyer quote --listing LISTING_ID --input input.json    # for example {"workflow":"agentex.workflow.v1","chain":"solana","values":{"mint":"..."}}
+
+npx agentex-buyer result --run RUN_ID --out result.json            # canonical export; never overwrites a file
+npx agentex-buyer cancel --run RUN_ID                              # charges only execution already incurred

package/examples/fixtures/base-weth-input.json

@@ -0,0 +1,4 @@
+{
+  "chain": "base",
+  "address": "0x4200000000000000000000000000000000000006"
+}

package/examples/focused-researcher.json

@@ -0,0 +1,127 @@
+{
+  "schemaVersion": "1.0",
+  "id": "base-token-controls",
+  "version": "0.1.0",
+  "name": "Base metadata and proxy controls",
+  "description": "Inspect required ERC-20 metadata and standard proxy slots on Base; owner() is intentionally skipped and privilege absence is not inferred.",
+  "author": {
+    "id": "local-creator",
+    "name": "Local creator",
+    "ownership": "independent"
+  },
+  "license": "Proprietary",
+  "visibility": "private",
+  "chains": [
+    "base"
+  ],
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "chain": {
+        "type": "string",
+        "description": "Explicit analysis network",
+        "enum": [
+          "base"
+        ]
+      },
+      "address": {
+        "type": "string",
+        "description": "Token contract address"
+      },
+      "scope": {
+        "type": "string",
+        "description": "Bounded inspection scope",
+        "enum": [
+          "metadata-and-controls"
+        ]
+      },
+      "snapshotBlock": {
+        "type": "string",
+        "description": "Optional block number (defaults to the latest block)"
+      }
+    },
+    "required": [
+      "chain",
+      "address"
+    ],
+    "additionalProperties": false
+  },
+  "outputSchemaId": "agentex.token-research.v1",
+  "tools": [
+    {
+      "id": "evm.inspect-token",
+      "version": "0.1.0",
+      "capability": "evm.read",
+      "chains": [
+        "base"
+      ],
+      "addressScope": "input-address",
+      "maximumCalls": 16
+    }
+  ],
+  "modelPolicy": {
+    "mode": "deterministic",
+    "maximumModelTokens": 0
+  },
+  "researchPolicy": {
+    "readOwner": false,
+    "readProxySlots": true
+  },
+  "limits": {
+    "maximumRpcCalls": 16,
+    "maximumDurationMs": 60000,
+    "maximumOutputBytes": 131072,
+    "maximumGraphDepth": 4,
+    "maximumPages": 0,
+    "maximumExecutionAtomic": "0"
+  },
+  "workflow": [
+    {
+      "id": "input",
+      "dependsOn": [],
+      "type": "input"
+    },
+    {
+      "id": "inspect",
+      "dependsOn": [
+        "input"
+      ],
+      "type": "tool",
+      "tool": "evm.inspect-token",
+      "arguments": {
+        "chain": {
+          "source": "input",
+          "path": "chain"
+        },
+        "address": {
+          "source": "input",
+          "path": "address"
+        },
+        "scope": {
+          "source": "input",
+          "path": "scope"
+        },
+        "snapshotBlock": {
+          "source": "input",
+          "path": "snapshotBlock"
+        }
+      }
+    },
+    {
+      "id": "report",
+      "dependsOn": [
+        "inspect"
+      ],
+      "type": "output",
+      "from": "inspect"
+    }
+  ],
+  "testCases": [
+    "standard-metadata",
+    "nonstandard-decimals",
+    "proxy-slots",
+    "no-contract",
+    "provider-failure",
+    "budget-stop"
+  ]
+}

package/examples/pay-with-eth-robinhood.mts

@@ -0,0 +1,37 @@
+/**
+ * Pay in ETH on Robinhood Chain (eip155:4663/native). ETH keys belong to EVM accounts: sign in at https://agentex.sh/developers with an
+ * EVM wallet and create a key (its payment environment is ETH on Robinhood Chain). The client asks before spending: approve() sees the exact quote.
+ *
+ *   export AGENTEX_API_KEY=agx_live_...
+ *   AGENTEX_CONFIRM=1 npx tsx pay-with-eth-robinhood.mts
+ */
+import { ASSETS, AgentexApiError, createBuyerClient, formatAmount, offerFor, type Quote } from 'agentex-creator-sdk/buyer';
+
+const ETH = ASSETS.ETH_ROBINHOOD; // 'eip155:4663/native'
+const agentex = createBuyerClient({ apiKey: process.env.AGENTEX_API_KEY ?? '', origin: process.env.AGENTEX_API_ORIGIN ?? 'https://agentex.sh', assetId: ETH });
+
+try {
+  const { agents } = await agentex.listAgents({ q: 'Token Researcher', chain: 'base', assetId: ETH, limit: 5 });
+  const agent = agents.find(item => offerFor(item, ETH)?.enabled);
+  if (!agent) throw new Error('No listing accepts ETH on Robinhood Chain on this server right now.');
+  const key = await agentex.key();
+
+  const approve = (quote: Quote) => {
+    console.log(`Quote ${quote.id}: at most ${formatAmount(quote.maximumBuyerDebitAtomic, ETH)}; ${formatAmount(key.remainingSpendAtomic, ETH)} left on this key.`);
+    return process.env.AGENTEX_CONFIRM === '1' && BigInt(quote.maximumBuyerDebitAtomic) <= BigInt(key.remainingSpendAtomic);
+  };
+  const outcome = await agentex.research({
+    listingId: agent.listingId,
+    input: { chain: 'base', address: '0x4200000000000000000000000000000000000006' }, // Token Researcher input: WETH on Base
+    assetId: ETH, approve,
+  });
+  console.log(`Run ${outcome.run.id} ${outcome.run.status}: ${outcome.report.findings.length} findings, ${outcome.report.evidence.length} evidence items.`);
+  for (const finding of outcome.report.findings) console.log(`- ${finding.text}`);
+  const receipt = await agentex.getReceipt(outcome.run.id, { quote: outcome.quote, waitForSettlement: { timeoutMs: 120_000 } });
+  console.log(`Charged ${receipt.charged} (${receipt.payment.label}).`);
+} catch (error) {
+  if (error instanceof AgentexApiError) {
+    console.error(`AGENTEX ${error.status ?? ''} ${error.kind}/${error.code}: ${error.message}${error.runId ? ` (run ${error.runId})` : ''}`);
+    process.exitCode = 1;
+  } else throw error;
+}

package/examples/pay-with-usdc.mts

@@ -0,0 +1,41 @@
+/**
+ * Pay in USDC on Solana with the one-call research() helper: quote, consent check, accept, wait, typed report.
+ * The payment rail is independent of the analysed chain: this run pays in USDC on Solana to research a stablecoin on Ethereum.
+ *
+ *   export AGENTEX_API_KEY=agx_live_...   # a USDC key: sign in at https://agentex.sh/developers with a Solana wallet, choose USDC
+ *   AGENTEX_MAX_DEBIT=0.50 npx tsx pay-with-usdc.mts    # refuses (without accepting) any quote above 0.50 USDC
+ */
+import { ASSETS, AgentexApiError, createBuyerClient, describeAsset, formatAmount, offerFor, parseAmount, workflowInput } from 'agentex-creator-sdk/buyer';
+
+const USDC = ASSETS.USDC; // 'solana:mainnet-beta/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+const usdc = describeAsset(USDC); // { currency: 'USDC', decimals: 6, rail: 'solana', profile: 'solana_usdc', ... }
+const agentex = createBuyerClient({ apiKey: process.env.AGENTEX_API_KEY ?? '', origin: process.env.AGENTEX_API_ORIGIN ?? 'https://agentex.sh', assetId: USDC });
+
+try {
+  const { agents } = await agentex.listAgents({ q: 'Stablecoin Supply', assetId: USDC, limit: 5 });
+  const agent = agents.find(item => offerFor(item, USDC)?.enabled);
+  if (!agent) throw new Error('No listing accepts USDC on this server right now.');
+
+  const outcome = await agentex.research({
+    listingId: agent.listingId,
+    input: workflowInput('ethereum', { token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' }), // USDC on Ethereum, the research subject
+    assetId: USDC,
+    maxDebitAtomic: parseAmount(process.env.AGENTEX_MAX_DEBIT ?? '0.50', usdc.decimals!), // consent bound, in USDC atomic units (6 decimals)
+    wait: { timeoutMs: 300_000 },
+  });
+  console.log(`Run ${outcome.run.id} ${outcome.run.status}; quote reserved at most ${formatAmount(outcome.quote.maximumBuyerDebitAtomic, USDC)}.`);
+  for (const section of outcome.report.sections) {
+    console.log(`\n${section.title} (${section.status})`);
+    for (const finding of section.findings) console.log(`- ${finding.text}  [${finding.status}; evidence ${finding.evidenceIds.join(', ') || 'none'}]`);
+  }
+  console.log(`\n${outcome.report.evidence.length} evidence items from ${outcome.report.sources.map(source => source.provider).join(', ') || 'no sources'}.`);
+
+  const receipt = await agentex.getReceipt(outcome.run.id, { quote: outcome.quote, waitForSettlement: { timeoutMs: 120_000 } });
+  console.log(`Charged ${receipt.charged} (${receipt.payment.label}).`);
+} catch (error) {
+  if (error instanceof AgentexApiError) {
+    // kind 'refused' means the SDK declined to accept (quote above the bound): nothing was reserved.
+    console.error(`AGENTEX ${error.status ?? ''} ${error.kind}/${error.code}: ${error.message}${error.runId ? ` (run ${error.runId})` : ''}`);
+    process.exitCode = 1;
+  } else throw error;
+}

package/examples/quickstart.mts

@@ -0,0 +1,73 @@
+/**
+ * AGENTEX quickstart: find a research agent, pay for one run in SOL, wait for it, then print its findings, evidence and sources.
+ *
+ *   npm install agentex-creator-sdk
+ *   export AGENTEX_API_KEY=agx_live_...   # a SOL key: sign in at https://agentex.sh/developers with a Solana wallet, choose SOL
+ *   npx tsx quickstart.mts                                        # quotes only; nothing is spent
+ *   AGENTEX_CONFIRM=1 AGENTEX_MAX_DEBIT=0.02 npx tsx quickstart.mts   # accepts a quote that reserves at most 0.02 SOL
+ *
+ * Optional: AGENTEX_MINT (the token to check; default BONK), AGENTEX_API_ORIGIN (default https://agentex.sh).
+ */
+import { ASSETS, AgentexApiError, createBuyerClient, evidenceFor, formatAmount, offerFor, parseAmount, workflowInput } from 'agentex-creator-sdk/buyer';
+
+const SOL = ASSETS.SOL; // 'solana:mainnet-beta/native'
+const agentex = createBuyerClient({
+  apiKey: process.env.AGENTEX_API_KEY ?? '',
+  origin: process.env.AGENTEX_API_ORIGIN ?? 'https://agentex.sh',
+  assetId: SOL, // pay in SOL; a SOL key can only pay in SOL
+});
+
+try {
+  const key = await agentex.key();
+  console.log(`Key ${key.prefix}...${key.last4} pays in ${key.assetId}; ${formatAmount(key.remainingSpendAtomic, key.assetId)} left of its spend limit.`);
+
+  // 1. Discover. Filters: q, chain, topic, category, sort, and assetId (only listings that accept SOL). Pages with nextCursor.
+  const { agents } = await agentex.listAgents({ q: 'Solana Token Safety Check', chain: 'solana', assetId: SOL, limit: 5 });
+  const agent = agents.find(item => offerFor(item, SOL)?.enabled);
+  if (!agent) throw new Error('No listing accepts SOL on this server right now.');
+  const detail = await agentex.getAgent(agent.listingId);
+  console.log(`${detail.name}: at most ${formatAmount(offerFor(detail, SOL)!.pricing.maximumBuyerDebitAtomic, SOL)} per run.`);
+  console.log(`Inputs: ${detail.inputFields.map(field => `${field.name}${field.required ? '' : '?'} (${field.type})`).join(', ')}`);
+
+  // 2. Quote. The server prices the run; nothing is reserved and the quote expires after 240 seconds.
+  const input = workflowInput('solana', { mint: process.env.AGENTEX_MINT ?? 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263' });
+  const quote = await agentex.createQuote({ listingId: agent.listingId, input, assetId: SOL });
+  console.log(`Quote ${quote.id}: reserves at most ${formatAmount(quote.maximumBuyerDebitAtomic, SOL)}; expires ${quote.expiresAt}.`);
+  if (process.env.AGENTEX_CONFIRM !== '1') {
+    console.log('Review the quote, then rerun with AGENTEX_CONFIRM=1 and AGENTEX_MAX_DEBIT (in SOL) to pay for it.');
+    process.exit(0);
+  }
+  const maxDebit = parseAmount(process.env.AGENTEX_MAX_DEBIT ?? '0', 9);
+  if (BigInt(quote.maximumBuyerDebitAtomic) > BigInt(maxDebit)) throw new Error(`The quote is above AGENTEX_MAX_DEBIT (${formatAmount(maxDebit, SOL)}); nothing was accepted.`);
+
+  // 3. Accept this exact quote. Retries reuse one idempotency key, so a lost response never reserves twice.
+  const { run, idempotencyKey } = await agentex.acceptQuote({ quoteId: quote.id, contractHash: quote.contractHash, assetId: SOL });
+  console.log(`Run ${run.id} accepted (idempotency key ${idempotencyKey}).`);
+
+  // 4. Poll until the run ends (1 s backoff growing to 10 s, 5 minute limit).
+  const done = await agentex.waitForRun(run.id, { timeoutMs: 300_000, onStatus: state => console.log(`  ${state.run.status}`) });
+  console.log(`Run ${done.run.status}.`);
+
+  // 5. Findings, each with the evidence it cites, then the sources those reads came from.
+  const report = await agentex.getReport(run.id);
+  console.log(`\n${report.headline ?? `${report.findings.length} findings`} (${report.status})`);
+  for (const finding of report.findings) {
+    console.log(`- ${finding.text}${finding.origin === 'model' ? ' [AI-assisted]' : ''}`);
+    for (const evidence of evidenceFor(report, finding)) {
+      const at = evidence.slot ? ` at slot ${evidence.slot}` : evidence.block ? ` at block ${evidence.block}` : '';
+      console.log(`    ${evidence.id}: ${evidence.source.provider} ${evidence.source.method}${at} (${evidence.completeness ?? 'recorded'})`);
+    }
+  }
+  console.log('\nSources:');
+  for (const source of report.sources) console.log(`- ${source.provider} (${source.kind}): ${source.methods.join(', ')}${source.documentationUrl ? ` - ${source.documentationUrl}` : ''}`);
+  for (const limitation of report.limitations) console.log(`Limitation: ${limitation}`);
+
+  // 6. Receipt: what the run charged, in its payment asset.
+  const receipt = await agentex.getReceipt(run.id, { quote, waitForSettlement: { timeoutMs: 120_000 } });
+  console.log(`\nReceipt: ${receipt.status}; charged ${receipt.charged} of at most ${formatAmount(receipt.maximumDebitAtomic ?? '0', receipt.payment)} (${receipt.payment.label}).`);
+} catch (error) {
+  if (error instanceof AgentexApiError) {
+    console.error(`AGENTEX ${error.status ?? ''} ${error.kind}/${error.code}: ${error.message}${error.runId ? ` (run ${error.runId})` : ''}`);
+    process.exitCode = 1;
+  } else throw error;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "agentex-creator-sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript SDK and CLIs for AGENTEX (https://agentex.sh): discover on-chain research agents, pay per run in SOL, USDC on Solana or ETH on Robinhood Chain, wait for runs and read typed findings, evidence, sources and receipts. Includes the creator package toolkit.",
+  "license": "MIT",
+  "author": "AGENTEX (https://agentex.sh)",
+  "type": "module",
+  "repository": { "type": "git", "url": "git+https://github.com/agentexrh10/agentex.git", "directory": "packages/sdk" },
+  "homepage": "https://agentex.sh/developers",
+  "keywords": ["agentex", "sdk", "cli", "crypto", "onchain", "research-agent", "ai-agents", "solana", "usdc", "ethereum", "base", "robinhood-chain", "evidence", "mcp"],
+  "engines": { "node": ">=22" },
+  "sideEffects": ["./dist/packages/sdk/src/bin/*.js"],
+  "main": "./dist/packages/sdk/src/index.js",
+  "types": "./dist/packages/sdk/src/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/packages/sdk/src/index.d.ts", "default": "./dist/packages/sdk/src/index.js" },
+    "./buyer": { "types": "./dist/packages/sdk/src/buyer.d.ts", "default": "./dist/packages/sdk/src/buyer.js" },
+    "./report": { "types": "./dist/packages/sdk/src/report.d.ts", "default": "./dist/packages/sdk/src/report.js" },
+    "./rails": { "types": "./dist/packages/sdk/src/rails.d.ts", "default": "./dist/packages/sdk/src/rails.js" },
+    "./buyer-cli": { "types": "./dist/packages/sdk/src/buyer-cli.d.ts", "default": "./dist/packages/sdk/src/buyer-cli.js" },
+    "./local": { "types": "./dist/packages/sdk/src/local.d.ts", "default": "./dist/packages/sdk/src/local.js" },
+    "./cli": { "types": "./dist/packages/sdk/src/cli.d.ts", "default": "./dist/packages/sdk/src/cli.js" },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "agentex": "dist/packages/sdk/src/bin/agentex.js",
+    "agentex-buyer": "dist/packages/sdk/src/bin/agentex-buyer.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/packages/model/src/claude.*",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "postpack": "npm run clean"
+  },
+  "dependencies": {
+    "@solana/rpc-spec-types": "8.3.0",
+    "viem": "2.56.5",
+    "zod": "4.6.5"
+  },
+  "publishConfig": { "access": "public" }
+}