Sweep External API
Sweep consolidates balances from one or more source chains into a single target token delivered to a recipient wallet. The integrator owns wallet connection, asset selection, user consent and transaction submission. Sweep owns route discovery, normalized economics, prepared calldata and settlement tracking.
The machine-readable contract is the
OpenAPI document. Every response carries
apiVersion: "1" and the X-Sweep-Api-Version: 1 header.
Responsibility boundary
| Side | Owns |
|---|---|
| Integrator frontend | Wallet connection, asset discovery, amount selection, consent UI, execution of prepared actions |
| Integrator backend | Partner secret, HMAC request signing, idempotency, durable attempt state, webhook verification |
| Sweep | Provider routing, source allocation, normalized output/fee/loss data, approval and execution calldata, on-chain verification, settlement status |
All calls to Sweep originate from the integrator backend. The partner secret must never enter a browser or mobile bundle.
End-to-end flow
user selects assets and amounts
-> POST /api/external/intents/quote quote + intentSessionId
-> user confirms the quoted plan
-> POST /api/external/intents/{id}/prepare chainActions + walletAuthorization
-> wallet signs the EIP-712 authorization
-> wallet executes each chainAction as returned
-> POST /api/external/attempts/{id}/submitted evidence (bundle id / tx hashes)
-> GET /api/external/attempts/{id}/status poll, or process webhooks
-> status = settled: target token is in the recipient walletAfter settled the delivered funds are in the user’s wallet. What the
integrator does with them next is outside the Sweep contract.
Vocabulary
| Term | Meaning |
|---|---|
| Intent session | A quote bound to the submitted sources and target; identified by intentSessionId, consumed by prepare |
| Attempt | One prepared execution of an intent session; identified by attemptId; owns the wallet authorization, evidence and status |
| Chain action | The per-source-chain unit of wallet execution returned by prepare |
| Leg | One source-to-target route slice inside a plan; settlement is reported per leg |
| Evidence | The bundle ids and transaction hashes reported to /submitted |
amountBasis | Provenance of a settled amount: exact (actual) or best available (estimated) |
| Partner backend | The integrator-owned server that holds the partner secret and signs every Sweep request |
Contents
- Become an integrator — registration and credentials
- Authentication — request signing and
GET /ping - Quote · Prepare · Submitted · Status · Webhooks
- Errors and retries
- Execution rules — wallet requirements, evidence, recovery
- Reference code — official SDK (
npm install sweep-external-sdk) and its full reference implementation
Last updated on