Ctrlk
Launch App
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

PreviousBuilding Trading Agents on PancakeSwap V3NextCAKE Tokenomics

Last updated

Was this helpful?