BNBAgent SDK

Python SDK (

pip install bnbagent

, Python 3.10+) for on-chain AI agents on BNB Chain. Two independent capabilities:

ERC-8004 (identity) — register an agent on-chain as an ERC-721 identity token with a discoverable profile URI. Gas-free on BSC Testnet via MegaFuel paymaster.
ERC-8183 (agentic commerce) — trustless job escrow between a client (pays) and a provider (delivers). Optimistic settlement: silence past the dispute window = approval; a client dispute triggers a whitelisted-voter quorum reject.

They are independent: you can run ERC-8183 jobs without ERC-8004 registration (registration is only recommended for discovery).

Active development — breaking changes possible. Tested with
bnbagent==0.4.0
; verify install with
python -c "import bnbagent; print(bnbagent.__version__)"
. Optional extra:
pip install "bnbagent[ipfs]"
for IPFS/Pinata deliverable storage.

⚠️ Mainnet economics — read BEFORE any mainnet commerce

The payment token is U (United Stables)
```
0xcE24439F2D9C6a2289F741120FE202248B666666
```
— not BNB, not USDT/USDC. There is no faucet for it: acquire U on PancakeSwap (a WBNB–U pair exists). The client must hold U before calling
```
fund()
```
. Fetch decimals at runtime via
```
erc8183.token_decimals()
```
— don't assume.
ERC-8183 writes on mainnet are never gas-sponsored. Client and provider both need BNB for gas (only ERC-8004 identity registration is sponsored on mainnet).
The mainnet dispute window is 604800s (7 days). A happy path cannot reach
```
COMPLETED
```
in one session — silence-approval only kicks in after the window. Plan a partial E2E (through
```
SUBMITTED
```
) and settle later via a cron/operator script (
```
examples/auto_settle.py
```
).
```
settle
```
reverting with
```
policy pending
```
during this week is expected, not an error.

Preflight balance checklist (mainnet)

Party	Needs	Why
Client	BNB	gas for `createJob` / `registerJob` / `setBudget` / `approve` / `fund` (+ optional swap gas)
Client	U	the job budget escrowed by `fund` (+ small residual for retries)
Provider	BNB	gas for `submit` — not sponsored on mainnet
Settler (anyone)	BNB	gas for `settle` after the window

Decide what you're doing

Goal	Use	Reference
Register agent identity on-chain	`ERC8004Agent`	quick start below
Earn: accept + deliver funded jobs	`ERC8183JobOps` + `funded_job_watcher`	quick start below, `examples/agent-server/` , `examples/a2a-agent/`
Pay: create/fund/settle jobs	`ERC8183Client`	quick start below, `examples/client/`
Vote on disputes (whitelisted voter)	`PolicyClient.vote_reject`	`examples/voter/`
Pay HTTP 402 challenges (x402)	`X402Signer` / twak delegated payer	`examples/x402/` , `references/twak.md`
Understand internals / extend	—	`references/architecture.md`
Wallet backends (EVM keystore vs twak)	`EVMWalletProvider` / `TWAKProvider`	`references/wallets.md` , `references/twak.md`

Quick start: register an agent (ERC-8004)

One-time setup. Needs a private key (auto-generated if omitted) and

WALLET_PASSWORD

python

import os
from bnbagent import ERC8004Agent, AgentEndpoint, EVMWalletProvider

wallet = EVMWalletProvider(
    password=os.getenv("WALLET_PASSWORD"),
    private_key=os.getenv("PRIVATE_KEY"),  # only needed on first run; keystore persists to ~/.bnbagent/wallets/
)
sdk = ERC8004Agent(network="bsc-testnet", wallet_provider=wallet)

agent_uri = sdk.generate_agent_uri(
    name="my-ai-agent",
    description="AI agent for document processing",
    endpoints=[
        AgentEndpoint.a2a("https://my-agent.example.com"),                      # A2A first (discovery doc URL)
        AgentEndpoint.mcp("https://my-agent.example.com/mcp", version="2025-06-18"),  # MCP second, if served
    ],
)
result = sdk.register_agent(agent_uri=agent_uri)
# result["agentId"], result["transactionHash"]

Quick start: provider (earn loop, headless)

No server needed. Watch for funded jobs, do the work, submit:

python

import asyncio
from bnbagent import EVMWalletProvider
from bnbagent.erc8183 import ERC8183JobOps, funded_job_watcher
from bnbagent.storage import LocalStorageProvider

wallet = EVMWalletProvider(password="...", private_key="0x...")
ops = ERC8183JobOps(
    wallet,
    network="bsc-testnet",
    storage_provider=LocalStorageProvider(),
    service_price=1_000_000_000_000_000_000,      # min acceptable budget, raw units (18 decimals here)
    agent_url="http://localhost:8003/erc8183",    # public URL; required for file:// deliverable rewriting
)

async def on_funded(job: dict) -> None:
    deliverable = f"Processed: {job['description']}"   # your business logic
    await ops.submit_result(job["jobId"], deliverable)

asyncio.run(funded_job_watcher(ops, on_funded, interval=30))

```
submit_result
```
handles verification (FUNDED status, assignment, expiry, budget ≥ service_price), deliverable upload, manifest hashing, and the
```
submit
```
tx.
The watcher never submits or settles by itself. Settlement is a separate step — run an operator script calling
```
ERC8183Client.settle(job_id)
```
after the dispute window elapses (
```
examples/auto_settle.py
```
,
```
examples/agent-server/scripts/settle.py
```
).

job

dict fields:

jobId

description

budget

client

provider

evaluator

status

(always

FUNDED

expiredAt

hook

Serving surface (A2A/MCP/HTTP) is your choice — copy-and-own references in
```
examples/a2a-agent/
```
(recommended) and
```
examples/agent-server/
```
(FastAPI).
Deliverable storage: placeholder URLs like
```
https://example.invalid/manifest.json
```
(as in
```
examples/client/happy.py
```
) are chain-only demos — voters cannot verify the deliverable. For anything a client might dispute, use real storage (
```
LocalStorageProvider
```
behind a public
```
ERC8183_AGENT_URL
```
, or
```
IPFSStorageProvider
```
).

Quick start: client (create and pay for a job)

python

import time
from bnbagent.erc8183 import ERC8183Client, JobStatus
from bnbagent.wallets import EVMWalletProvider

wallet = EVMWalletProvider(password="...", private_key="0x...")
erc8183 = ERC8183Client(wallet, network="bsc-testnet")

budget = 1 * (10 ** erc8183.token_decimals())   # DEMO-SCALE (1 full token). On MAINNET use tiny
                                                # budgets, e.g. (10 ** dec) // 100 for 0.01 U.
expired_at = int(time.time()) + 65 * 60

job_id = erc8183.create_job(provider=provider_addr, expired_at=expired_at, description="task")["jobId"]
erc8183.register_job(job_id)          # bind default policy (OptimisticPolicy)
erc8183.set_budget(job_id, budget)
erc8183.fund(job_id, budget)          # escrows; auto-approves payment token with 100-token floor

# ... provider submits ... dispute window elapses ...
erc8183.settle(job_id)                # permissionless — anyone can call
assert erc8183.get_job_status(job_id) == JobStatus.COMPLETED

Disputes and escape hatch:

python

erc8183.dispute(job_id)        # client only, within dispute window after submit
erc8183.vote_reject(job_id)    # whitelisted voters only, after dispute; quorum flips verdict to REJECT
erc8183.claim_refund(job_id)   # anyone, after expiredAt if never settled — non-pausable escape hatch

fund(job_id, amount, approve_floor=None)

: default approves

max(amount, 100 * 10**decimals)

to avoid re-approving across job streams;

approve_floor=0

approves exactly

amount

; no approve is sent if allowance already covers it.

Job lifecycle

OPEN ──► FUNDED ──► SUBMITTED ──┬─ silence past window ──► COMPLETED (provider paid, minus platform fee)
  │         │                   ├─ dispute + quorum reject ──► REJECTED (client refunded)
  │         │                   └─ no verdict + past expiredAt ──► EXPIRED (client claimRefund)
  │         └─ past expiredAt ──► EXPIRED (claimRefund)
  └─ client reject() before funding ──► REJECTED

Gas sponsorship matrix

Protocol / write	BSC Testnet	BSC Mainnet
ERC-8004 `register_agent`	✅ sponsored (MegaFuel)	✅ sponsored (MegaFuel) — works with a zero-BNB wallet
ERC-8183 create/fund/submit/settle	🟡 per-call: MegaFuel decides ( `fund` / `settle` sponsored today); declined calls self-pay	❌ never sponsored — all writes self-pay BNB
ERC-20 `approve` of payment token (sent inside `fund` when allowance short)	❌ always self-pays — fresh testnet buyer needs a little tBNB	❌ self-pays
twak wallet ops	❌ twak self-pays (twak-internal, SDK has no control)	✅ twak auto-sponsors — see `references/twak.md`

Networks & contracts

BSC Testnet (chain 97) — faucets: tBNB, U tokens

Contract	Address
Identity Registry (ERC-8004)	`0x8004A818BFB912233c491871b3d84c89A494BD9e`
AgenticCommerce	`0xa206c0517b6371c6638cd9e4a42cc9f02a33b0de`
EvaluatorRouter	`0xd7d36d66d2f1b608a0f943f722d27e3744f66f25`
OptimisticPolicy	`0x4f4678d4439fec812ac7674bb3efb4c8f5fb78a6`

BSC Mainnet (chain 56)

Contract	Address
Identity Registry (ERC-8004)	`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`
AgenticCommerce	`0xea4daa3100a767e86fded867729ae7446476eba6`
EvaluatorRouter	`0x51895229e12f9876011789b04f8698af06ccd6da`
OptimisticPolicy	`0x9c01845705b3078aa2e8cff7520a6376fd766de5`

The payment token address is NOT configurable — it is read from the Commerce kernel at runtime (

ERC8183Client.payment_token

). On mainnet it resolves to U (United Stables)

0xcE24…6666

(see the mainnet economics section at the top).

Notes:

The SDK constructor defaults to
```
network="bsc-testnet"
```
— always pass
```
network="bsc-mainnet"
```
explicitly (or
```
NETWORK=bsc-mainnet
```
) for mainnet work, and print
```
bscscan.com
```
(not
```
testnet.bscscan.com
```
) explorer links; some example scripts hardcode testnet URLs.
Discovery/indexer lag: the registry index may show a generic name (e.g.
```
Agent #198565
```
) even when your URI carries the real name. The on-chain URI is the source of truth; indexer names can lag or stay generic.

Environment variables

Full annotated reference:

references/env.example

. The essentials:

Variable	Required	Notes
`WALLET_PASSWORD`	Yes	Encrypts/decrypts the keystore at `~/.bnbagent/wallets/` .
`PRIVATE_KEY`	First run only	Imported and encrypted, then removable. Auto-generates a wallet if absent.
`WALLET_ADDRESS`	No	Pick a keystore when several exist.
`NETWORK`	No ( `bsc-testnet` )	Or `bsc-mainnet` .
`RPC_URL`	No	Custom RPC endpoint.
`ERC8183_SERVICE_PRICE`	No ( `1e18` )	Provider's minimum budget, raw units.
`ERC8183_AGENT_URL`	If LocalStorageProvider	Public base URL incl. `/erc8183` ; `file://` deliverable URLs get rewritten to it.
`STORAGE_API_KEY`	If IPFSStorageProvider	Pinata-compatible JWT.
`STORAGE_LOCAL_PATH`	No ( `.agent-data` )	Local deliverable dir.

Storage backend is chosen in code (pass

storage_provider=

), not by env var.

Security rules (important for agent flows)

EIP-712 signing is policy-gated by default.
```
EVMWalletProvider.sign_typed_data
```
only accepts EIP-3009
```
TransferWithAuthorization
```
/
```
ReceiveWithAuthorization
```
against U-token on BSC 56/97. EIP-2612
```
Permit
```
and Permit2
```
PermitSingle
```
/
```
PermitBatch
```
are denylisted unconditionally (they grant unbounded allowances — a malicious 402 server could drain the wallet). Never try to bypass this in agent-reachable code;
```
SigningPolicy.permissive()
```
and
```
_DANGEROUS_sign_typed_data_no_policy()
```
are tests-only.
Never hand tool functions a raw
WalletProvider
. Give them a scoped
```
X402Signer(wallet, max_value_per_call={token: ...}, session_budget={token: ...})
```
and always pass
```
expected_to
```
from config/on-chain registry — never from the 402 challenge body.

Custom tokens/types:

SigningPolicy.strict_default().extend(domain_allowlist={(chain_id, contract)}, primary_type_allowlist={"MyType"})

— the Permit denylist still wins.

```
claimRefund
```
is non-pausable and non-hookable: funds are always recoverable past
```
expiredAt
```
.
Throwaway/demo keys: use
```
EVMWalletProvider(persist=False)
```
so one-off keys never touch disk, and never reuse demo keys in production. Never paste production private keys into chat/logs — prefer the keystore +
```
WALLET_PASSWORD
```
flow.

Full rationale, decision tree, and examples:

references/sdk-readme.md

(Security section) and

examples/security/e2e.py

Wallet backends

EVMWalletProvider
(default) — Keystore V3 (MetaMask/Geth compatible), persistent at
```
~/.bnbagent/wallets/
```
or in-memory with
```
persist=False
```
.
TWAKProvider
(Trust Wallet Agent Kit) — self-custody, self-broadcasting; no raw-tx or generic EIP-712 signing; BSC only; x402 via delegated payer
```
make_x402_payer()
```
. Read
references/twak.md
before using — unsupported calls raise
```
UnsupportedWalletOperation
```
. Swap:
```
TWAKProvider(chain="bsc")
```
or
```
WALLET_KIND=twak
```
.
Custom (HSM, MPC, KMS): subclass
```
WalletProvider
```
. Details:
```
references/wallets.md
```
.

AA / self-broadcast wallets (Privy, ZeroDev, etc.) — known integration tax

Account-abstraction wallets that submit Intents/UserOperations instead of raw signed transactions are not first-class in the SDK yet (field-tested on BSC mainnet with a Privy AA client,

bnbagent==0.4.0

). What to expect and the workarounds that worked:

ERC-20
approve
fails:
```
approve_payment_token
```
goes through
```
_send_tx
```
→ raw
```
sign_transaction
```
, which AA wallets don't implement (
```
sign.transaction: wallet does not implement raw-transaction signing
```
). Workaround: do the
```
approve(commerce, amount)
```
on the payment token manually through your AA stack, then call
```
fund
```
with
```
fund_bundles_approval=True
```
.
```
create_job
```
/
```
set_budget
```
/
```
fund
```
themselves work through a custom Intent executor (subclass the executor /
```
WalletProvider
```
).
jobId
comes back
None
after
create_job
: AA wallets return a
```
user_operation_hash
```
, not a tx hash, and
```
create_job
```
only parses
```
jobId
```
from receipt logs. Workaround: wait for inclusion, then scan
```
jobCounter
```
backwards (or index recent jobs by
```
client
```
+
```
provider
```
+
```
description
```
) to find your job.
For a documented self-broadcasting wallet, use
```
TWAKProvider
```
(
```
references/twak.md
```
); Privy-style adapters are currently build-your-own.

Troubleshooting

Error	Cause → Fix
`No PRIVATE_KEY and no keystore found`	New wallet auto-generated, or set `PRIVATE_KEY` to import.
`Multiple wallets found`	Set `WALLET_ADDRESS=0x...` .
`403 Provider mismatch`	Job assigned to a different provider — check `job.provider` .
`409 Not FUNDED`	Job already submitted/settled.
`408 Job expired`	Past `expiredAt` ; client can `claimRefund` , create a new job.
`402 Budget below service price`	Client must fund ≥ `ERC8183_SERVICE_PRICE` .
`settle` reverts `policy pending`	Dispute window not elapsed and no dispute — wait, then retry. On mainnet the window is 7 days.
`voteReject` reverts `not voter` / `not disputed`	Caller not whitelisted or no dispute — use `examples/voter/vote_reject.py` .
Revert selector `0xcdbc1d27` on `register_job`	Job already bound to a policy — re-registering reverts by design. Treat as success if `job_policy(job_id)` is already set.
`sign.transaction: wallet does not implement raw-transaction signing`	AA/self-broadcast wallet hit the raw-tx `approve` path — see AA wallet section above.
`jobId` is `None` after `create_job`	AA wallet returned a user-op hash, no receipt to parse — scan `jobCounter` backwards for your job.
Allowance stays 0 after `fund` attempt	The bundled `approve` never landed (wrong wallet path) — manually `approve(commerce, amount)` , then `fund` .

Files in this skill

```
references/sdk-readme.md
```
— full upstream SDK README (deep detail on everything above)
```
references/architecture.md
```
— code map, layering, invariants
```
references/twak.md
```
— TWAK wallet support matrix and boundaries
```
references/wallets.md
```
— wallet provider deep dive
```
references/env.example
```
— annotated env var reference

examples/

— copy-and-own scripts:

client/

(5 canonical job flows),

a2a-agent/

agent-server/

voter/

twak/

x402/

security/

auto_settle.py

bnbagent

NPX Install

Tags

SKILL.md Content

BNBAgent SDK

⚠️ Mainnet economics — read BEFORE any mainnet commerce

Preflight balance checklist (mainnet)

Decide what you're doing

Quick start: register an agent (ERC-8004)

Quick start: provider (earn loop, headless)

Quick start: client (create and pay for a job)

Job lifecycle

Gas sponsorship matrix

Networks & contracts

Environment variables

Security rules (important for agent flows)

Wallet backends

AA / self-broadcast wallets (Privy, ZeroDev, etc.) — known integration tax

Troubleshooting

Files in this skill