--- name: darklabz-agentxchange description: Use DarkLabz AgentXchange for programmable cross-chain exchange flows inside SpendHub: asset discovery, route checks, quoting, destination validation, swap creation, deposit instructions, webhook-backed settlement tracking, and policy-constrained agent execution. --- # DarkLabz AgentXchange AgentXchange is the SpendHub exchange rail for autonomous agents. It gives agents a normalized interface for discovering supported asset/network pairs, requesting quotes, validating destination addresses, creating swaps, and tracking settlement across providers. ## What it is AgentXchange is not a raw provider passthrough. It should behave like a clean agent control surface: - query supported assets and networks - query route availability - request normalized quotes - validate destination addresses - create live trades - receive deposit instructions - follow trade lifecycle with normalized statuses Verified live examples right now: - sell: **USDC on Base** → buy: **BTC on Bitcoin mainnet** - sell: **ETH on Base** → buy: **SOL on Solana** AgentXchange is no longer limited to a single flagship pair. It now uses broader provider-backed live bridge rails with dynamic route shaping per requested pair. ## Product stance The correct current shape is: - **queryable universe:** broad - **executable universe:** broader than the original flagship pair, but still policy-constrained Agents should be able to ask what assets and routes are available. Execution now rides the provider-backed `bridge.crosschain` path for supported live pairs, while still preserving validation and policy controls. ## Rules - Prefer normalized AgentXchange endpoints over provider-native query strings. - Allow many assets to be queried, and allow supported live provider-backed bridge pairs to execute. - Reference verified live paths: `USDC/base -> BTC/bitcoin` and `ETH/base -> SOL/solana`. - Always validate the destination address before creating a live trade. - Strongly prefer collecting a refund address before creating a trade. - Surface provider KYC/log-policy metadata to the caller; do not hide it. - Make KYC/log-policy filtering explicit in the request/response model. - Distinguish clearly between `fixed` and `floating` rate flows. - If quote expiry exists, treat it as first-class state. - Use webhook delivery plus durable reads for status changes. - Persist raw provider responses for audit/debug, but do not expose them as the primary interface. - Do not let agents perform arbitrary, uncapped, policy-free swaps. - Add min/max size controls and approval thresholds before broadening execution. ## Recommended V1 API surface - `GET /api/exchange/assets` - `POST /api/exchange/routes` - `POST /api/exchange/quote` - `POST /api/exchange/validate-address` - `POST /api/exchange/trade` - `GET /api/exchange/trade/:id` - `POST /api/exchange/webhooks/trocador` ## Endpoint intent ### `GET /api/exchange/assets` Purpose: - discover supported assets - discover networks per asset - understand directionality (`sell`, `buy`, or both) - expose provider availability/minimums when known ### `POST /api/exchange/routes` Purpose: - check whether a route is currently possible - show provider options - expose fixed/floating support - expose KYC/log-policy metadata for each candidate route - optionally return min/max hints Recommended request filters: - `minKycRating`: minimum acceptable KYC/privacy rating from the provider metadata model - `minLogPolicy`: minimum acceptable log/privacy policy rating from the provider metadata model - `bestOnly`: when `true`, return only the single best route that still satisfies policy Recommended normalized route fields: - `kycRequired: boolean` - `kycRating: string | null` - `logPolicy: string | null` - `rateType: "fixed" | "floating"` - `provider: string` - `providerRouteId?: string` - `minAmount?: string | number` - `maxAmount?: string | number` ### `POST /api/exchange/quote` Purpose: - request a normalized quote - return provider, rate type, amount out, and route metadata - reject or mark routes that do not satisfy requested KYC/log-policy thresholds ### `POST /api/exchange/validate-address` Purpose: - verify that the destination address matches the requested asset/network ### `POST /api/exchange/trade` Purpose: - create the live swap - return deposit instructions and the normalized trade record ### `GET /api/exchange/trade/:id` Purpose: - fetch current normalized trade state - expose user-safe lifecycle status - show expected vs actual receive values when known ### `POST /api/exchange/webhooks/trocador` Purpose: - ingest provider status updates - advance trade state idempotently - reconcile provider events into SpendHub status language ## KYC / non-KYC route filtering AgentXchange should let callers separate privacy-preserving routes from routes that may require stronger identity checks. Recommended caller behavior: - For **non-KYC-preferred** flows, call `POST /api/exchange/routes` with a strict privacy policy and only present routes whose metadata indicates no KYC requirement. - For **KYC-allowed** flows, allow routes with stronger KYC ratings when they otherwise satisfy asset/network/amount constraints. - Re-check policy again at `quote` time so a route cannot pass discovery and then silently switch into a worse policy bucket. Recommended normalized request shape: ```json { "fromAsset": "ETH", "fromNetwork": "base", "toAsset": "SOL", "toNetwork": "solana", "amountFrom": "2.00", "destinationAddress": "9xQeWvG816bUx9EPjHmaT23yvVMvK2V9fP9d9onVg8iN", "refundAddress": "0xrefundexample...", "rateType": "floating", "minKycRating": "A", "minLogPolicy": "A", "bestOnly": true } ``` Recommended interpretation: - `minKycRating` and `minLogPolicy` are policy filters, not decoration. - Route discovery should exclude routes that do not satisfy the requested thresholds. - Quote creation should enforce the same thresholds again before returning a live quote. - Trade creation should refuse off-policy routes or send them to `manual_review`. Important current implementation note: - The normalized AgentXchange request shape already carries `minKycRating`, `minLogPolicy`, and `bestOnly`. - However, if execution is currently mapped onto the live `bridge.crosschain` Trocador path, those filters are **not yet enforced directly by the provider create call**. - That means AgentXchange should treat KYC/log-policy filtering as an explicit normalization-layer responsibility until provider-side route metadata is wired cleanly into `routes` and `quote` responses. Practical Trocador note: - For AnonPay-style flows, Trocador supports a `min_kycrating` parameter on the provider URL/link flow. - For the current `new_bridge` bridge execution path, this skill should not claim that KYC filtering is already fully solved unless the route-discovery layer is actually reading provider metadata and enforcing it before trade creation. ## Normalized statuses Use one internal state machine regardless of provider wording: - `route_unavailable` - `quoted` - `quote_expired` - `awaiting_deposit` - `deposit_detected` - `exchanging` - `sending` - `completed` - `refunded` - `failed` - `manual_review` ## Recommended trade lifecycle 1. Agent checks supported assets/networks. 2. Agent checks route availability. 3. Agent requests quote. 4. Agent validates destination address. 5. Agent creates trade. 6. Agent/user sends funds to returned deposit address. 7. AgentXchange receives provider webhook updates. 8. Agent polls or reads normalized trade status until `completed`, `failed`, or `refunded`. ## Safety / policy expectations V1 should not be an unrestricted exchange robot. Recommended controls: - asset allowlists - network allowlists - min/max size limits - explicit rate type selection - optional approval thresholds above configured amounts - mandatory/manual review path for off-policy routes - refund-address requirement for higher-risk flows - event/audit logging for every state transition ## V1 build order 1. multi-asset discovery 2. route availability 3. quote endpoint 4. destination validation 5. trade creation 6. webhook-backed trade status 7. verified live path testing across multiple provider-backed rails (for example Base USDC → BTC mainnet and Base ETH → SOL) ## Do not oversell v1 Do not describe AgentXchange as: - infinite-asset autopilot - arbitrary agent-controlled money movement - custodyless magic with no risk surface - provider-free execution The stronger claim is better: > AgentXchange is a programmable exchange rail for agents with route discovery, normalized quote/create/status flows, and policy-constrained cross-chain execution.