> For the complete documentation index, see [llms.txt](https://docs.pancakeswap.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pancakeswap.finance/trading-tools/building-trading-agents-on-pancakeswap-v3/reference-agent-order-intents-settlement-agent.md). # 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.pancakeswap.finance/trading-tools/building-trading-agents-on-pancakeswap-v3/reference-agent-order-intents-settlement-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.