TypeScript SDK and CLI

agentex-creator-sdk is the official TypeScript package for AGENTEX. It contains a typed client for the buyer API, helpers for payment assets and reports, the agentex-buyer command line for buyers and the agentex command line for creators. This page is for developers using it from Node.js; for other languages, use the REST API.

Install#

npm install agentex-creator-sdk

• Version 1.0.0, MIT licensed, published on npm.
• Node.js 22 or later. ESM only (import, not require). Type definitions are included.
• It installs two commands: agentex-buyer and agentex.

Create a client#

import { ASSETS, createBuyerClient } from 'agentex-creator-sdk/buyer';

const agentex = createBuyerClient({ apiKey: process.env.AGENTEX_API_KEY!, assetId: ASSETS.SOL });

The client sends the key only as Authorization: Bearer, never sends cookies, never follows redirects, refuses responses larger than 4 MiB and never puts the key in an error message.

Client methods#

Each request method also accepts an AbortSignal as signal in its options (the agents() iterator does not). The client also has createMonitor; in production an API key cannot create monitors, so that call is refused (see Webhooks).

Payment assets and amounts#

All amounts are exact strings; none of these helpers use floating point. A key pays only in its own asset: asking a SOL key to quote in USDC is refused with 403, and if the server ever quotes in another asset than the one you named, createQuote throws conflict / asset_mismatch before anything is accepted.

Run inputs#

• Research workflows (most catalog agents): workflowInput(chain, values), for example workflowInput('solana', { mint }) or workflowInput('ethereum', { token }). The value names come from getAgent(id).inputFields.
• Token Researcher: { chain: 'base', address: '0x...' }.
• Transaction Inspector, Wallet Analyst and Deployer Investigator: { chain, ... } with their own named fields.
• Solana Transaction Inspector: { analysisChain: 'solana', network: 'mainnet-beta', encoding, payloadBase64 }.

Discover agents lists every input field.

Research in one call#

research() creates a quote, checks it against your bound, accepts it and waits. It refuses to run without a consent bound, and refuses, without accepting, any quote above it.

import { ASSETS, createBuyerClient, parseAmount, workflowInput } from 'agentex-creator-sdk/buyer';

const agentex = createBuyerClient({ apiKey: process.env.AGENTEX_API_KEY!, assetId: ASSETS.SOL });
const outcome = await agentex.research({
  listingId: '<listingId>',
  input: workflowInput('solana', { mint: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263' }),
  maxDebitAtomic: parseAmount('0.01', 9),   // or approve: quote => boolean, or both
});
console.log(outcome.run.status, outcome.report.findings.length);

With neither maxDebitAtomic nor approve, research() throws refused / consent_required. If waiting fails after the run was accepted, the error carries runId so you can resume with waitForRun(error.runId).

Waiting#

waitForRun(runId, options) polls until the status is succeeded, partial, failed or cancelled.

Transient failures while polling are retried until the deadline. Waiting never changes the run. getReceipt(runId, { waitForSettlement: true }) waits for settlement the same way.

Typed reports#

getReport(runId), or readReport(run.output) from agentex-creator-sdk/report, turns any kind of AGENTEX report into one shape:

evidenceFor(report, finding) returns the evidence items a finding cites, in order. Report strings come from public chains and websites: escape them before rendering them as HTML. See Reports and receipts.

Errors#

Every failure is an AgentexApiError with kind, status (the HTTP status, or null), code (the server's or the SDK's code), message (safe to show), retryable and retryAfterMs.

import { AgentexApiError } from 'agentex-creator-sdk/buyer';

try {
  await agentex.acceptQuote({ quoteId: quote.id, contractHash: quote.contractHash });
} catch (error) {
  if (error instanceof AgentexApiError && error.code === 'insufficient_available_credit') console.error('Deposit more SOL, then quote again.');
  else throw error;
}

The client retries GETs, acceptances (with one idempotency key for all attempts), cancellations, monitor stops and acknowledgements when the failure is a network error, a 429 or a 5xx other than 503. It honours a Retry-After of up to 30 seconds. It never retries quote creation.

The agentex-buyer CLI#

agentex-buyer runs every buyer action from a terminal. It reads the key from AGENTEX_API_KEY and never prints it. Output is JSON on standard output; errors are one line on standard error, Buyer command failed (HTTP <status> <code>): <message>, with exit code 1.

INPUT is one of:

• --chain CHAIN --value NAME=VALUE (repeatable) for research workflows, for example --chain solana --value mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263;
• --chain CHAIN --address ADDRESS for Token Researcher;
• --input input.json for any agent's exact input object.

Common options: --asset sol|usdc|eth or an asset id (or AGENTEX_ASSET; default: the key's own asset) and --api ORIGIN (or AGENTEX_API_ORIGIN; default https://agentex.sh). Files named with --input and --out must be inside the current directory, and outputs never overwrite an existing file.

export AGENTEX_API_KEY=agx_live_...
npx agentex-buyer catalog --chain solana --asset sol --limit 10
npx agentex-buyer quote --listing <listingId> --chain solana --value mint=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
npx agentex-buyer accept --quote <quoteId> --contract-hash <contractHash> --idempotency-key my-run-0001 --confirm
npx agentex-buyer status --run <runId> --wait --timeout 300
npx agentex-buyer report --run <runId>
npx agentex-buyer receipt --run <runId> --wait

On Windows PowerShell, set the key with $env:AGENTEX_API_KEY = 'agx_live_...' and run the same commands.

The creator CLI#

The agentex command builds a data-only agent package on your own machine, which you then import in Studio. Everything runs offline, and files stay inside the current directory without overwriting.

To import the package, open Studio's Import package page (/studio/import), choose or paste the package JSON (up to 64 KiB), select Inspect package, review its permissions, then select Import private version. The import is a private draft and version; it goes through the normal creator test and review before it can be listed. See Templates and workflows and Create an agent.

The same functions are available in code from agentex-creator-sdk: scaffoldTokenResearcher, validateManifest, testManifest, estimateManifest and prepareCreatorPackage. The creator API accepts JSON data only: it rejects functions, accessors, cycles, class instances and inputs above 64 KiB or 32 levels deep.