From 208d54cdad2fc914ea7416f86dfbf333d512eedc Mon Sep 17 00:00:00 2001 From: Ang Weoy Yang <62604618+Ang-dot@users.noreply.github.com> Date: Mon, 24 Aug 2026 01:45:26 +0800 Subject: [PATCH 1/2] docs(bnbagent-sdk): add a TypeScript quickstart The SDK README commits to Python and TypeScript both being "first-class, long-term", but the only quickstart was Python. The one page where a developer picks a language showed one language. Adds quickstart-typescript.md covering the same three flows: register an agent (ERC-8004), earn as a provider, buy as a client. Every snippet is taken from shipped code, not written fresh: - registration from typescript/examples/agent-server/scripts/register.ts, retargeted from relative src/ imports to the published subpath exports - provider and client flows from the typescript/README.md quickstart States plainly that the TypeScript SDK ships no HTTP server layer. The Python provider examples wrap the protocol in FastAPI; the TS path is a headless fundedJobWatcher loop. Implying otherwise is what made the Python quickstart's server section wrong in the first place. quickstart.md is retitled "(Python)" and both pages cross-link, with a note that independent release cadences mean the version numbers differ by design. Existing /quickstart/ URL is unchanged. Verified: all 7 documented APIs exist in typescript/src (ERC8004Agent.create at erc8004/agent.ts:351, policy.disputeWindow used at erc8183/client.ts:366, tokenDecimals/createJob/registerJob/fund/settle/getJob/setBudget all present); subpath exports and Node >=20 from typescript/package.json; every nav path and relative link resolves; the three GitHub links return 200. --- docs/developer-kit/bnbagent-sdk/index.md | 3 +- .../bnbagent-sdk/quickstart-typescript.md | 230 ++++++++++++++++++ docs/developer-kit/bnbagent-sdk/quickstart.md | 13 +- docs/llms.txt | 3 +- mkdocs.yml | 3 +- 5 files changed, 248 insertions(+), 4 deletions(-) create mode 100644 docs/developer-kit/bnbagent-sdk/quickstart-typescript.md diff --git a/docs/developer-kit/bnbagent-sdk/index.md b/docs/developer-kit/bnbagent-sdk/index.md index 4329a696e6..0f0079e874 100644 --- a/docs/developer-kit/bnbagent-sdk/index.md +++ b/docs/developer-kit/bnbagent-sdk/index.md @@ -137,7 +137,8 @@ OPEN ──► FUNDED ──► SUBMITTED ──┬──► (silence past windo | Guide | Description | |-------|-------------| -| [Quickstart](quickstart.md) | Register an agent (ERC-8004), run an ERC-8183 server, use `ERC8183Client` | +| [Quickstart (Python)](quickstart.md) | Register an agent (ERC-8004), run an ERC-8183 server, use `ERC8183Client` | +| [Quickstart (TypeScript)](quickstart-typescript.md) | The same three flows in TypeScript — register, earn as a provider, buy as a client | | [Configuration](configuration.md) | Environment variables and module settings | | [Architecture](architecture.md) | Code map, module system, data flows | | [Networks & contracts](networks.md) | Supported networks and upstream deployment references | diff --git a/docs/developer-kit/bnbagent-sdk/quickstart-typescript.md b/docs/developer-kit/bnbagent-sdk/quickstart-typescript.md new file mode 100644 index 0000000000..0b313c4299 --- /dev/null +++ b/docs/developer-kit/bnbagent-sdk/quickstart-typescript.md @@ -0,0 +1,230 @@ +--- +title: BNB Agent SDK Quickstart (TypeScript) +--- + +# Quickstart — TypeScript + +The BNB Agent SDK ships as two first-class implementations that target the same +protocols and the same on-chain deployments. This page is the TypeScript path; for +Python see [Quickstart (Python)](quickstart.md). + +!!! info "Choosing a language" + Both SDKs are actively maintained long term — pick the one that matches your + application. They release independently, so their published version numbers + routinely differ; that is expected and does not mean either is behind. + Language-specific wallet and runtime integrations do differ, and the + differences that affect this page are called out inline. + +## Install + +```bash +pnpm add @bnbagent/sdk +# or +npm install @bnbagent/sdk +``` + +Requires **Node.js ≥ 20**. The package ships both ESM (`import`) and CommonJS +(`require`) builds plus TypeScript types. + +Available subpath exports: `./erc8004`, `./erc8183`, `./x402`, `./storage`, +`./wallets`, `./signing`, `./networks`, `./utils`. + +### Environment + +Nothing is read automatically. Call `loadEnv()` once at your entrypoint to load +`.env.local` then `.env`, or inject variables however your deployment normally +does. The snippets below use: + +| Variable | Used by | Notes | +| --- | --- | --- | +| `NETWORK` | network resolution | `bsc-testnet` (default) or `bsc-mainnet` | +| `WALLET_PASSWORD` | `EVMWalletProvider` | required; encrypts/decrypts the local Keystore V3 file | +| `PRIVATE_KEY` | `EVMWalletProvider` | first run only — imported, then encrypted to disk; remove afterward | +| `ERC8183_AGENT_URL` | `ERC8183JobOps` | public base URL; deliverable-URL fallback host | +| `PROVIDER_ADDRESS` | client flow | address of the agent you are buying from | + +The full table lives in the [SDK README](https://github.com/bnb-chain/bnbagent-sdk/tree/main/typescript#environment-variables). + +Both protocol snippets assume a funded wallet on `bsc-testnet` — get test BNB from +the [BNB Chain faucet](https://www.bnbchain.org/en/testnet-faucet). + +--- + +## Register an agent (ERC-8004) + +A one-time on-chain operation so clients can discover your agent. + +```ts +import { EVMWalletProvider, loadEnv } from "@bnbagent/sdk"; +import { AgentEndpoint, ERC8004Agent } from "@bnbagent/sdk/erc8004"; + +loadEnv(); + +const wallet = new EVMWalletProvider({ + password: process.env.WALLET_PASSWORD!, + // First run only — encrypted to ~/.bnbagent/wallets/
.json; + // later runs need only the password. + privateKey: process.env.PRIVATE_KEY, +}); + +const sdk = await ERC8004Agent.create({ + walletProvider: wallet, + network: process.env.NETWORK ?? "bsc-testnet", +}); + +const agentUri = sdk.generateAgentUri({ + name: "my-ai-agent", + description: "AI agent for document processing", + endpoints: [ + new AgentEndpoint({ + name: "web", + endpoint: "https://my-agent.example.com/status", + }), + ], +}); + +const result = await sdk.registerAgent(agentUri); +console.log(`agent_id: ${result.agentId} tx: ${result.transactionHash}`); +``` + +The endpoint `name` is an open string — `"A2A"` and `"MCP"` are the spec-named +protocol types, and `"web"` is the conventional choice for a plain HTTP surface. +Registration is gas-free on BSC Testnet via MegaFuel paymaster sponsorship. + +Working script: [`typescript/examples/agent-server/scripts/register.ts`](https://github.com/bnb-chain/bnbagent-sdk/tree/main/typescript/examples/agent-server/scripts/register.ts). + +--- + +## Earn as a provider (ERC-8183) + +!!! important "The TypeScript SDK ships no HTTP server layer" + The Python SDK's provider examples wrap the protocol in FastAPI. The + TypeScript SDK is transport-agnostic: the provider path is a **headless + polling loop**, not a web app. `fundedJobWatcher` only *detects* funded jobs + — your callback decides what to do with each one, so you can bring whatever + HTTP framework you like, or none at all. + +`ERC8183JobOps` handles verification (status, assignment, expiry, budget floor) +and deliverable upload. + +```ts +import { EVMWalletProvider } from "@bnbagent/sdk"; +import { ERC8183JobOps, fundedJobWatcher } from "@bnbagent/sdk/erc8183"; +import { LocalStorageProvider } from "@bnbagent/sdk/storage"; + +const wallet = new EVMWalletProvider({ + password: process.env.WALLET_PASSWORD!, +}); + +const jobOps = await ERC8183JobOps.create({ + walletProvider: wallet, + network: "bsc-testnet", + storageProvider: new LocalStorageProvider(".agent-data"), + servicePrice: 1n * 10n ** 18n, // reject jobs budgeted below 1 token (18 decimals) + agentUrl: process.env.ERC8183_AGENT_URL, // public base URL; deliverable-URL fallback +}); + +await fundedJobWatcher( + jobOps, + async (job) => { + const jobId = job.jobId as number; + console.log(`[earn-loop] job ${jobId} funded, budget=${job.budget}`); + + const result = await jobOps.submitResult( + jobId, + `computed result for job ${jobId}`, + { model: "my-model-v1" }, + ); + if (!result.success) { + console.error(`[earn-loop] submit(${jobId}) failed: ${result.error}`); + // { retry: true } asks the watcher to re-validate and re-fire this job + // on the next tick — only for transient failures. + return { retry: result.retryable === true }; + } + console.log(`[earn-loop] submitted ${jobId}, tx=${result.txHash}`); + }, + { interval: 30 }, // seconds between polls +); +``` + +Settle is permissionless and is **not** run for you: any party can finalise a +submitted job once its dispute window elapses. Operators typically run a separate +script that polls verdicts and calls `settle()`. + +--- + +## Buy as a client (ERC-8183) + +The client creates a job, binds the on-chain dispute policy, funds escrow, and — +once the provider submits — settles it. + +```ts +import { + loadEnv, + EVMWalletProvider, + ERC8183Client, + JobStatus, +} from "@bnbagent/sdk"; + +loadEnv(); + +const wallet = new EVMWalletProvider({ + password: process.env.WALLET_PASSWORD!, + privateKey: process.env.PRIVATE_KEY, +}); + +const client = await ERC8183Client.create({ + walletProvider: wallet, + network: "bsc-testnet", +}); + +const decimals = await client.tokenDecimals(); +const budget = 1n * 10n ** BigInt(decimals); // 1 token + +// expiredAt must clear (disputeWindow + a safety buffer) or createJob() throws — +// a job whose deadline is too close can never be submitted. +const disputeWindow = await client.policy.disputeWindow(); +const expiredAt = + BigInt(Math.floor(Date.now() / 1000)) + disputeWindow + 600n; // +10 min slack + +const { jobId } = await client.createJob({ + provider: process.env.PROVIDER_ADDRESS!, + expiredAt, + description: "ERC-8183 demo: summarize this week's BSC ecosystem news", +}); + +// Bind the OptimisticPolicy so settle() has a verdict source. +await client.registerJob(jobId!); + +// Escrow the budget — auto-approves the payment token if the allowance is short. +// For a free job, setBudget(jobId, 0n) then fund(jobId, 0n) moves no tokens and +// skips the ERC-20 approve entirely. +await client.fund(jobId!, budget); + +// ... the provider submits its deliverable here ... + +// After the dispute window elapses with no rejection, settle() finalizes the job +// as COMPLETED (or REJECTED if the policy recorded a reject vote). +await client.settle(jobId!); +const job = await client.getJob(jobId!); +console.log(`settled -> ${JobStatus[job.status]}`); +``` + +Five canonical client flows (happy, dispute-reject, stalemate-expire, +never-submit, cancel-open) live in +[`typescript/examples/client/`](https://github.com/bnb-chain/bnbagent-sdk/tree/main/typescript/examples/client). + +--- + +## Wallets + +`EVMWalletProvider` (local Keystore V3) is used above. The TypeScript SDK also +ships `TWAKProvider` (Trust Wallet Agent Kit CLI) and `AltanaWalletProvider` +(EIP-7702 session keys) — select the backend at construction time, or set +`WALLET_KIND=evm|twak`. See the +[wallet providers section](https://github.com/bnb-chain/bnbagent-sdk/tree/main/typescript#wallet-providers) +of the SDK README. + +--- + +[← BNB Agent SDK overview](index.md) · [Quickstart (Python)](quickstart.md) diff --git a/docs/developer-kit/bnbagent-sdk/quickstart.md b/docs/developer-kit/bnbagent-sdk/quickstart.md index dea5037e32..437100c0fe 100644 --- a/docs/developer-kit/bnbagent-sdk/quickstart.md +++ b/docs/developer-kit/bnbagent-sdk/quickstart.md @@ -1,7 +1,18 @@ --- -title: BNB Agent SDK Quickstart +title: BNB Agent SDK Quickstart (Python) --- +# Quickstart — Python + +The BNB Agent SDK ships as two first-class implementations targeting the same +protocols and the same on-chain deployments. This page is the Python path; for +TypeScript see [Quickstart (TypeScript)](quickstart-typescript.md). + +!!! info "Choosing a language" + Both SDKs are actively maintained long term — pick the one that matches your + application. They release independently, so their published version numbers + routinely differ; that is expected and does not mean either is behind. + ## Quick Start: Register an Agent (ERC-8004) Register your AI agent on-chain with a unique identity. This is a one-time setup. diff --git a/docs/llms.txt b/docs/llms.txt index 59b437cca3..9133e7a75b 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -213,7 +213,8 @@ - [Overview](https://docs.bnbchain.org/developer-kit/): Lightweight index of official BNB Chain developer tools. - [Greenfield SDK](https://docs.bnbchain.org/developer-kit/greenfield-sdk/): Go and JavaScript client libraries for Greenfield (language tabs). - [BNB Agent SDK](https://docs.bnbchain.org/developer-kit/bnbagent-sdk/): Python SDK for on-chain AI agents (ERC-8004, ERC-8183) on BSC. - - [Quickstart](https://docs.bnbchain.org/developer-kit/bnbagent-sdk/quickstart/): Register agents, run server, use client. + - [Quickstart (Python)](https://docs.bnbchain.org/developer-kit/bnbagent-sdk/quickstart/): Register agents, run server, use client. + - [Quickstart (TypeScript)](https://docs.bnbchain.org/developer-kit/bnbagent-sdk/quickstart-typescript/): Same flows in TypeScript; headless provider loop, no HTTP server layer. - [Architecture](https://docs.bnbchain.org/developer-kit/bnbagent-sdk/architecture/): Module system and data flows. - [Configuration](https://docs.bnbchain.org/developer-kit/bnbagent-sdk/configuration/): Environment variables. - [Networks & contracts](https://docs.bnbchain.org/developer-kit/bnbagent-sdk/networks/): Supported networks and upstream deployment references. diff --git a/mkdocs.yml b/mkdocs.yml index 033c945fa2..a268bc858a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -297,7 +297,8 @@ nav: - Troubleshooting: ./developer-kit/bnbchain-studio/troubleshooting.md - BNB Agent SDK: - Overview: ./developer-kit/bnbagent-sdk/index.md - - Quickstart: ./developer-kit/bnbagent-sdk/quickstart.md + - Quickstart (TypeScript): ./developer-kit/bnbagent-sdk/quickstart-typescript.md + - Quickstart (Python): ./developer-kit/bnbagent-sdk/quickstart.md - Configuration: ./developer-kit/bnbagent-sdk/configuration.md - Architecture: ./developer-kit/bnbagent-sdk/architecture.md - Networks & Contracts: ./developer-kit/bnbagent-sdk/networks.md From 0fde3809f5fdfaa07fa3e7610450da9b15edce15 Mon Sep 17 00:00:00 2001 From: Ang Weoy Yang <62604618+Ang-dot@users.noreply.github.com> Date: Mon, 24 Aug 2026 01:57:32 +0800 Subject: [PATCH 2/2] docs(bnbagent-sdk): order the TypeScript quickstart ahead of Python Node is the path being pushed for agentic use, so it should be the first quickstart a developer sees. Applies to both the nav and the overview page's guide table. Neither page's URL changes. --- docs/developer-kit/bnbagent-sdk/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-kit/bnbagent-sdk/index.md b/docs/developer-kit/bnbagent-sdk/index.md index 0f0079e874..b291465061 100644 --- a/docs/developer-kit/bnbagent-sdk/index.md +++ b/docs/developer-kit/bnbagent-sdk/index.md @@ -137,8 +137,8 @@ OPEN ──► FUNDED ──► SUBMITTED ──┬──► (silence past windo | Guide | Description | |-------|-------------| -| [Quickstart (Python)](quickstart.md) | Register an agent (ERC-8004), run an ERC-8183 server, use `ERC8183Client` | | [Quickstart (TypeScript)](quickstart-typescript.md) | The same three flows in TypeScript — register, earn as a provider, buy as a client | +| [Quickstart (Python)](quickstart.md) | Register an agent (ERC-8004), run an ERC-8183 server, use `ERC8183Client` | | [Configuration](configuration.md) | Environment variables and module settings | | [Architecture](architecture.md) | Code map, module system, data flows | | [Networks & contracts](networks.md) | Supported networks and upstream deployment references |