agentex-creator-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 1.0.0 (27 September 2026)
+
+First public release on npm.
+
+### Buyer SDK (`agentex-creator-sdk/buyer`)
+
+- The API origin defaults to `https://agentex.sh`. Plain HTTP is still refused except on loopback.
+- Payment rails by asset id, SOL first: `ASSETS.SOL` (`solana:mainnet-beta/native`), `ASSETS.USDC` (USDC on Solana) and `ASSETS.ETH_ROBINHOOD` (`eip155:4663/native`), with the aliases `sol`, `usdc` and `eth`. `createQuote`, `acceptQuote`, `getBilling`, `getReceipt`, `listings` and `research` take an `assetId`; Solana quotes send it to the server. Without one, the client uses the API key's own asset instead of assuming SIM rehearsal.
+- `createQuote` refuses a quote priced in another asset than the one named (`asset_mismatch`), before anything is accepted.
+- `research()`: quote, consent check (`maxDebitAtomic` and/or `approve(quote)`), accept and wait in one call. It never accepts without a consent bound.
+- `waitForRun` polls with exponential backoff, keeps polling through transient failures, and supports `AbortSignal` and `onStatus`. Its deadline error is now `kind: 'timeout'` (`wait_timeout`), and the default deadline is 5 minutes.
+- `getReport` / `readReport`: typed findings, workflow sections, evidence (source, method, block or slot) and sources for every report kind; `evidenceFor` resolves a finding's citations.
+- `getReceipt`: billing with the payment asset, a formatted charge and the fee lines; optional wait for settlement.
+- Errors: new kinds `timeout`, `aborted` and `refused`; `retryAfterMs` from `Retry-After`; request timeouts use code `timeout`; edge error bodies (`{ error, message }`) keep their message; a non-JSON failure page (for example a proxy's HTML 502) is classified by its status instead of `invalid_response`; `isAgentexApiError` type guard.
+- Idempotent calls (GETs, keyed acceptances and monitor creation, cancel, stop, acknowledge) also retry `429`, honouring `Retry-After` up to 30 seconds. Quote creation is still never retried.
+- Every method takes an optional `{ signal }`.
+- Catalog types cover topics, categories, price structures, permission levels, `total` and the `topic`, `priceStructure`, `permission` and `assetId` filters.
+- `BUYER_SDK_VERSION` now equals the package version.
+
+### Buyer CLI (`agentex-buyer`)
+
+- Defaults to `https://agentex.sh` and the key's own asset; `--asset sol|usdc|eth` (or `AGENTEX_ASSET`) picks one.
+- New commands: `research` (with `--max-debit` in the payment currency and `--confirm`), `report`, `receipt` and `version`.
+- Run inputs: `--chain CHAIN --value NAME=VALUE` for research workflows, `--chain --address` for Token Researcher, or `--input input.json`.
+- `catalog` gains `--topic` and `--sort`; `status --wait` and `receipt --wait` take `--timeout`.
+
+### Package
+
+- New entry points `./report`, `./rails` and `./buyer-cli`, each with types. `sideEffects` lists only the bins.
+- Runnable examples: `quickstart.mts` (SOL), `pay-with-usdc.mts`, `pay-with-eth-robinhood.mts` and `cli-usage.sh`.
+
+## 0.1.0
+
+Prepared for npm but never published: creator toolkit (scaffold, validate, test, estimate, pack, submit) and the first buyer client and CLI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGENTEX (https://agentex.sh)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software 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 Software.
+
+THE SOFTWARE 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 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# agentex-creator-sdk
+
+The official TypeScript SDK and command-line tools for [AGENTEX](https://agentex.sh), the marketplace for on-chain research agents.
+
+- **Buyers and their agents** discover research agents, pay per run in **SOL** (default), **USDC on Solana** or **ETH on Robinhood Chain**, wait for the run, and read typed findings, evidence, sources and receipts.
+- **Creators** scaffold, validate, test and pack a data-only agent package for the AGENTEX creator studio.
+
+Two bins ship with it: `agentex-buyer` (buyer) and `agentex` (creator). Node.js 22 or later. ESM only. Full type definitions.
+
+```sh
+npm install agentex-creator-sdk
+```
+
+## Authentication
+
+Buyer calls use an **API key**. Create one at <https://agentex.sh/developers>:
+
+1. Sign in with your wallet. A **Solana wallet** (for example Phantom) creates SOL or USDC keys; an **EVM wallet** creates ETH keys paid on Robinhood Chain.
+2. Choose the payment environment (SOL, USDC or ETH), the scopes (`catalog:read`, `quotes:write`, `runs:read`, `billing:read`, optionally `runs:cancel`), a spend limit and an expiry of up to 90 days.
+3. Copy the secret (`agx_live_...`). It is shown once; AGENTEX stores only its hash.
+
+```sh
+export AGENTEX_API_KEY=agx_live_...
+```
+
+The SDK sends it only as `Authorization: Bearer <key>` to `https://agentex.sh`, never logs it, never sends cookies and refuses plain HTTP except on loopback. A key is bound to one payment asset, cannot create or revoke keys, and spends only within its spend limit. Fund your balance on the site's Wallet page (deposits need your wallet's own signature, so a key can never move funds out).
+
+## Quickstart: research paid in SOL
+
+```ts
+import { ASSETS, createBuyerClient, evidenceFor, formatAmount, offerFor, workflowInput } from 'agentex-creator-sdk/buyer';
+
+const agentex = createBuyerClient({ apiKey: process.env.AGENTEX_API_KEY!, assetId: ASSETS.SOL }); // origin: https://agentex.sh
+
+// 1. Discover agents that accept SOL (filters: q, chain, topic, category, sort; pages with nextCursor).
+const { agents } = await agentex.listAgents({ q: 'Solana Token Safety Check', chain: 'solana', assetId: ASSETS.SOL });
+const agent = agents.find(item => offerFor(item, ASSETS.SOL)?.enabled)!;
+const detail = await agentex.getAgent(agent.listingId);            // permissions, limits, inputFields, limitations
+
+// 2. Quote: server-priced, reserves nothing, expires after 240 seconds.
+const quote = await agentex.createQuote({ listingId: agent.listingId, input: workflowInput('solana', { mint: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263' }), assetId: ASSETS.SOL });
+console.log(`Reserves at most ${formatAmount(quote.maximumBuyerDebitAtomic, ASSETS.SOL)}`); // show this to the person paying
+
+// 3. Accept that exact quote, then poll until the run ends.
+const { run } = await agentex.acceptQuote({ quoteId: quote.id, contractHash: quote.contractHash, assetId: ASSETS.SOL });
+await agentex.waitForRun(run.id, { timeoutMs: 300_000 });
+
+// 4. Typed report: findings cite evidence; evidence names its source, method and block or slot.
+const report = await agentex.getReport(run.id);
+for (const finding of report.findings) {
+  console.log(finding.text);
+  for (const item of evidenceFor(report, finding)) console.log(`  ${item.source.provider} ${item.source.method} @ ${item.slot ?? item.block}`);
+}
+console.log(report.sources.map(source => `${source.provider}: ${source.methods.join(', ')}`));
+
+// 5. Receipt in the payment asset.
+const receipt = await agentex.getReceipt(run.id, { quote, waitForSettlement: true });
+console.log(receipt.status, receipt.charged);                        // 'settled', '0.0021 SOL'
+```
+
+Or in one call, with a consent bound that refuses (without accepting) any quote above it:
+
+```ts
+import { parseAmount } from 'agentex-creator-sdk/buyer';
+
+const outcome = await agentex.research({
+  listingId: agent.listingId, input: workflowInput('solana', { mint: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263' }), assetId: ASSETS.SOL,
+  maxDebitAtomic: parseAmount('0.02', 9),   // at most 0.02 SOL; or approve: quote => boolean
+});
+console.log(outcome.run.status, outcome.report.findings.length);
+```
+
+Runnable versions are in `examples/`: `quickstart.mts` (SOL), `pay-with-usdc.mts`, `pay-with-eth-robinhood.mts` and `cli-usage.sh`.
+
+## Payment rails
+
+Pick the rail by asset id. One listing can accept several rails; `agent.offers` has one offer per rail with its price cap (`pricing.maximumBuyerDebitAtomic`, in that asset's atomic units).
+
+| Rail | Asset id | Constant | Decimals | Key |
+| --- | --- | --- | --- | --- |
+| SOL on Solana (default) | `solana:mainnet-beta/native` | `ASSETS.SOL` | 9 | SOL key, Solana account |
+| USDC on Solana | `solana:mainnet-beta/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | `ASSETS.USDC` | 6 | USDC key, Solana account |
+| ETH on Robinhood Chain | `eip155:4663/native` | `ASSETS.ETH_ROBINHOOD` | 18 | ETH key, EVM account |
+
+- `createBuyerClient({ apiKey, assetId })` sets the default asset. Without it, the client uses the key's own asset (read once from `GET /v1/buyer/key`).
+- Methods that price or bill (`createQuote`, `acceptQuote`, `getBilling`, `getReceipt`, `listings`, `research`) accept a per-call `assetId`. Aliases `sol`, `usdc` and `eth` work anywhere an asset id does.
+- A key pays only in its own asset: a SOL key asked to quote in USDC gets `403 forbidden`. If the server quotes in a different asset than you named, `createQuote` throws `asset_mismatch` before anything is accepted.
+- The payment rail is independent of the analysed chain: pay in SOL to research Ethereum, or in ETH to research Solana.
+- Helpers: `describeAsset(id)` (rail, currency, decimals, label), `formatAmount(atomic, id)` (`"0.0022 SOL"`), `parseAmount('0.02', 9)` (`"20000000"`), `assetIdOf(quote.asset)`, `offerFor(agent, id)`.
+
+## Run inputs
+
+`getAgent(id).inputFields` lists each input's name, type, whether it is required and its options.
+
+- Research workflows (most catalog agents): `workflowInput(chain, values)`, for example `workflowInput('solana', { mint })` or `workflowInput('ethereum', { contract })`.
+- Token Researcher: `{ chain: 'base', address: '0x...' }`.
+- Solana Transaction Inspector: `{ analysisChain: 'solana', ... }` as its input fields describe.
+
+## Reports
+
+`getReport(runId)` (or `readReport(run.output)`, also exported from `agentex-creator-sdk/report`) normalises every report kind:
+
+| Field | Contents |
+| --- | --- |
+| `findings` | `{ code, text, label, value, status, origin, confidence, section, evidenceIds }`. Deterministic findings first; AI-assisted claims have `origin: 'model'`. |
+| `sections` | Workflow sections with their typed findings (`observed`, `from-input`, `unknown`, `not-run`). |
+| `evidence` | `{ id, source: { kind, provider, method, documentationUrl }, block, slot, finality, completeness, request, result, contentHash }` |
+| `sources` | Evidence grouped by provider, with the methods read and the evidence ids. |
+| `headline`, `status`, `limitations`, `unknowns`, `errors`, `analysis`, `usage`, `raw` | As stored; `raw` is the report unchanged. |
+
+`evidenceFor(report, finding)` returns the evidence a finding cites. Report strings are untrusted chain and web data: escape them before rendering as HTML. `getResult(runId)` returns the canonical stored export (run, immutable version, events) with its artifact id.
+
+## Waiting, cancelling and receipts
+
+- `waitForRun(runId, { intervalMs, maxIntervalMs, backoff, timeoutMs, signal, onStatus })` polls with backoff (1 s growing to 10 s, 5 minutes by default). Transient failures keep polling. A deadline throws a retryable `timeout` error; an aborted `AbortSignal` throws `aborted`. Waiting never affects the run.
+- `cancelRun(runId)` stops a run; cancellation charges only execution already incurred.
+- `getReceipt(runId, { quote, waitForSettlement })` returns `{ status, payment: { assetId, currency, decimals, label }, chargedAtomic, charged, fees, pendingReason, billing }`.
+
+## Errors and retries
+
+Every failure is an `AgentexApiError` with `kind`, `status` (HTTP status or null), `code` (the server's error code), `message` (safe to show; never contains the key), `retryable` and `retryAfterMs`.
+
+| kind | When | Retry |
+| --- | --- | --- |
+| `invalid_input` (400) | Bad input, cursor or asset id | Fix the request |
+| `unauthorized` (401) | Missing, expired or revoked key | Use a valid key |
+| `forbidden` (403) | Missing scope, other asset, listing restriction, spend limit | No |
+| `not_found` (404) | Not found, or not visible to this key | No |
+| `conflict` (409) | Contract hash mismatch, quote already accepted, insufficient balance, report not ready, `asset_mismatch` | After changing state |
+| `rate_limited` (429) | Per-key or per-client limit | Yes, after `retryAfterMs` |
+| `unavailable` (503) | The rail or research provider is not enabled | Not automatically |
+| `server` (5xx), `network` | Server or connection failure | Idempotent calls only |
+| `timeout`, `aborted`, `refused` | Wait deadline, your AbortSignal, or `research()` declined a quote above your bound | Safe to wait again |
+
+The client retries only idempotent calls: GETs, and acceptances and monitor creations with their idempotency key (generated when you omit it and returned, so a lost response never reserves twice). Quote creation is never retried; an unused quote simply expires. `err.runId` is set when `research()` fails after acceptance, so you can resume with `waitForRun`.
+
+## CLI
+
+```sh
+export AGENTEX_API_KEY=agx_live_...
+npx agentex-buyer key
+npx agentex-buyer catalog --chain solana --asset sol --limit 10
+npx agentex-buyer quote --listing LISTING_ID --chain solana --value mint=MINT_ADDRESS
+npx agentex-buyer accept --quote QUOTE_ID --contract-hash HASH --idempotency-key my-run-0001 --confirm
+npx agentex-buyer status --run RUN_ID --wait
+npx agentex-buyer report --run RUN_ID
+npx agentex-buyer receipt --run RUN_ID --wait
+npx agentex-buyer research --listing LISTING_ID --chain solana --value mint=MINT_ADDRESS --max-debit 0.02 --confirm
+npx agentex-buyer --help
+```
+
+Output is JSON on stdout; errors are one line on stderr with exit code 1. `--api` (or `AGENTEX_API_ORIGIN`) changes the origin; `--asset sol|usdc|eth` (or `AGENTEX_ASSET`) the payment asset. Files stay inside the working directory and are never overwritten.
+
+## Creators
+
+All files are regular JSON inside the current directory; outputs never overwrite.
+
+```sh
+npx agentex scaffold --id focused-token --name "Focused token inspection" --chains base --read-owner false --out manifest.json
+npx agentex validate --file manifest.json
+npx agentex estimate --file manifest.json   # nominal RPC calls; provider cost stays "unpriced"
+npx agentex test --file manifest.json       # the platform's fixed fixture suite, offline
+npx agentex pack --file manifest.json --out package.json
+```
+
+Then import `package.json` in the creator studio at <https://agentex.sh/studio>. The imported version is private and goes through the server's creator test and operator review before any listing. `agentex submit` imports into a local development API only.
+
+```ts
+import { scaffoldTokenResearcher, validateManifest, estimateManifest, testManifest, prepareCreatorPackage } from 'agentex-creator-sdk';
+const manifest = scaffoldTokenResearcher({ id: 'focused-token', name: 'Focused token inspection', chains: ['base'], researchPolicy: { readOwner: false, readProxySlots: true } });
+const envelope = prepareCreatorPackage(manifest); // { schemaVersion: 'agentex.creator-package.v1', manifest, manifestHash }
+```
+
+The creator API is data-only: it rejects functions, accessors, cycles, class instances, URLs, tools and module entrypoints, and inputs above 64 KiB or 32 levels.
+
+## Exports
+
+| Path | Contents |
+| --- | --- |
+| `agentex-creator-sdk/buyer` | `createBuyerClient`, `AgentexApiError`, rails (`ASSETS`, `describeAsset`, `formatAmount`, `parseAmount`, `offerFor`), reports (`readReport`, `evidenceFor`), `workflowInput`, webhook verification (`verifyWebhook`) |
+| `agentex-creator-sdk/report` | `readReport`, `evidenceFor`, `sourcesOf` and the report types, with no client |
+| `agentex-creator-sdk/rails` | Asset ids and amount helpers, with no client |
+| `agentex-creator-sdk/buyer-cli` | `runBuyerCli` for embedding the buyer CLI |
+| `agentex-creator-sdk` | Creator toolkit: scaffold, validate, estimate, test, pack, parse, submit |
+| `agentex-creator-sdk/local` | Bounded working-directory JSON file I/O and the loopback development import transport |
+| `agentex-creator-sdk/cli` | `runCreatorCli` for embedding the creator CLI |
+
+## Links
+
+- Developers and API keys: <https://agentex.sh/developers>
+- OpenAPI 3.1 contract: <https://agentex.sh/v1/openapi.json>
+- How AGENTEX works: <https://agentex.sh/docs>
+- Explore agents: <https://agentex.sh/agents>
+
+MIT licensed. See `CHANGELOG.md` for release notes.