{ "openapi": "3.1.0", "info": { "title": "Sweep External Intent API", "version": "1.0.0", "description": "Frozen v1 HTTP/response contract. Every response carries apiVersion \"1\" and X-Sweep-Api-Version: 1. Request-auth is selected by server-side partner config, never by client negotiation: version 1 is a frozen legacy scheme preserving HMAC_SHA256(secret, `${X-Timestamp}.${rawBody}`); version 2 is the scheme used for new partners and requires X-Sweep-Auth-Version: 2 and X-Nonce and signs the canonical method/path/idempotency/body-hash tuple documented in API_CONTRACT.md. One partner accepts exactly one algorithm. Canonical v2 permits only absent/identity Content-Encoding, prohibits GET bodies and Idempotency-Key on GET, and defines an empty POST body as SHA-256 of zero bytes. Mutating endpoints additionally require Idempotency-Key (1..255 chars). Outbound webhooks remain on the frozen version-1 timestamp/raw-body signature." }, "servers": [{ "url": "/api/external" }], "security": [{ "partnerId": [], "timestamp": [], "signature": [] }], "paths": { "/ping": { "get": { "operationId": "ping", "summary": "Auth and connectivity probe", "parameters": [ { "$ref": "#/components/parameters/RequestAuthVersion" }, { "$ref": "#/components/parameters/RequestNonce" } ], "responses": { "200": { "description": "Authenticated", "headers": { "X-Sweep-Api-Version": { "$ref": "#/components/headers/ApiVersionHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/intents/quote": { "post": { "operationId": "quoteIntent", "summary": "Quote a portfolio intent", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestAuthVersion" }, { "$ref": "#/components/parameters/RequestNonce" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "200": { "description": "Persisted quote. A newly created quote is ready, partial_only or unavailable. A repeated Idempotency-Key replays the stored session with its current quoteStatus, which is expired once expiresAt has passed.", "headers": { "X-Sweep-Api-Version": { "$ref": "#/components/headers/ApiVersionHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/intents/{intentSessionId}/prepare": { "post": { "operationId": "prepareIntent", "summary": "Build the exact executable transactions for a ready quote", "parameters": [ { "name": "intentSessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestAuthVersion" }, { "$ref": "#/components/parameters/RequestNonce" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareRequest" } } } }, "responses": { "200": { "description": "Prepared execution attempt (30s signable TTL). A repeated Idempotency-Key replays the stored attempt with its current status, which may already be wallet_submitted, provider_pending, settled, failed or expired.", "headers": { "X-Sweep-Api-Version": { "$ref": "#/components/headers/ApiVersionHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/attempts/{attemptId}/submitted": { "post": { "operationId": "reportSubmitted", "summary": "Report wallet execution evidence (additive, at-least-once)", "parameters": [ { "name": "attemptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestAuthVersion" }, { "$ref": "#/components/parameters/RequestNonce" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmittedRequest" } } } }, "responses": { "200": { "description": "Current attempt snapshot after recording the evidence", "headers": { "X-Sweep-Api-Version": { "$ref": "#/components/headers/ApiVersionHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/attempts/{attemptId}/status": { "get": { "operationId": "getAttemptStatus", "summary": "Canonical attempt status snapshot", "parameters": [ { "name": "attemptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/RequestAuthVersion" }, { "$ref": "#/components/parameters/RequestNonce" } ], "responses": { "200": { "description": "Attempt snapshot", "headers": { "X-Sweep-Api-Version": { "$ref": "#/components/headers/ApiVersionHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } } }, "webhooks": { "attemptLifecycle": { "post": { "operationId": "attemptLifecycleWebhook", "summary": "Signed lifecycle event delivered to the partner-configured callback URL", "description": "At-least-once, ordered per attempt. Webhooks deliberately keep the frozen HMAC_SHA256(secret, `${X-Timestamp}.${rawBody}`) algorithm regardless of inbound request-auth version. Headers: X-Partner-Id, X-Timestamp, X-Signature, X-Sweep-Event-Id, X-Sweep-Api-Version. Deduplicate by eventId before acknowledging with 2xx. /status remains canonical.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "2XX": { "description": "Event durably recorded by the partner" } } } } }, "components": { "securitySchemes": { "partnerId": { "type": "apiKey", "in": "header", "name": "X-Partner-Id", "description": "Trimmed partner identifier; canonical v2 requires 1..64 characters." }, "timestamp": { "type": "apiKey", "in": "header", "name": "X-Timestamp" }, "signature": { "type": "apiKey", "in": "header", "name": "X-Signature" } }, "parameters": { "RequestAuthVersion": { "name": "X-Sweep-Auth-Version", "in": "header", "required": false, "description": "Required with value 2 for every partner configured for canonical request auth, which is the scheme used for all new partners. The header cannot negotiate or downgrade the server-selected algorithm: it must match the server-side configuration, and a mismatch returns 401 external_auth_version_mismatch. Only partners still on the frozen legacy scheme omit it.", "schema": { "type": "string", "enum": ["1", "2"] } }, "RequestNonce": { "name": "X-Nonce", "in": "header", "required": false, "description": "Required for configured canonical-v2 partners. Reuse is accepted only for the exact same canonical request tuple; the binding is retained for at least 60 seconds beyond the authentication window.", "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9._~-]{16,128}$" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "headers": { "ApiVersionHeader": { "schema": { "type": "string", "const": "1" }, "description": "Frozen contract major version" } }, "responses": { "Error": { "description": "Stable error body; see the error-code registry in API_CONTRACT.md", "headers": { "X-Sweep-Api-Version": { "$ref": "#/components/headers/ApiVersionHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ApiVersion": { "type": "string", "const": "1" }, "ErrorResponse": { "type": "object", "required": ["apiVersion", "error"], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" } } }, "PingResponse": { "type": "object", "required": ["apiVersion", "ok", "partnerId"], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "ok": { "type": "boolean", "const": true }, "partnerId": { "type": "string" } } }, "QuoteRequest": { "type": "object", "required": ["walletAddress", "sources"], "properties": { "walletAddress": { "type": "string", "description": "EVM sender address (pilot: EVM-only sources)" }, "sources": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/SourceInput" } }, "target": { "$ref": "#/components/schemas/TargetInput", "description": "Single-output form; exactly one of target / targets per request" }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/TargetInput" }, "description": "Multi-output form with allocationPercent (portfolio-USD quotas); requires usdValue on every source" }, "recipient": { "type": "string" }, "slippageBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Slippage tolerance in basis points. Omit to accept the default of 50; 0 is rejected with invalid_slippage_bps." }, "allowPartial": { "type": "boolean" }, "maxWaitMs": { "type": "integer", "minimum": 1000, "maximum": 18000 }, "feeBps": { "type": "integer", "minimum": 0, "description": "Integrator markup in bps on top of Sweep's base rate. Strictly a JSON integer; numeric strings are rejected. The upper bound is the partner's configured maxFeeBps, which is 300 unless Sweep provisioned a different cap; exceeding it returns 400 invalid_fee_bps. Providers receive the combined base and markup rate; the markup is owed to the integrator off-chain. Absent means no markup." }, "allowedProviders": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderName" } }, "callbackUrl": { "type": "string" } } }, "SourceInput": { "type": "object", "required": ["chainId", "address", "amount", "decimals"], "properties": { "chainId": { "type": "integer" }, "address": { "type": "string" }, "amount": { "type": "string", "description": "Positive base-10 uint256 raw units" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255 }, "usdValue": { "type": "string" } } }, "TargetInput": { "type": "object", "required": ["chainId", "address", "targetToken"], "properties": { "id": { "type": "string" }, "chainId": { "type": "integer" }, "address": { "type": "string" }, "allocationPercent": { "type": "number" }, "targetToken": { "type": "object", "required": ["address", "decimals"], "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255 }, "priceUSD": { "type": "string" } } } } }, "PrepareRequest": { "type": "object", "properties": { "callbackUrl": { "type": "string", "description": "Must exactly match the partner-configured callback URL" }, "walletContext": { "type": "object", "properties": { "connectorName": { "type": "string" }, "connectorId": { "type": "string" }, "walletCapabilities": { "type": "object" } } } } }, "SubmittedRequest": { "type": "object", "required": ["chainResults"], "properties": { "submittedAt": { "type": ["number", "null"] }, "walletAuthorization": { "type": ["object", "null"], "description": "The executing wallet's EIP-712 signature over the prepare response's walletAuthorization typed data. It is required before Sweep promotes reported evidence to settlement. External API v1 supports EOA/EIP-7702 signers only; contract-wallet ERC-1271 signatures are rejected with 400 contract_wallet_unsupported.", "required": ["signature"], "properties": { "signature": { "type": "string", "description": "65-byte ECDSA signature (r,s,v) from an EOA or EIP-7702 wallet.", "pattern": "^0x[0-9a-fA-F]{130}$" } } }, "chainResults": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": ["chainId"], "properties": { "chainId": { "type": "integer" }, "bundleId": { "type": ["string", "null"] }, "txHashes": { "type": "array", "maxItems": 64, "items": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } }, "quoteResults": { "type": "array" } } } } } }, "ProviderName": { "type": "string", "enum": ["relay", "across", "mayan", "symbiosis", "fly"] }, "QuoteStatus": { "type": "string", "enum": ["ready", "partial_only", "unavailable", "expired"], "description": "A newly created quote is ready, partial_only or unavailable. expired is returned only when replaying the Idempotency-Key of a quote whose expiresAt has already passed; treat it as a dead quote and start a new one." }, "CoverageMode": { "type": "string", "enum": ["full", "partial", "none"] }, "AttemptStatus": { "type": "string", "enum": [ "prepared", "wallet_submitted", "provider_pending", "settled", "failed", "expired" ] }, "TargetToken": { "type": "object", "required": ["address", "chainId", "symbol", "decimals"], "properties": { "address": { "type": "string" }, "chainId": { "type": "integer" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" }, "logoUrl": { "type": "string" }, "priceUSD": { "type": ["string", "null"] } } }, "Target": { "type": "object", "required": [ "id", "chainId", "address", "allocationPercent", "targetToken" ], "properties": { "id": { "type": "string" }, "chainId": { "type": "integer" }, "address": { "type": "string" }, "allocationPercent": { "type": "number" }, "targetToken": { "$ref": "#/components/schemas/TargetToken" } } }, "SourceAllocation": { "type": "object", "required": [ "inputTokenIndex", "chainId", "address", "symbol", "decimals", "allocatedRawAmount", "allocatedAmount", "isNoop", "isSameSymbolRoute" ], "properties": { "inputTokenIndex": { "type": "integer" }, "chainId": { "type": "integer" }, "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" }, "logoUrl": { "type": "string" }, "allocatedRawAmount": { "type": "string" }, "allocatedAmount": { "type": "string" }, "allocatedUsdValue": { "type": ["string", "null"] }, "isNoop": { "type": "boolean" }, "isSameSymbolRoute": { "type": "boolean" } } }, "AllocationPlan": { "type": "object", "required": ["legs"], "properties": { "legs": { "type": "array", "items": { "type": "object", "required": [ "outputTargetId", "target", "sourceAllocations" ], "properties": { "outputTargetId": { "type": "string" }, "target": { "$ref": "#/components/schemas/Target" }, "sourceAllocations": { "type": "array", "items": { "$ref": "#/components/schemas/SourceAllocation" } } } } } } }, "LegOutputRef": { "type": "object", "required": ["chainId", "tokenAddress", "symbol", "decimals"], "properties": { "chainId": { "type": "integer" }, "tokenAddress": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" } } }, "LegEconomicSummary": { "type": "object", "required": [ "expectedOutputRaw", "minimumOutputRaw", "expectedOutputAmount", "minimumOutputAmount", "output" ], "properties": { "expectedOutputRaw": { "type": ["string", "null"] }, "minimumOutputRaw": { "type": ["string", "null"] }, "expectedOutputAmount": { "type": ["string", "null"] }, "minimumOutputAmount": { "type": ["string", "null"] }, "output": { "$ref": "#/components/schemas/LegOutputRef" }, "totalOutputUsd": { "type": ["number", "null"] }, "totalFeeUsd": { "type": ["number", "null"] }, "totalLossUsd": { "type": ["number", "null"] }, "timeEstimate": { "type": ["number", "null"] } } }, "FailedSource": { "type": "object", "required": [ "outputTargetId", "provider", "symbol", "address", "chainId", "reasonCode", "reason" ], "properties": { "outputTargetId": { "type": "string" }, "provider": { "oneOf": [ { "$ref": "#/components/schemas/ProviderName" }, { "type": "null" } ] }, "inputTokenIndex": { "type": ["integer", "null"] }, "symbol": { "type": "string" }, "address": { "type": "string" }, "chainId": { "type": "integer" }, "amount": { "type": ["string", "null"] }, "logoUrl": { "type": "string" }, "reasonCode": { "type": "string", "description": "Open set; documented values include no_allowed_provider, provider_unavailable, route_unavailable, same_chain_unsupported, provider_timeout" }, "reason": { "type": "string" } } }, "SelectedPlanLeg": { "type": "object", "required": [ "outputTargetId", "routeId", "provider", "target", "coveredSliceCount", "totalSliceCount", "requiredQuoteCount", "noopSliceCount", "isFullRoute", "summary", "failedSources" ], "properties": { "outputTargetId": { "type": "string" }, "routeId": { "type": "string" }, "provider": { "type": "string" }, "target": { "$ref": "#/components/schemas/Target" }, "coveredSliceCount": { "type": "integer" }, "totalSliceCount": { "type": "integer" }, "requiredQuoteCount": { "type": "integer" }, "noopSliceCount": { "type": "integer" }, "isFullRoute": { "type": "boolean" }, "summary": { "$ref": "#/components/schemas/LegEconomicSummary" }, "failedSources": { "type": "array", "items": { "$ref": "#/components/schemas/FailedSource" } } } }, "SelectedPlan": { "type": "object", "required": [ "isFullPlan", "coveredSliceCount", "totalSliceCount", "providerSet", "legs", "summary" ], "properties": { "isFullPlan": { "type": "boolean" }, "coveredSliceCount": { "type": "integer" }, "totalSliceCount": { "type": "integer" }, "providerSet": { "type": "array", "items": { "type": "string" } }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/SelectedPlanLeg" } }, "summary": { "type": "object", "properties": { "totalOutputUsd": { "type": ["number", "null"] }, "totalFeeUsd": { "type": ["number", "null"] }, "totalLossUsd": { "type": ["number", "null"] }, "timeEstimate": { "type": ["number", "null"] } } } } }, "RouteEvaluationEntry": { "type": "object", "required": [ "outputTargetId", "routeId", "provider", "coveredSliceCount", "totalSliceCount", "isFullRoute", "availability", "isSelected", "failedSources" ], "properties": { "outputTargetId": { "type": "string" }, "routeId": { "type": "string" }, "provider": { "type": "string" }, "coveredSliceCount": { "type": "integer" }, "totalSliceCount": { "type": "integer" }, "requiredQuoteCount": { "type": "integer" }, "noopSliceCount": { "type": "integer" }, "isFullRoute": { "type": "boolean" }, "availability": { "type": "string" }, "isSelected": { "type": "boolean" }, "isBestReturn": { "type": "boolean" }, "isFastest": { "type": "boolean" }, "expectedOutputRaw": { "type": ["string", "null"] }, "minimumOutputRaw": { "type": ["string", "null"] }, "expectedOutputAmount": { "type": ["string", "null"] }, "minimumOutputAmount": { "type": ["string", "null"] }, "output": { "oneOf": [ { "$ref": "#/components/schemas/LegOutputRef" }, { "type": "null" } ] }, "totalOutputUsd": { "type": ["number", "null"] }, "totalFeeUsd": { "type": ["number", "null"] }, "totalLossUsd": { "type": ["number", "null"] }, "timeEstimate": { "type": ["number", "null"] }, "failedSources": { "type": "array", "items": { "$ref": "#/components/schemas/FailedSource" } }, "rejectedQuoteCount": { "type": "integer" } } }, "RouteEvaluationGroup": { "type": "object", "required": [ "outputTargetId", "quoteStatus", "selectedRouteId", "evaluations" ], "properties": { "outputTargetId": { "type": "string" }, "quoteStatus": { "$ref": "#/components/schemas/QuoteStatus" }, "selectedRouteId": { "type": ["string", "null"] }, "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/RouteEvaluationEntry" } } } }, "QuoteResponse": { "type": "object", "required": [ "apiVersion", "quoteStatus", "intentSessionId", "expiresAt", "coverageMode", "allocationPlan", "selectedPlan", "failedSources", "routeEvaluations" ], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "quoteStatus": { "$ref": "#/components/schemas/QuoteStatus" }, "intentSessionId": { "type": "string" }, "expiresAt": { "type": "string" }, "coverageMode": { "$ref": "#/components/schemas/CoverageMode" }, "allocationPlan": { "$ref": "#/components/schemas/AllocationPlan" }, "selectedPlan": { "oneOf": [ { "$ref": "#/components/schemas/SelectedPlan" }, { "type": "null" } ] }, "failedSources": { "type": "array", "items": { "$ref": "#/components/schemas/FailedSource" } }, "routeEvaluations": { "type": "array", "items": { "$ref": "#/components/schemas/RouteEvaluationGroup" } } } }, "ChainCall": { "type": "object", "required": [ "to", "data", "value", "callId", "callIndex", "quoteIndex" ], "properties": { "to": { "type": "string" }, "data": { "type": "string" }, "value": { "type": "string" }, "gas": { "type": ["string", "null"] }, "callId": { "type": "string" }, "callIndex": { "type": "integer" }, "quoteIndex": { "type": "integer" } } }, "ChainTransaction": { "type": "object", "required": [ "to", "data", "value", "callId", "chainId", "callIndex", "quoteIndex" ], "properties": { "to": { "type": "string" }, "data": { "type": "string" }, "value": { "type": "string" }, "gas": { "type": ["string", "null"] }, "callId": { "type": "string" }, "chainId": { "type": "integer" }, "callIndex": { "type": "integer" }, "quoteIndex": { "type": "integer" } } }, "QuotePlan": { "type": "object", "required": [ "provider", "callCount", "callStart", "quoteIndex", "outputTargetId", "transactionCount" ], "properties": { "provider": { "type": "string" }, "callCount": { "type": "integer" }, "callStart": { "type": "integer" }, "quoteIndex": { "type": "integer" }, "outputTargetId": { "type": "string" }, "primaryCallIndex": { "type": ["integer", "null"] }, "sourceTokenCount": { "type": "integer" }, "transactionCount": { "type": "integer" } } }, "SourceTokenPreview": { "type": "object", "required": ["chain", "amount", "symbol", "address", "rawAmount"], "properties": { "chain": { "type": "string" }, "amount": { "type": "string" }, "symbol": { "type": "string" }, "address": { "type": "string" }, "logoUrl": { "type": "string" }, "usdValue": { "type": ["string", "null"] }, "rawAmount": { "type": "string" }, "networkLogo": { "type": "string" } } }, "PerLegPreview": { "type": "object", "required": [ "legIndex", "provider", "outputSymbol", "sourceTokens", "sourceChainId", "outputTargetId", "expectedOutputAmount", "expectedOutputFormatted" ], "properties": { "legIndex": { "type": "integer" }, "provider": { "type": "string" }, "outputSymbol": { "type": "string" }, "sourceTokens": { "type": "array", "items": { "$ref": "#/components/schemas/SourceTokenPreview" } }, "sourceChainId": { "type": "integer" }, "outputTargetId": { "type": "string" }, "expectedOutputUsd": { "type": ["string", "null"] }, "expectedOutputAmount": { "type": ["string", "null"] }, "expectedOutputFormatted": { "type": ["string", "null"] } } }, "ChainAction": { "type": "object", "required": [ "chainId", "provider", "submitMethod", "atomicRequired", "calls", "transactions", "transactionCount", "quoteCount", "quotePlans", "perLegPreview" ], "properties": { "chainId": { "type": "integer" }, "provider": { "type": "string" }, "submitMethod": { "type": "string", "enum": ["sendTransaction", "wallet_sendCalls"] }, "atomicRequired": { "type": "boolean" }, "calls": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/ChainCall" } }, "transactions": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/ChainTransaction" } }, "transactionCount": { "type": "integer" }, "quoteCount": { "type": "integer" }, "quotePlans": { "type": "array", "items": { "$ref": "#/components/schemas/QuotePlan" } }, "perLegPreview": { "type": "array", "items": { "$ref": "#/components/schemas/PerLegPreview" } } } }, "PrepareResponse": { "type": "object", "required": [ "apiVersion", "attemptId", "intentSessionId", "status", "expiresAt", "chainActions" ], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "attemptId": { "type": "string" }, "intentSessionId": { "type": "string" }, "status": { "$ref": "#/components/schemas/AttemptStatus", "description": "prepared on the first successful call. A replay of the same Idempotency-Key returns the attempt's current status, so it may be wallet_submitted, provider_pending, settled, failed or expired. Check it before executing chainActions." }, "expiresAt": { "type": "string", "description": "Signable window: until this instant it still makes sense for the user to start signing. Gate the Execute button on it." }, "evidenceDeadlineAt": { "type": "string", "description": "Reportable window: until this instant an execution the wallet already broadcast may still be reported to POST /submitted. It is derived from the attempt's execution tickets and is typically about 15 minutes." }, "chainActions": { "type": "array", "items": { "$ref": "#/components/schemas/ChainAction" } }, "walletAuthorization": { "type": ["object", "null"], "description": "EIP-712 typed data the executing wallet must sign; the signature is submitted with execution evidence and gates claim promotion.", "required": ["domain", "types", "primaryType", "message"], "properties": { "domain": { "type": "object" }, "types": { "type": "object" }, "primaryType": { "type": "string", "const": "SweepExecutionAuthorization" }, "message": { "type": "object", "required": [ "partnerId", "intentSessionId", "attemptId", "wallet", "recipient", "executionCommitment", "nonce", "expiresAt" ] } } } } }, "StatusLeg": { "type": "object", "required": [ "legIndex", "outputTargetId", "provider", "sourceChainId", "sourceTokens", "outputSymbol", "status", "txHash" ], "properties": { "legIndex": { "type": "integer" }, "outputTargetId": { "type": "string" }, "provider": { "type": "string" }, "sourceChainId": { "type": "integer" }, "sourceTokens": { "type": "array", "items": { "$ref": "#/components/schemas/SourceTokenPreview" } }, "outputSymbol": { "type": "string" }, "expectedOutputAmount": { "type": ["string", "null"] }, "expectedOutputFormatted": { "type": ["string", "null"] }, "expectedOutputUsd": { "type": ["string", "null"] }, "status": { "type": "string" }, "txHash": { "type": ["string", "null"] }, "sourceChainTxHash": { "type": ["string", "null"] }, "destinationChainTxHash": { "type": ["string", "null"] }, "settledAmount": { "type": ["string", "null"] }, "settledAmountBasis": { "type": ["string", "null"] }, "trackingContext": { "type": ["object", "null"] }, "errorCode": { "type": ["string", "null"] }, "errorMessage": { "type": ["string", "null"] } } }, "PerChainStatus": { "type": "object", "required": [ "chainId", "provider", "submitMethod", "atomicRequired", "status", "txHashes", "bundleId", "legs" ], "properties": { "chainId": { "type": "integer" }, "provider": { "type": "string" }, "submitMethod": { "type": "string", "enum": ["sendTransaction", "wallet_sendCalls"] }, "atomicRequired": { "type": "boolean" }, "status": { "type": "string" }, "txHashes": { "type": "array", "items": { "type": "string" } }, "bundleId": { "type": ["string", "null"] }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/StatusLeg" } } } }, "StatusResponse": { "type": "object", "required": [ "apiVersion", "attemptId", "intentSessionId", "partnerId", "walletAddress", "recipient", "status", "expiresAt", "submittedAt", "perChainStatus", "settledOutputs", "latestProviderTracking" ], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "attemptId": { "type": "string" }, "intentSessionId": { "type": "string" }, "partnerId": { "type": "string" }, "walletAddress": { "type": "string" }, "recipient": { "type": "string" }, "status": { "$ref": "#/components/schemas/AttemptStatus" }, "expiresAt": { "type": ["string", "null"] }, "evidenceDeadlineAt": { "type": ["string", "null"], "description": "Reportable deadline. `status` may still be `prepared` while `expiresAt` is in the past: signing is over, reporting is not. Derive reportability from this field, never from expiresAt." }, "submittedAt": { "type": ["number", "null"] }, "perChainStatus": { "type": "array", "items": { "$ref": "#/components/schemas/PerChainStatus" } }, "settledOutputs": { "type": "array", "items": { "type": "object" } }, "latestProviderTracking": { "type": "array", "items": { "type": "object" } } } }, "WebhookPayload": { "type": "object", "required": [ "eventId", "event", "occurredAt", "attemptId", "intentSessionId", "partnerId", "status", "currentStatus", "walletAddress", "recipient", "submittedAt", "perChainStatus", "settledOutputs" ], "properties": { "eventId": { "type": "string" }, "event": { "type": "string", "enum": [ "wallet_submitted", "provider_pending", "settled", "failed" ] }, "occurredAt": { "type": "string" }, "attemptId": { "type": "string" }, "intentSessionId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "type": "string" }, "currentStatus": { "$ref": "#/components/schemas/AttemptStatus" }, "walletAddress": { "type": "string" }, "recipient": { "type": "string" }, "submittedAt": { "type": ["number", "null"] }, "perChainStatus": { "type": "array", "items": { "$ref": "#/components/schemas/PerChainStatus" } }, "settledOutputs": { "type": "array", "items": { "type": "object" } } } } } } }