Orchestrator API Reference

Base URL: https://api.sweepster.xyz

The orchestrator handles quote generation, intent submission, and status polling.

---

POST /quote

Request a sweep quote. This locks in the fee breakdown and returns the unsigned SweepOrder the user will sign.

Auth: None (rate-limited at 100 req/min per IP)

Rate limit: 100 requests per 60 seconds per IP

Request body

Field	Type	Required	Description
owner	string (hex address)	Yes	User's wallet address (0x... 40 hex digits)
tokenIn	string (hex address)	Yes	Source token contract address
amountIn	string (decimal)	Yes	Amount in token's smallest unit, e.g. "1000000" for 1 USDC
tokenOut	string (hex address)	Yes	Destination token contract address
destination	string (hex address)	Yes	Recipient address on destination chain
destChainId	number (integer)	Yes	Destination chain ID (e.g. 42161 for Arbitrum)
tier	"tier1" | "tier2" | "tier3"	Yes	Token risk tier (caller's hint; orchestrator may adjust)
route	string	No	Route hint, e.g. "base->arbitrum" or "base->base"
subscriptionActive	boolean	Yes	Whether the user has an active subscription (affects fee)
userId	string	Yes	Unique user identifier for fee policy
apiKey	string	No	Builder API key for off-chain attribution

Response 200

{
  "quote": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "crossChain": true,
    "expiresAtMs": 1717340400000,
    "total": "8000000",
    "builderId": "bld_abc123"
  },
  "order": {
    "owner": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amountIn": "1000000",
    "feeAmount": "5000000",
    "builder": "0xBuilderAddress",
    "builderFee": "3000000",
    "tokenOut": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "minAmountOut": "0",
    "destination": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    "swapTarget": "0xLIFIAddress",
    "swapCalldata": "0x...",
    "deadline": "1717340400",
    "nonce": "12345678",
    "destChainId": "42161"
  }
}

Notes:

• All uint256 fields in order are decimal strings (bigint-safe JSON)
• quote.total = feeAmount + builderFee as a decimal string
• minAmountOut is "0" for cross-chain orders (slippage is in swapCalldata)
• builderId is present only when builder attribution succeeded

Errors

Status	Body	Cause
422	{ "error": "..." }	Invalid input or token declined by risk engine
429	Rate limit	Too many requests

---

POST /intents

Submit a signed quote. The orchestrator atomically creates an intent and broadcasts (or queues) the source transaction.

Auth: None (rate-limited)

Request body

Field	Type	Required	Description
quoteId	string	Yes	The quote.id from POST /quote
signature	string (hex bytes)	Yes	The EIP-712 signature from the user (0x...)

Response 201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "submitted",
  "txHash": "0xabc..."
}

Field	Type	Description
id	string	Intent ID (same as quote ID)
status	IntentStatus	Current status — usually "submitted"
txHash	string?	Source tx hash (may be absent if not yet broadcast)

Errors

Status	Body	Cause
400	{ "error": "..." }	Unknown quoteId, expired quote, duplicate submission
422	{ "error": "..." }	Invalid signature format
429	Rate limit	Too many requests

---

GET /intents/:id

Poll the status of a submitted intent.

Auth: None

Path param: id — the intent ID (from POST /intents response)

Response 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "delivered",
  "txHash": "0xabc...",
  "crossChain": true
}

Field	Type	Description
id	string	Intent ID
status	IntentStatus	Current status
txHash	string?	Source tx hash
crossChain	boolean	Whether this is a cross-chain sweep

Intent status lifecycle

quoted → submitted → settled_source → delivered
                                    ↘ failed

Status	Meaning
quoted	Quote created, not yet submitted
submitted	Signature accepted; source tx broadcast
settled_source	Source settlement confirmed; delivery in progress
delivered	Destination delivery confirmed
failed	Unrecoverable failure

Errors

Status	Body	Cause
404	{ "error": "not found" }	Unknown intent ID

---

Rate limits

Public endpoints (/quote, /intents, GET /intents/:id) are rate-limited at 100 requests per 60 seconds per IP address by default.

Rate limit responses return HTTP 429.