Reference Agent — Order/Intents Settlement Agent

An ERC-8183 Provider agent that fulfills a single swap-intent Job at a time by routing it through PancakeSwap aggregation and delivering the target token directly to the Client.

0. How it maps to ERC-8183

ERC-8183 (Agentic Commerce; Virtuals + Ethereum Foundation) defines a Job with three roles and states Open → Funded → Submitted → Terminal. BNB’s BNBAgent SDK is the live implementation.

Role	In this agent
Client (Agent-A)	posts a swap intent: “swap X of token A → token B, deliver me ≥ minOut”, escrows the input + a tip
Provider (Agent-B) — this is our reference agent	quotes via PancakeSwap aggregation, and if it can meet/beat minOut, executes the swap and delivers token B to the Client
Evaluator	verifies the Client received token-B amount ≥ minOut; releases the tip (or refunds the Client)

The deliverable is objective (“did the Client receive ≥ minOut?”), which is exactly why this fits ERC-8183 where the rebalancer didn’t.

---

1. Purpose & one-line scope

A Provider agent that fulfills a single swap-intent Job at a time by routing it through PancakeSwap aggregation and delivering the target token directly to the Client — and nothing else.

---

2. What the agent is ALLOWED to do (capability allowlist)

#	Capability	Surface	Notes
A	Discover open Jobs	BNBAgent SDK (ERC-8183 registry)	Read-only; filter to swap-intent Jobs it can serve
B	Quote a route	PancakeSwap aggregation (Aggregator API / Smart Router)	Read-only; best price across V3
C	Accept a Job	BNBAgent SDK (Funded → committed)	Only if its fresh quote ≥ minOut and tip ≥ floor
D	Execute the swap	PancakeSwap router	Input pulled from Job escrow; output recipient = the Client, in one tx
E	Submit the deliverable	BNBAgent SDK (→ Submitted)	The settlement tx hash as proof
F	Claim the tip	ERC-8183 escrow / x402	Only after the Evaluator marks the Job Terminal

Output of every settlement goes directly to the Client. The agent’s only earning is the Job’s tip.

---

3. Hard guardrails (the gate to featuring)

Guardrail	Rule
Never accept what it can’t fulfill	Accept a Job only if a fresh quote clears minOut. If it can’t, leave the Job Funded for another Provider.
Requote at execution	Re-quote immediately before settling; abort if the route no longer clears minOut (no stale quotes).
Atomic settlement	Pull-from-escrow → swap → deliver to Client in one transaction, output recipient = Client. The agent must never hold the Client’s funds across a failed step.
Slippage	Execution slippage bounded; delivered amount must still be ≥ minOut after slippage, or the tx reverts. Never amountOutMin = 0.
Deadline	Short deadline on the settlement tx (≤ 5 min); respect the Job’s own deadline.
Min tip / max value	Don’t accept Jobs below a tip floor or above a per-Job value cap.
Token safelist	Only serve Jobs whose tokens are on the PancakeSwap token list (anti-honeypot / fake-token).
Single-Job concurrency (v1)	Fulfill one Job at a time; no over-commitment.
Gas precondition	Confirm enough BNB for the full settlement before accepting.
Idempotent	Never double-submit or re-fulfill a Job already Submitted/Terminal.

If any rule can’t be met, skip the Job — never force a settlement.

---

4. Out of scope — the agent MUST NOT

1. Use Client funds for anything but the specified swap. Output recipient is always the Client.
2. Front its own inventory / take principal risk. v1 is escrow-pull only — it routes the Client’s escrowed input; it does not fill from its own balance.
3. Route through non-PancakeSwap or unverified contracts, or settle outside PancakeSwap aggregation.
4. Serve Jobs with non-safelisted tokens, or (v1) any scaled-UI / RWA token (§5).
5. Use leverage, perps, margin, or lending.
6. Submit a deliverable it didn’t actually fulfill (no false attestation) or evaluate its own Jobs (conflict of interest).
7. Call any owner/admin function on PancakeSwap or the ERC-8183 contracts.
8. Hold standing token approvals beyond a single settlement; scope approvals to the Job amount.

---

5. PancakeSwap-specific logic (application correctness)

• Route via PancakeSwap aggregation, not a single pool — best execution across V2 / V3 / Stable is the whole value proposition (“best price wins the tip”).
• Deliver atomically to the Client by setting the router’s recipient to the Client address; never a two-step “swap to self, then transfer.”
• Quote freshness — the on-chain price moves between discovery and settlement; requote at execution (guardrail §3).
• minOut is in raw units. For scaled-UI / ERC-8056 tokens (Binance Stock Tokens / RWA equities) raw ≠ displayed; mishandling silently mis-delivers. Exclude scaled-UI tokens from v1 until eng confirms raw-unit handling end-to-end.
• Slippage minimum on the settlement swap must be derived so the delivered amount ≥ minOut, accounting for the tip/fee split.

---

6. Failure & recovery behavior

• Quote fails minOut at execution → abort before/atomically with the escrow pull; the Job stays Funded for another Provider. No partial state.
• Already Submitted/Terminal → skip (idempotent).
• Settlement tx reverts → Job remains claimable by others; the agent records the failure and moves on.
• Repeated failures on a Job → blacklist that Job locally and alert, rather than retry-looping.

---

7. Integration points (the BNB / ERC-8183 half)

These are provided by BNB Agent Studio / BNBAgent SDK, not built by PancakeSwap — but the spec depends on them:

• Job lifecycle (discover Open → accept Funded → Submitted → claim) via BNBAgent SDK.
• Provider identity via ERC-8004.
• Escrow + payout via the ERC-8183 escrow / x402.
• Evaluator — the predicate must be “Client’s token-B balance increased by ≥ minOut.” Confirm with BNB who runs the Evaluator (neutral/protocol vs. Client) and that the predicate is enforceable on-chain.

---

8. Recommended v1 posture & open decisions

1. Escrow-pull only, single Job at a time, token-safelist only, no scaled-UI tokens. Smallest safe surface to feature at launch.
2. Confirm the PancakeSwap swap interface — the Aggregator (aggr) HTTP API vs the Smart Router SDK. Jerry’s note says “use pcs aggr api”; needs confirming which the agent calls, as it changes the integration (and whether the guide needs an aggregation section).
3. Confirm the escrow mechanic with BNB — can the Provider pull the Client’s escrowed input to route the swap, and is delivery-to-Client enforceable as the deliverable?
4. Confirm the Evaluator owner and predicate (§7).

Eng sign-off before featuring: atomic escrow-pull → swap → deliver-to-Client routing; requote-at-execution; minOut-after-slippage math; safelist enforcement; idempotent Job handling.