{ "openapi": "3.1.0", "info": { "title": "PWS Public API", "version": "1", "description": "Integrate with Payward Services to onboard users, manage accounts and funds, trade assets, and receive event notifications.", "contact": { "name": "Payward Services" } }, "servers": [ { "url": "https://api.sandbox.services.payward.com" } ], "tags": [ { "name": "Assets", "description": "List the assets PWS is willing to swap.", "x-displayName": "Assets" }, { "name": "Conversions", "description": "Rule-driven and on-demand fiat ↔ crypto value movement, including conversion rules and deposits.", "x-displayName": "Conversions" }, { "name": "Auto Earn", "description": "Manage Auto Earn preferences and retrieve allocation and reward information.", "x-displayName": "Auto Earn" }, { "name": "Bonded Earn", "description": "Allocate funds to and deallocate funds from bonded earn strategies, review allocations, and track request status.", "x-displayName": "Bonded Earn" }, { "name": "Funding", "description": "Discover deposit and withdrawal options, manage deposit addresses, and move funds between accounts.", "x-displayName": "Funding" }, { "name": "Derivative transfers", "description": "Move funds between an account's spot balance and the same owner's futures balance.", "x-displayName": "Derivative transfers" }, { "name": "Portfolio", "description": "Inspect a customer's portfolio: balances, valuations, and transactions.", "x-displayName": "Portfolio" }, { "name": "Ramp", "description": "Support Ramp flows with discovery, quotes, limits, and hosted checkout experiences.", "x-displayName": "Ramp" }, { "name": "Reports", "description": "Settlement and reconciliation reports for the partner.", "x-displayName": "Reports" }, { "name": "Swaps", "description": "Account-funded quotes that lock a price until they expire or are executed.", "x-displayName": "Swaps" }, { "name": "Onchain quotes", "description": "Wallet-funded quotes that return the data needed to settle onchain.", "x-displayName": "Onchain quotes" }, { "name": "Price trigger swaps", "description": "Swaps that wait for a target price before submitting a trade.", "x-displayName": "Price trigger swaps" }, { "name": "Travel Rule verifications", "description": "Travel Rule address ownership verification flows.", "x-displayName": "Travel Rule verifications" }, { "name": "Users", "description": "User onboarding and status flows that the partner manages.\n\n- **Create User** provisions an account-owned user from an external reference and optional email.\n- **Get User** retrieves the user's profile, verification status, and required actions.\n\nUse the returned user `id` for calls that require the user's identifier.", "x-displayName": "Users" }, { "name": "Verifications", "description": "Identity verification (KYC) submission and status for end users.", "x-displayName": "Verifications" }, { "name": "Webhooks", "description": "Register HTTPS destinations to receive event deliveries, rotate signing secrets, and inspect, update, or delete existing subscriptions. Each subscription is owned by the authenticated partner; deliveries are signed with HMAC-SHA256 and retried on transient failures.", "x-displayName": "Webhooks" } ], "paths": { "/v1/assets": { "get": { "tags": [ "Assets" ], "description": "List assets available on the platform.\n\nThe response includes each asset's symbol, type, display metadata, market data, and per-action availability. Use the optional filters to narrow the list by asset type or by whether an asset is enabled for swap trading, withdrawals, or deposits.\n\nPublic endpoint: unauthenticated by design. Geo restrictions are applied from the required `country` query parameter.", "operationId": "listAssets", "parameters": [ { "in": "query", "name": "country", "schema": { "description": "ISO 3166-1 alpha-2 country code used to apply geo restrictions (e.g., \"US\", \"GB\"). Required.", "type": "string", "pattern": "^[A-Z]{2}$" }, "style": "form", "example": "DE", "required": true }, { "in": "query", "name": "type", "schema": { "description": "Filter assets by classification. Repeat the parameter to filter on multiple types.", "type": "array", "default": [], "items": { "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "minItems": 0, "maxItems": 4 }, "style": "form", "example": [ "crypto" ] }, { "in": "query", "name": "swap_trading", "schema": { "description": "Filter to assets that are currently enabled for swap trading. Omit to ignore this dimension.", "type": "boolean" }, "style": "form", "example": true }, { "in": "query", "name": "withdraw", "schema": { "description": "Filter to assets that are currently enabled for withdrawal. Omit to ignore this dimension.", "type": "boolean" }, "style": "form", "example": true }, { "in": "query", "name": "deposit", "schema": { "description": "Filter to assets that are currently enabled for deposit. Omit to ignore this dimension.", "type": "boolean" }, "style": "form", "example": true }, { "in": "query", "name": "sort", "schema": { "$ref": "#/components/schemas/Assets_SortField" }, "style": "form", "example": "market_cap_rank" }, { "in": "query", "name": "sort_direction", "schema": { "description": "Direction of the sort. Use asc for natural ascending order (rank 1 first, oldest first, lowest first); desc for the inverse.", "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "style": "form", "example": "desc" }, { "$ref": "#/components/parameters/Assets_PageSize" }, { "$ref": "#/components/parameters/PageToken" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Symbol of the asset to use as the quote currency for valuations.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Classification of the quote asset. Currently only fiat is supported.", "type": "string", "enum": [ "fiat" ], "default": "fiat" }, "style": "form", "example": "fiat" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The list of matching assets.", "type": "array", "items": { "$ref": "#/components/schemas/Assets_Asset" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Quote asset symbol the prices are denominated in (resolved, defaults to USD).", "type": "string" }, "quote_type": { "description": "Classification of the quote asset (resolved, defaults to fiat).", "$ref": "#/components/schemas/Assets_QuoteAssetType" }, "page_size": { "description": "Maximum number of results returned on this page (resolved, defaults to 20).", "type": "integer", "format": "int32", "minimum": 1, "maximum": 100 }, "sort": { "description": "Field the results were sorted by (resolved, defaults to market_cap_rank).", "$ref": "#/components/schemas/Assets_SortField" }, "sort_direction": { "description": "Direction the results were sorted in (resolved, defaults to asc).", "type": "string", "enum": [ "asc", "desc" ] }, "type": { "description": "Asset classifications the listing was filtered to. Empty when no type filter was applied.", "type": "array", "items": { "$ref": "#/components/schemas/Assets_CatalogAssetType" } }, "swap_trading": { "description": "Swap-trading filter that was applied, echoed back. Absent when not filtered.", "type": "boolean" }, "withdraw": { "description": "Withdrawal filter that was applied, echoed back. Absent when not filtered.", "type": "boolean" }, "deposit": { "description": "Deposit filter that was applied, echoed back. Absent when not filtered.", "type": "boolean" } }, "required": [ "data", "quote_symbol", "quote_type", "page_size", "sort", "sort_direction" ] }, "examples": { "first-page": { "summary": "First page of assets across crypto, fiat, and xStocks", "value": { "data": [ { "symbol": "BTC", "type": "crypto", "name": "Bitcoin", "website": "https://bitcoin.org/", "docs": "https://bitcoin.org/bitcoin.pdf", "description": "Bitcoin is the world's largest cryptocurrency project.", "listing_date": "2013-10-06", "price": "62081.0000", "market_cap": "1244183483835", "market_cap_rank": 1, "trending_rank": 66, "volume": { "last_24h": "53096507160" }, "supply": { "circulating": "20038918", "total": "20038918", "max": "21000000", "in_quote": { "circulating": "1244036068358", "total": "1244036068358", "max": "1303701000000" } }, "price_range": { "high_24h": "63120.0000", "low_24h": "61540.0000", "high_1y": "73750.0000", "low_1y": "24900.0000" }, "price_change_percent": { "last_1h": "-0.31", "last_24h": "-0.58", "last_7d": "-15.62", "last_30d": "-24.56", "last_1y": "-40.69" }, "ath": { "value": "126080.0000", "timestamp": "2025-10-06T18:57:42Z" }, "buy_rate": "65.00", "market_dominance": "52.40", "status": { "swap_trading": { "enabled": true, "disabled_against": [ { "symbol": "USDT", "type": "stablecoin" }, { "symbol": "SOL", "type": "crypto" } ] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_btc.webp", "type": "image/webp" }, "decimals": { "funding": 8, "swap": 10 } }, { "symbol": "ETH", "type": "crypto", "name": "Ethereum", "listing_date": "2015-08-07", "price": "1659.8600", "market_cap": "200269280850", "market_cap_rank": 2, "trending_rank": 55, "volume": { "last_24h": "27036726996" }, "price_range": { "high_24h": "1688.4000", "low_24h": "1642.1000" }, "price_change_percent": { "last_1h": "-0.53", "last_24h": "-4.92", "last_7d": "-17.38", "last_30d": "-31.16", "last_1y": "-36.02" }, "ath": { "value": "4946.0500", "timestamp": "2025-08-24T19:21:03Z" }, "status": { "swap_trading": { "enabled": true, "disabled_against": [ { "symbol": "USDT", "type": "stablecoin" }, { "symbol": "SOL", "type": "crypto" } ] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_eth.webp", "type": "image/webp" }, "decimals": { "funding": 10, "swap": 10 } }, { "symbol": "USD", "type": "fiat", "name": "US Dollar", "listing_date": "2013-10-06", "status": { "swap_trading": { "enabled": true, "disabled_against": [ { "symbol": "AED", "type": "fiat" }, { "symbol": "USDT", "type": "stablecoin" } ] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_usd.webp", "type": "image/webp" }, "decimals": { "funding": 2, "swap": 4 } }, { "symbol": "TSLAx", "type": "xstock", "name": "Tesla, Inc.", "listing_date": "2025-06-30", "price": "248.5000", "market_cap": "799000000000", "market_cap_rank": 12, "trending_rank": 8, "volume": { "last_24h": "1203456789" }, "price_change_percent": { "last_1h": "0.15", "last_24h": "-1.02", "last_7d": "3.44", "last_30d": "-2.10", "last_1y": "18.73" }, "ath": { "value": "488.5400", "timestamp": "2025-01-31T20:00:00Z" }, "status": { "swap_trading": { "enabled": true, "disabled_against": [] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_tslax.webp", "type": "image/webp" }, "decimals": { "funding": 8, "swap": 8 } } ], "quote_symbol": "USD", "quote_type": "fiat", "page_size": 20, "sort": "market_cap_rank", "sort_direction": "asc", "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } }, "last-page": { "summary": "Last page of results; `next_page_token` is omitted", "value": { "data": [ { "symbol": "GBP", "type": "fiat", "name": "Pound Sterling", "listing_date": "2013-10-06", "status": { "swap_trading": { "enabled": true, "disabled_against": [] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_gbp.webp", "type": "image/webp" }, "decimals": { "funding": 2, "swap": 4 } } ], "quote_symbol": "USD", "quote_type": "fiat", "page_size": 20, "sort": "market_cap_rank", "sort_direction": "asc" } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/assets-bad-request" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/assets-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/assets-forbidden" } } } } }, "404": { "description": "Not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/assets-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/assets-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/assets-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/assets-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/assets-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/assets-deadline-exceeded" } } } } } }, "summary": "List assets", "security": [] } }, "/v1/assets/{asset_type}/{asset_symbol}": { "get": { "tags": [ "Assets" ], "description": "Get information about a specific asset.\n\nPublic endpoint: unauthenticated by design. Geo restrictions are applied from the required `country` query parameter.", "operationId": "getAsset", "parameters": [ { "in": "query", "name": "country", "schema": { "description": "ISO 3166-1 alpha-2 country code used to apply geo restrictions (e.g., \"US\", \"GB\"). Required.", "type": "string", "pattern": "^[A-Z]{2}$" }, "style": "form", "example": "DE", "required": true }, { "in": "path", "name": "asset_type", "required": true, "schema": { "description": "Classification of the asset (fiat, crypto, stablecoin, or xstock).", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "style": "simple", "example": "crypto" }, { "in": "path", "name": "asset_symbol", "required": true, "schema": { "description": "Ticker symbol of an asset (e.g., BTC, USDC, EUR).", "$ref": "#/components/schemas/AssetSymbol" }, "style": "simple", "example": "BTC" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Ticker symbol of the quote asset for valuations.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Classification of the quote asset. Pair with quote_symbol to disambiguate when the same ticker exists across asset classes.", "type": "string", "enum": [ "fiat" ], "default": "fiat" }, "style": "form", "example": "fiat" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The requested asset.", "$ref": "#/components/schemas/Assets_Asset" }, "quote_symbol": { "description": "Quote asset symbol the prices are denominated in.", "type": "string" }, "quote_type": { "description": "Classification of the quote asset.", "$ref": "#/components/schemas/Assets_QuoteAssetType" } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "btc": { "summary": "Full BTC asset payload for an unrestricted user", "value": { "data": { "symbol": "BTC", "type": "crypto", "name": "Bitcoin", "website": "https://bitcoin.org/", "docs": "https://bitcoin.org/bitcoin.pdf", "description": "Bitcoin is the world's largest cryptocurrency project.", "listing_date": "2013-10-06", "price": "62081.0000", "market_cap": "1244183483835", "market_cap_rank": 1, "trending_rank": 66, "volume": { "last_24h": "53096507160" }, "supply": { "circulating": "20038918", "total": "20038918", "max": "21000000", "in_quote": { "circulating": "1244036068358", "total": "1244036068358", "max": "1303701000000" } }, "price_range": { "high_24h": "63120.0000", "low_24h": "61540.0000", "high_1y": "73750.0000", "low_1y": "24900.0000" }, "price_change_percent": { "last_1h": "-0.31", "last_24h": "-0.58", "last_7d": "-15.62", "last_30d": "-24.56", "last_1y": "-40.69" }, "ath": { "value": "126080.0000", "timestamp": "2025-10-06T18:57:42Z" }, "buy_rate": "65.00", "market_dominance": "52.40", "status": { "swap_trading": { "enabled": true, "disabled_against": [ { "symbol": "USDT", "type": "stablecoin" }, { "symbol": "SOL", "type": "crypto" } ] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_btc.webp", "type": "image/webp" }, "decimals": { "funding": 8, "swap": 10 } }, "quote_symbol": "USD", "quote_type": "fiat" } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/assets-bad-request" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/assets-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/assets-forbidden" } } } } }, "404": { "description": "Asset not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/assets-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/assets-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/assets-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/assets-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/assets-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/assets-deadline-exceeded" } } } } } }, "summary": "Get asset", "security": [] } }, "/v1/assets/{asset_type}/{asset_symbol}/rates": { "get": { "tags": [ "Assets" ], "description": "List historical OHLCV candles for a single asset against a quote asset.\n\nReturn open, high, low, close, and base-asset volume for each available candle, in chronological order. Use `close` to plot a price time-series.\n\nPrices are expressed in the quote asset per unit of the requested asset. Some candles use derived rates: their high and low values are price bounds that may not correspond to executed trades. Their volume comes from the underlying market used to price the requested asset, expressed in units of that asset.\n\nFor example, when BTC/JPY prices are derived from BTC/USD and USD/JPY, volume represents BTC traded in the BTC/USD market during the interval. It does not represent BTC/JPY trading activity.\n\nIntervals without trades may carry forward prior prices with zero volume. The current, incomplete candle may be included and can change until the interval ends.\n\nPages cover consecutive portions of the requested time window. Continue with `next_page_token` until it is absent, even if `data` is empty. An empty page means no prices are available for that portion of the window. History is limited to the most recent 5,760 candles and may be shorter for some intervals.\n\nGeographic restrictions apply according to `country`.", "operationId": "listAssetRates", "parameters": [ { "in": "query", "name": "country", "schema": { "description": "ISO 3166-1 alpha-2 country code used to apply geo restrictions (e.g., \"US\", \"GB\"). Required.", "type": "string", "pattern": "^[A-Z]{2}$" }, "style": "form", "example": "DE", "required": true }, { "in": "path", "name": "asset_type", "required": true, "schema": { "description": "Classification of the asset (fiat, crypto, stablecoin, or xstock).", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "style": "simple", "example": "crypto" }, { "in": "path", "name": "asset_symbol", "required": true, "schema": { "description": "Ticker symbol of an asset (e.g., BTC, USDC, EUR).", "$ref": "#/components/schemas/AssetSymbol" }, "style": "simple", "example": "BTC" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Ticker symbol of the quote asset.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Classification of the quote asset.", "type": "string", "enum": [ "fiat" ], "default": "fiat" }, "style": "form", "example": "fiat" }, { "in": "query", "name": "start_timestamp", "schema": { "description": "Inclusive lower bound of the rate window. Defaults to end_timestamp - 7 days.", "$ref": "#/components/schemas/DateTime" }, "style": "form", "example": "2025-06-30T00:00:00.000Z" }, { "in": "query", "name": "end_timestamp", "schema": { "description": "Exclusive upper bound of the rate window. Defaults to \"now\".", "$ref": "#/components/schemas/DateTime" }, "style": "form", "example": "2025-06-30T00:00:00.000Z" }, { "in": "query", "name": "interval", "schema": { "$ref": "#/components/schemas/Assets_Interval" }, "style": "form", "example": "PT15M" }, { "$ref": "#/components/parameters/Assets_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Available candles for this page's portion of the requested time window, in chronological order.", "type": "array", "items": { "$ref": "#/components/schemas/Assets_HistoricalRate" } }, "quote_symbol": { "description": "Quote asset symbol the prices are denominated in.", "type": "string" }, "quote_type": { "description": "Classification of the quote asset.", "$ref": "#/components/schemas/Assets_QuoteAssetType" }, "start_timestamp": { "description": "Resolved start of the window after defaults were applied.", "$ref": "#/components/schemas/DateTime" }, "end_timestamp": { "description": "Resolved end of the window after defaults were applied.", "$ref": "#/components/schemas/DateTime" }, "interval": { "description": "Resolved interval after defaults were applied.", "$ref": "#/components/schemas/Assets_Interval" }, "page_size": { "description": "Maximum number of results returned on this page. Echoes the page_size query parameter.", "type": "integer", "format": "int32", "minimum": 1, "maximum": 100 }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data", "quote_symbol", "quote_type", "start_timestamp", "end_timestamp", "interval", "page_size" ] }, "examples": { "btc-15m-window": { "summary": "Two 15-minute candles for BTC priced in USD", "value": { "data": [ { "timestamp": "2026-01-01T00:00:00Z", "open": "94000.10", "high": "94520.00", "low": "93875.25", "close": "94250.12", "volume": "123.456789" }, { "timestamp": "2026-01-01T00:15:00Z", "open": "94250.12", "high": "94425.75", "low": "94190.00", "close": "94381.50", "volume": "98.765432" } ], "quote_symbol": "USD", "quote_type": "fiat", "start_timestamp": "2026-01-01T00:00:00Z", "end_timestamp": "2026-01-01T00:30:00Z", "interval": "PT15M", "page_size": 20 } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/assets-bad-request" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/assets-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/assets-forbidden" } } } } }, "404": { "description": "Asset not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/assets-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/assets-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/assets-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/assets-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/assets-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/assets-deadline-exceeded" } } } } } }, "summary": "List asset rates", "security": [] } }, "/v1/users/{user_id}/assets": { "get": { "tags": [ "Assets" ], "description": "List assets available to a specific user, with that user's geo restrictions applied.\n\nThe response includes each asset's symbol, type, display metadata, market data, and per-action availability. Use the optional filters to narrow the list by asset type or by whether an asset is enabled for swap trading, withdrawals, or deposits.", "operationId": "listUserAssets", "parameters": [ { "in": "query", "name": "type", "schema": { "description": "Filter assets by classification. Repeat the parameter to filter on multiple types.", "type": "array", "default": [], "items": { "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "minItems": 0, "maxItems": 4 }, "style": "form", "example": [ "crypto" ] }, { "in": "query", "name": "swap_trading", "schema": { "description": "Filter to assets that are currently enabled for swap trading. Omit to ignore this dimension.", "type": "boolean" }, "style": "form", "example": true }, { "in": "query", "name": "withdraw", "schema": { "description": "Filter to assets that are currently enabled for withdrawal. Omit to ignore this dimension.", "type": "boolean" }, "style": "form", "example": true }, { "in": "query", "name": "deposit", "schema": { "description": "Filter to assets that are currently enabled for deposit. Omit to ignore this dimension.", "type": "boolean" }, "style": "form", "example": true }, { "in": "query", "name": "sort", "schema": { "$ref": "#/components/schemas/Assets_SortField" }, "style": "form", "example": "market_cap_rank" }, { "in": "query", "name": "sort_direction", "schema": { "description": "Direction of the sort. Use asc for natural ascending order (rank 1 first, oldest first, lowest first); desc for the inverse.", "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "style": "form", "example": "desc" }, { "$ref": "#/components/parameters/Assets_PageSize" }, { "$ref": "#/components/parameters/PageToken" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Symbol of the asset to use as the quote currency for valuations.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Classification of the quote asset. Currently only fiat is supported.", "type": "string", "enum": [ "fiat" ], "default": "fiat" }, "style": "form", "example": "fiat" }, { "$ref": "#/components/parameters/UserId" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The list of matching assets.", "type": "array", "items": { "$ref": "#/components/schemas/Assets_Asset" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Quote asset symbol the prices are denominated in (resolved, defaults to USD).", "type": "string" }, "quote_type": { "description": "Classification of the quote asset (resolved, defaults to fiat).", "$ref": "#/components/schemas/Assets_QuoteAssetType" }, "page_size": { "description": "Maximum number of results returned on this page (resolved, defaults to 20).", "type": "integer", "format": "int32", "minimum": 1, "maximum": 100 }, "sort": { "description": "Field the results were sorted by (resolved, defaults to market_cap_rank).", "$ref": "#/components/schemas/Assets_SortField" }, "sort_direction": { "description": "Direction the results were sorted in (resolved, defaults to asc).", "type": "string", "enum": [ "asc", "desc" ] }, "type": { "description": "Asset classifications the listing was filtered to. Empty when no type filter was applied.", "type": "array", "items": { "$ref": "#/components/schemas/Assets_CatalogAssetType" } }, "swap_trading": { "description": "Swap-trading filter that was applied, echoed back. Absent when not filtered.", "type": "boolean" }, "withdraw": { "description": "Withdrawal filter that was applied, echoed back. Absent when not filtered.", "type": "boolean" }, "deposit": { "description": "Deposit filter that was applied, echoed back. Absent when not filtered.", "type": "boolean" } }, "required": [ "data", "quote_symbol", "quote_type", "page_size", "sort", "sort_direction" ] }, "examples": { "first-page": { "summary": "First page of assets across crypto, fiat, and xStocks", "value": { "data": [ { "symbol": "BTC", "type": "crypto", "name": "Bitcoin", "website": "https://bitcoin.org/", "docs": "https://bitcoin.org/bitcoin.pdf", "description": "Bitcoin is the world's largest cryptocurrency project.", "listing_date": "2013-10-06", "price": "62081.0000", "market_cap": "1244183483835", "market_cap_rank": 1, "trending_rank": 66, "volume": { "last_24h": "53096507160" }, "supply": { "circulating": "20038918", "total": "20038918", "max": "21000000", "in_quote": { "circulating": "1244036068358", "total": "1244036068358", "max": "1303701000000" } }, "price_range": { "high_24h": "63120.0000", "low_24h": "61540.0000", "high_1y": "73750.0000", "low_1y": "24900.0000" }, "price_change_percent": { "last_1h": "-0.31", "last_24h": "-0.58", "last_7d": "-15.62", "last_30d": "-24.56", "last_1y": "-40.69" }, "ath": { "value": "126080.0000", "timestamp": "2025-10-06T18:57:42Z" }, "buy_rate": "65.00", "market_dominance": "52.40", "status": { "swap_trading": { "enabled": true, "disabled_against": [ { "symbol": "USDT", "type": "stablecoin" }, { "symbol": "SOL", "type": "crypto" } ] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_btc.webp", "type": "image/webp" }, "decimals": { "funding": 8, "swap": 10 } }, { "symbol": "ETH", "type": "crypto", "name": "Ethereum", "listing_date": "2015-08-07", "price": "1659.8600", "market_cap": "200269280850", "market_cap_rank": 2, "trending_rank": 55, "volume": { "last_24h": "27036726996" }, "price_range": { "high_24h": "1688.4000", "low_24h": "1642.1000" }, "price_change_percent": { "last_1h": "-0.53", "last_24h": "-4.92", "last_7d": "-17.38", "last_30d": "-31.16", "last_1y": "-36.02" }, "ath": { "value": "4946.0500", "timestamp": "2025-08-24T19:21:03Z" }, "status": { "swap_trading": { "enabled": true, "disabled_against": [ { "symbol": "USDT", "type": "stablecoin" }, { "symbol": "SOL", "type": "crypto" } ] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_eth.webp", "type": "image/webp" }, "decimals": { "funding": 10, "swap": 10 } }, { "symbol": "USD", "type": "fiat", "name": "US Dollar", "listing_date": "2013-10-06", "status": { "swap_trading": { "enabled": true, "disabled_against": [ { "symbol": "AED", "type": "fiat" }, { "symbol": "USDT", "type": "stablecoin" } ] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_usd.webp", "type": "image/webp" }, "decimals": { "funding": 2, "swap": 4 } }, { "symbol": "TSLAx", "type": "xstock", "name": "Tesla, Inc.", "listing_date": "2025-06-30", "price": "248.5000", "market_cap": "799000000000", "market_cap_rank": 12, "trending_rank": 8, "volume": { "last_24h": "1203456789" }, "price_change_percent": { "last_1h": "0.15", "last_24h": "-1.02", "last_7d": "3.44", "last_30d": "-2.10", "last_1y": "18.73" }, "ath": { "value": "488.5400", "timestamp": "2025-01-31T20:00:00Z" }, "status": { "swap_trading": { "enabled": true, "disabled_against": [] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_tslax.webp", "type": "image/webp" }, "decimals": { "funding": 8, "swap": 8 } } ], "quote_symbol": "USD", "quote_type": "fiat", "page_size": 20, "sort": "market_cap_rank", "sort_direction": "asc", "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } }, "last-page": { "summary": "Last page of results; `next_page_token` is omitted", "value": { "data": [ { "symbol": "GBP", "type": "fiat", "name": "Pound Sterling", "listing_date": "2013-10-06", "status": { "swap_trading": { "enabled": true, "disabled_against": [] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_gbp.webp", "type": "image/webp" }, "decimals": { "funding": 2, "swap": 4 } } ], "quote_symbol": "USD", "quote_type": "fiat", "page_size": 20, "sort": "market_cap_rank", "sort_direction": "asc" } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/assets-bad-request" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/assets-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/assets-forbidden" } } } } }, "404": { "description": "Not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/assets-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/assets-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/assets-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/assets-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/assets-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/assets-deadline-exceeded" } } } } } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List user assets" } }, "/v1/users/{user_id}/assets/{asset_type}/{asset_symbol}": { "get": { "tags": [ "Assets" ], "description": "Get information about a specific asset for a specific user, with that user's geo restrictions applied.", "operationId": "getUserAsset", "parameters": [ { "in": "path", "name": "asset_type", "required": true, "schema": { "description": "Classification of the asset (fiat, crypto, stablecoin, or xstock).", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "style": "simple", "example": "crypto" }, { "in": "path", "name": "asset_symbol", "required": true, "schema": { "description": "Ticker symbol of an asset (e.g., BTC, USDC, EUR).", "$ref": "#/components/schemas/AssetSymbol" }, "style": "simple", "example": "BTC" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Ticker symbol of the quote asset for valuations.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Classification of the quote asset. Pair with quote_symbol to disambiguate when the same ticker exists across asset classes.", "type": "string", "enum": [ "fiat" ], "default": "fiat" }, "style": "form", "example": "fiat" }, { "$ref": "#/components/parameters/UserId" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The requested asset.", "$ref": "#/components/schemas/Assets_Asset" }, "quote_symbol": { "description": "Quote asset symbol the prices are denominated in.", "type": "string" }, "quote_type": { "description": "Classification of the quote asset.", "$ref": "#/components/schemas/Assets_QuoteAssetType" } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "btc": { "summary": "Full BTC asset payload for an unrestricted user", "value": { "data": { "symbol": "BTC", "type": "crypto", "name": "Bitcoin", "website": "https://bitcoin.org/", "docs": "https://bitcoin.org/bitcoin.pdf", "description": "Bitcoin is the world's largest cryptocurrency project.", "listing_date": "2013-10-06", "price": "62081.0000", "market_cap": "1244183483835", "market_cap_rank": 1, "trending_rank": 66, "volume": { "last_24h": "53096507160" }, "supply": { "circulating": "20038918", "total": "20038918", "max": "21000000", "in_quote": { "circulating": "1244036068358", "total": "1244036068358", "max": "1303701000000" } }, "price_range": { "high_24h": "63120.0000", "low_24h": "61540.0000", "high_1y": "73750.0000", "low_1y": "24900.0000" }, "price_change_percent": { "last_1h": "-0.31", "last_24h": "-0.58", "last_7d": "-15.62", "last_30d": "-24.56", "last_1y": "-40.69" }, "ath": { "value": "126080.0000", "timestamp": "2025-10-06T18:57:42Z" }, "buy_rate": "65.00", "market_dominance": "52.40", "status": { "swap_trading": { "enabled": true, "disabled_against": [ { "symbol": "USDT", "type": "stablecoin" }, { "symbol": "SOL", "type": "crypto" } ] }, "withdraw": { "enabled": true }, "deposit": { "enabled": true } }, "logo": { "width": 400, "height": 400, "href": "https://assets.kraken.com/marketing/web/icons-uni-webp/s_btc.webp", "type": "image/webp" }, "decimals": { "funding": 8, "swap": 10 } }, "quote_symbol": "USD", "quote_type": "fiat" } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/assets-bad-request" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/assets-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/assets-forbidden" } } } } }, "404": { "description": "Asset not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/assets-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/assets-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/assets-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/assets-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/assets-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/assets-deadline-exceeded" } } } } } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get user asset" } }, "/v1/users/{user_id}/assets/{asset_type}/{asset_symbol}/rates": { "get": { "tags": [ "Assets" ], "description": "List historical OHLCV candles for a single asset against a quote asset, for a specific user with that user's geo restrictions applied.\n\nReturn open, high, low, close, and base-asset volume for each available candle, in chronological order. Use `close` to plot a price time-series.\n\nPrices are expressed in the quote asset per unit of the requested asset. Some candles use derived rates: their high and low values are price bounds that may not correspond to executed trades. Their volume comes from the underlying market used to price the requested asset, expressed in units of that asset.\n\nFor example, when BTC/JPY prices are derived from BTC/USD and USD/JPY, volume represents BTC traded in the BTC/USD market during the interval. It does not represent BTC/JPY trading activity.\n\nIntervals without trades may carry forward prior prices with zero volume. The current, incomplete candle may be included and can change until the interval ends.\n\nPages cover consecutive portions of the requested time window. Continue with `next_page_token` until it is absent, even if `data` is empty. An empty page means no prices are available for that portion of the window. History is limited to the most recent 5,760 candles and may be shorter for some intervals.", "operationId": "listUserAssetRates", "parameters": [ { "in": "path", "name": "asset_type", "required": true, "schema": { "description": "Classification of the asset (fiat, crypto, stablecoin, or xstock).", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "style": "simple", "example": "crypto" }, { "in": "path", "name": "asset_symbol", "required": true, "schema": { "description": "Ticker symbol of an asset (e.g., BTC, USDC, EUR).", "$ref": "#/components/schemas/AssetSymbol" }, "style": "simple", "example": "BTC" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Ticker symbol of the quote asset.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Classification of the quote asset.", "type": "string", "enum": [ "fiat" ], "default": "fiat" }, "style": "form", "example": "fiat" }, { "in": "query", "name": "start_timestamp", "schema": { "description": "Inclusive lower bound of the rate window. Defaults to end_timestamp - 7 days.", "$ref": "#/components/schemas/DateTime" }, "style": "form", "example": "2025-06-30T00:00:00.000Z" }, { "in": "query", "name": "end_timestamp", "schema": { "description": "Exclusive upper bound of the rate window. Defaults to \"now\".", "$ref": "#/components/schemas/DateTime" }, "style": "form", "example": "2025-06-30T00:00:00.000Z" }, { "in": "query", "name": "interval", "schema": { "$ref": "#/components/schemas/Assets_Interval" }, "style": "form", "example": "PT15M" }, { "$ref": "#/components/parameters/Assets_PageSize" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/UserId" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Available candles for this page's portion of the requested time window, in chronological order.", "type": "array", "items": { "$ref": "#/components/schemas/Assets_HistoricalRate" } }, "quote_symbol": { "description": "Quote asset symbol the prices are denominated in.", "type": "string" }, "quote_type": { "description": "Classification of the quote asset.", "$ref": "#/components/schemas/Assets_QuoteAssetType" }, "start_timestamp": { "description": "Resolved start of the window after defaults were applied.", "$ref": "#/components/schemas/DateTime" }, "end_timestamp": { "description": "Resolved end of the window after defaults were applied.", "$ref": "#/components/schemas/DateTime" }, "interval": { "description": "Resolved interval after defaults were applied.", "$ref": "#/components/schemas/Assets_Interval" }, "page_size": { "description": "Maximum number of results returned on this page. Echoes the page_size query parameter.", "type": "integer", "format": "int32", "minimum": 1, "maximum": 100 }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data", "quote_symbol", "quote_type", "start_timestamp", "end_timestamp", "interval", "page_size" ] }, "examples": { "btc-15m-window": { "summary": "Two 15-minute candles for BTC priced in USD", "value": { "data": [ { "timestamp": "2026-01-01T00:00:00Z", "open": "94000.10", "high": "94520.00", "low": "93875.25", "close": "94250.12", "volume": "123.456789" }, { "timestamp": "2026-01-01T00:15:00Z", "open": "94250.12", "high": "94425.75", "low": "94190.00", "close": "94381.50", "volume": "98.765432" } ], "quote_symbol": "USD", "quote_type": "fiat", "start_timestamp": "2026-01-01T00:00:00Z", "end_timestamp": "2026-01-01T00:30:00Z", "interval": "PT15M", "page_size": 20 } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/assets-bad-request" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/assets-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/assets-forbidden" } } } } }, "404": { "description": "Asset not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/assets-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/assets-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/assets-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/assets-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/assets-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/assets-deadline-exceeded" } } } } } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List user asset rates" } }, "/v1/accounts/{account_id}/on-demand-conversions": { "get": { "tags": [ "Conversions" ], "summary": "List on-demand conversions", "description": "Lists on-demand conversions for the selected account, ordered by `created_at` descending. Results include prepared and canceled conversions as well as conversions that have started.\n\nTo start a prepared conversion, call [Execute prepared on-demand conversion](./execute-prepared-on-demand-conversion) before `expires_at`. A canceled conversion includes `cancellation_reason`; prepare a new conversion to try again. If `next_action` is present, direct the payer to its `widget_url` to authorize the payment before `next_action.expires_at`.", "operationId": "listOnDemandConversions", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "query", "name": "page_size", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "On-demand conversions returned for the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "On-demand conversions on this page, ordered by `created_at` descending.", "items": { "$ref": "#/components/schemas/Conversions_OnDemandConversion" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "examples": { "id-list-on-demand-conversions-ok": { "summary": "ListOnDemandConversions returns on-demand conversions", "value": { "data": [ { "id": "00000000-0000-0000-0000-000000000001", "status": "completed", "from": { "symbol": "USD", "amount": "100.00", "type": "balance", "status": "settled" }, "to": { "symbol": "BTC", "amount": "0.00150", "type": "wallet", "status": "settled", "wallet": { "via": "bitcoin", "address": "bc1qexamplewallet002", "memo": "destination-memo", "tag": "destination-tag" } }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "BTC" }, "price": "0.00001520" }, "fees": { "from": { "symbol": "EUR", "amount": "0.50" }, "trade": { "symbol": "EUR", "amount": "0.25" }, "to": { "symbol": "BTC", "amount": "0.00001" } }, "transaction_references": { "to": { "transaction_id": "withdrawal-1", "blockchain_transaction_id": "chain-1" } }, "created_at": "2026-08-12T12:55:00Z", "updated_at": "2026-08-12T13:02:03Z" } ] } }, "list-canceled-on-demand-conversion": { "summary": "A prepared conversion whose price lock expired", "value": { "data": [ { "id": "c1a7e2f4-31b9-4f0e-8d63-7a2b9c5d0e11", "status": "canceled", "from": { "symbol": "USD", "type": "bank", "amount": "1000.00", "status": "pending", "bank_account": { "via": "rfp", "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B" } }, "to": { "symbol": "ETH", "type": "wallet", "amount": "0.39770000", "status": "pending", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "ETH" }, "price": "0.0004" }, "fees": { "from": { "symbol": "USD", "amount": "0.00" }, "trade": { "symbol": "USD", "amount": "5.00" }, "to": { "symbol": "ETH", "amount": "0.00030000" } }, "created_at": "2026-10-05T12:00:00Z", "updated_at": "2026-10-05T12:02:00Z", "expires_at": "2026-10-05T12:02:00Z", "cancellation_reason": "expired" } ] } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "Validation error." }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden." }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded." }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error." }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable." }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded." } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ] }, "post": { "tags": [ "Conversions" ], "summary": "Execute on-demand conversion", "description": "Executes an on-demand conversion for the selected account. The service calculates the missing amount and processes the conversion in the background.\n\nTo review a locked price and fees before starting, use [Prepare on-demand conversion](./prepare-on-demand-conversion) followed by [Execute prepared on-demand conversion](./execute-prepared-on-demand-conversion) instead. For an RfP (request for payment) source, direct the payer to `next_action.widget_url` to authorize the payment before `next_action.expires_at`. Use [Get on-demand conversion](./get-on-demand-conversion) to follow its progress.\n\nAn `Idempotency-Key` identifies one execution request. If an earlier execution request already used the key, no new conversion starts. The response is a `409` error with code `idempotency_key_already_used` and the `conversion_id` of the conversion that the first request started. To get the result of the first request, call [Get on-demand conversion](./get-on-demand-conversion) with that `conversion_id`. Use a new key for each new request.", "operationId": "executeOnDemandConversion", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/RequiredIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "$ref": "#/components/schemas/Conversions_OnDemandConversionSource" }, "to": { "$ref": "#/components/schemas/Conversions_OnDemandConversionDestination" } }, "if": { "properties": { "from": { "properties": { "type": { "enum": [ "bank" ] } } } } }, "then": { "properties": { "from": { "required": [ "amount" ] }, "to": { "properties": { "type": { "enum": [ "wallet" ] } } } } }, "oneOf": [ { "title": "Source amount", "description": "Provide `from.amount` to specify how much to debit. Omit `to.amount`; the service calculates the amount delivered to the destination.", "type": "object", "required": [ "from" ], "properties": { "from": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "to": { "type": "object", "not": { "required": [ "amount" ] } } } }, { "title": "Destination amount", "description": "Provide `to.amount` to specify how much to deliver. Omit `from.amount`; the service calculates the amount debited from the source.", "type": "object", "required": [ "to" ], "properties": { "from": { "type": "object", "not": { "required": [ "amount" ] } }, "to": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } ] }, "examples": { "execute-on-demand-conversion": { "summary": "Execute a balance-to-wallet conversion", "value": { "from": { "symbol": "USD", "type": "balance", "amount": "1000.00" }, "to": { "symbol": "ETH", "type": "wallet", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12", "memo": "destination-memo", "tag": "destination-tag" } } } }, "execute-on-demand-ach-pay-in": { "summary": "Execute an ACH-funded conversion to a wallet", "value": { "from": { "symbol": "USD", "type": "bank", "amount": "100.00", "bank_account": { "via": "ach", "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B" } }, "to": { "symbol": "USDC", "type": "wallet", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } } } }, "execute-on-demand-rfp-pay-in": { "summary": "Execute an RfP-funded conversion to a wallet", "value": { "from": { "symbol": "USD", "type": "bank", "amount": "100.00", "bank_account": { "via": "rfp", "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B" } }, "to": { "symbol": "USDC", "type": "wallet", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } } } } } } } }, "responses": { "201": { "description": "On-demand conversion created.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversions_OnDemandConversion" } } }, "examples": { "execute-on-demand-conversion-ok": { "summary": "ExecuteOnDemandConversion returns the initial conversion state", "value": { "data": { "id": "00000000-0000-0000-0000-000000000009", "status": "converting", "from": { "symbol": "USD", "amount": "1000.00", "type": "balance", "status": "pending" }, "to": { "symbol": "ETH", "amount": "0.40000000", "type": "wallet", "status": "pending", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12", "memo": "destination-memo", "tag": "destination-tag" } }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "ETH" }, "price": "0.0004" }, "fees": { "from": { "symbol": "EUR", "amount": "0.50" }, "trade": { "symbol": "EUR", "amount": "0.25" }, "to": { "symbol": "BTC", "amount": "0.00001" } }, "created_at": "2026-07-31T00:00:00Z", "updated_at": "2026-07-31T00:00:00Z" } } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "The request contains an invalid amount, unsupported asset or destination, invalid wallet address or network, an amount below the applicable minimum, a target amount that cannot be fulfilled, an unsupported bank rail, a rail and currency mismatch, or missing bank destination fields." }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden." }, "409": { "$ref": "#/components/responses/ConversionsOnDemandConflictResponse", "description": "The conversion cannot be created with the supplied account state, destination wallet address, or idempotency key." }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded." }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error." }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "A required dependency is unavailable." }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded." } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ] } }, "/v1/accounts/{account_id}/on-demand-conversions/estimate": { "post": { "tags": [ "Conversions" ], "summary": "Estimate on-demand conversion", "description": "Returns the indicative amounts, rate, and fees for an on-demand conversion. An estimate does not lock a price, reserve funds, or create a conversion.\n\nSupports conversions from an account balance to a crypto address or bank account, and from a bank account to a crypto address. For a bank source, provide `from.amount`; the destination amount is calculated for you. For a balance source, provide either `from.amount` or `to.amount`.\n\nSpecify bank rails and crypto networks without account link identifiers, bank routing details, or crypto addresses. To lock the price, call [Prepare on-demand conversion](./prepare-on-demand-conversion).", "operationId": "estimateOnDemandConversion", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "On-demand conversion to estimate.", "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "description": "Source of the conversion.", "$ref": "#/components/schemas/Conversions_EstimateOnDemandConversionSide" }, "to": { "description": "Destination of the conversion.", "$ref": "#/components/schemas/Conversions_EstimateOnDemandConversionSide" } }, "if": { "properties": { "from": { "properties": { "type": { "enum": [ "bank" ] } } } } }, "then": { "properties": { "from": { "required": [ "amount" ] }, "to": { "properties": { "type": { "enum": [ "wallet" ] } } } } }, "else": { "properties": { "from": { "properties": { "type": { "enum": [ "balance" ] } } }, "to": { "properties": { "type": { "enum": [ "bank", "wallet" ] } } } } }, "oneOf": [ { "title": "Source amount", "description": "Provide `from.amount` to specify how much to debit. Omit `to.amount`; the service calculates the amount delivered to the destination.", "type": "object", "required": [ "from" ], "properties": { "from": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "to": { "type": "object", "not": { "required": [ "amount" ] } } } }, { "title": "Destination amount", "description": "Provide `to.amount` to specify how much to deliver. Omit `from.amount`; the service calculates the amount debited from the source.", "type": "object", "required": [ "to" ], "properties": { "from": { "type": "object", "not": { "required": [ "amount" ] } }, "to": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } ] }, "examples": { "estimate-on-demand-conversion": { "summary": "Estimate an RfP-funded conversion to a wallet", "value": { "from": { "symbol": "USD", "type": "bank", "bank_account": { "via": "rfp" }, "amount": "1000.00" }, "to": { "symbol": "ETH", "type": "wallet", "wallet": { "via": "ethereum" } } } } } } } }, "responses": { "200": { "description": "On-demand conversion estimate returned.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversions_OnDemandConversionEstimate" } } }, "examples": { "estimate-on-demand-conversion-ok": { "summary": "Estimate an RfP-funded conversion to a wallet", "value": { "data": { "from": { "symbol": "USD", "type": "bank", "amount": "1000.00" }, "to": { "symbol": "ETH", "type": "wallet", "amount": "0.39770000" }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "ETH" }, "price": "0.0004" }, "fees": { "from": { "symbol": "USD", "amount": "0.00" }, "trade": { "symbol": "USD", "amount": "5.00" }, "to": { "symbol": "ETH", "amount": "0.00030000" } } } } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "The request contains an invalid amount, unsupported asset or destination, an amount below the applicable minimum, a target amount that cannot be fulfilled, an unsupported bank rail, or a rail and currency mismatch." }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden." }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded." }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error." }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable." }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded." } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ] } }, "/v1/accounts/{account_id}/on-demand-conversions/prepare": { "post": { "tags": [ "Conversions" ], "summary": "Prepare on-demand conversion", "description": "Creates an on-demand conversion in status `prepared`. Its price and fees are locked up to `expires_at`. The conversion does not start and does not reserve funds. To start it, call [Execute prepared on-demand conversion](./execute-prepared-on-demand-conversion) before `expires_at`. To start a conversion at once, call [Execute on-demand conversion](./execute-on-demand-conversion).\n\nTo preview indicative amounts, rates, and fees without locking a price, use [Estimate on-demand conversion](./estimate-on-demand-conversion).\n\nIf the conversion is not executed before `expires_at`, or the locked price can no longer be honored, the conversion is canceled. Then `status` is `canceled` and `cancellation_reason` tells why. Prepare a new conversion to try again.\n\nAn `Idempotency-Key` identifies one prepare request. If this endpoint already received the key, it does not prepare a new conversion. The response is a `409` error with code `idempotency_key_already_used` and the `conversion_id` of the conversion that the first request prepared. To get the result of the first request, call [Get on-demand conversion](./get-on-demand-conversion) with that `conversion_id`.\n\nPrepare checks keys separately from [Execute on-demand conversion](./execute-on-demand-conversion) and [Execute prepared on-demand conversion](./execute-prepared-on-demand-conversion). A key that one of these endpoints received does not cause a conflict here. Use a new key for each new request.", "operationId": "prepareOnDemandConversion", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/RequiredIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "$ref": "#/components/schemas/Conversions_OnDemandConversionSource" }, "to": { "$ref": "#/components/schemas/Conversions_OnDemandConversionDestination" } }, "if": { "properties": { "from": { "properties": { "type": { "enum": [ "bank" ] } } } } }, "then": { "properties": { "from": { "required": [ "amount" ] }, "to": { "properties": { "type": { "enum": [ "wallet" ] } } } } }, "oneOf": [ { "title": "Source amount", "description": "Provide `from.amount` to specify how much to debit. Omit `to.amount`; the service calculates the amount delivered to the destination.", "type": "object", "required": [ "from" ], "properties": { "from": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "to": { "type": "object", "not": { "required": [ "amount" ] } } } }, { "title": "Destination amount", "description": "Provide `to.amount` to specify how much to deliver. Omit `from.amount`; the service calculates the amount debited from the source.", "type": "object", "required": [ "to" ], "properties": { "from": { "type": "object", "not": { "required": [ "amount" ] } }, "to": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } ] }, "examples": { "prepare-on-demand-conversion": { "summary": "Prepare an RfP-funded conversion to a wallet", "value": { "from": { "symbol": "USD", "type": "bank", "amount": "1000.00", "bank_account": { "via": "rfp", "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B" } }, "to": { "symbol": "ETH", "type": "wallet", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } } } } } } } }, "responses": { "201": { "description": "On-demand conversion prepared.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversions_OnDemandConversion" } } }, "examples": { "prepare-on-demand-conversion-ok": { "summary": "Prepared RfP-funded conversion to a wallet", "value": { "data": { "id": "c1a7e2f4-31b9-4f0e-8d63-7a2b9c5d0e11", "status": "prepared", "from": { "symbol": "USD", "type": "bank", "amount": "1000.00", "status": "pending", "bank_account": { "via": "rfp", "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B" } }, "to": { "symbol": "ETH", "type": "wallet", "amount": "0.39770000", "status": "pending", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "ETH" }, "price": "0.0004" }, "fees": { "from": { "symbol": "USD", "amount": "0.00" }, "trade": { "symbol": "USD", "amount": "5.00" }, "to": { "symbol": "ETH", "amount": "0.00030000" } }, "created_at": "2026-10-05T12:00:00Z", "updated_at": "2026-10-05T12:00:00Z", "expires_at": "2026-10-05T12:02:00Z" } } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "The request contains an invalid amount, unsupported asset or destination, invalid wallet address or network, an amount below the applicable minimum, a target amount that cannot be fulfilled, an unsupported bank rail, a rail and currency mismatch, or missing bank destination fields." }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden." }, "409": { "$ref": "#/components/responses/ConversionsOnDemandPrepareConflictResponse", "description": "The conversion cannot be prepared with the supplied account state, destination wallet address, or idempotency key." }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded." }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error." }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "A required dependency is unavailable." }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded." } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ] } }, "/v1/accounts/{account_id}/on-demand-conversions/{conversion_id}": { "get": { "tags": [ "Conversions" ], "summary": "Get on-demand conversion", "description": "Returns an on-demand conversion and its current status, including conversions that are prepared or canceled.\n\nTo start a prepared conversion, call [Execute prepared on-demand conversion](./execute-prepared-on-demand-conversion) before `expires_at`. A canceled conversion includes `cancellation_reason`; prepare a new conversion to try again. If `next_action` is present, direct the payer to its `widget_url` to authorize the payment before `next_action.expires_at`. Payment authorization has its own expiry, separate from the deadline for executing a prepared conversion.", "operationId": "getOnDemandConversion", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "conversion_id", "required": true, "schema": { "description": "On-demand conversion identifier.", "type": "string", "format": "uuid" }, "style": "simple", "example": "00000000-0000-0000-0000-000000000001" } ], "responses": { "200": { "description": "On-demand conversion returned.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversions_OnDemandConversion" } } }, "examples": { "id-get-on-demand-conversion-ok": { "summary": "GetOnDemandConversion returns an on-demand conversion", "value": { "data": { "id": "00000000-0000-0000-0000-000000000001", "status": "completed", "from": { "symbol": "USD", "amount": "100.00", "type": "balance", "status": "settled" }, "to": { "symbol": "BTC", "amount": "0.00150", "type": "wallet", "status": "settled", "wallet": { "via": "bitcoin", "address": "bc1qexamplewallet002", "memo": "destination-memo", "tag": "destination-tag" } }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "BTC" }, "price": "0.00001520" }, "fees": { "from": { "symbol": "EUR", "amount": "0.50" }, "trade": { "symbol": "EUR", "amount": "0.25" }, "to": { "symbol": "BTC", "amount": "0.00001" } }, "transaction_references": { "to": { "transaction_id": "withdrawal-1", "blockchain_transaction_id": "chain-1" } }, "created_at": "2026-08-12T12:55:00Z", "updated_at": "2026-08-12T13:02:03Z" } } }, "get-prepared-on-demand-conversion": { "summary": "A conversion waiting to be executed", "value": { "data": { "id": "c1a7e2f4-31b9-4f0e-8d63-7a2b9c5d0e11", "status": "prepared", "from": { "symbol": "USD", "type": "bank", "amount": "1000.00", "status": "pending", "bank_account": { "via": "rfp", "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B" } }, "to": { "symbol": "ETH", "type": "wallet", "amount": "0.39770000", "status": "pending", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "ETH" }, "price": "0.0004" }, "fees": { "from": { "symbol": "USD", "amount": "0.00" }, "trade": { "symbol": "USD", "amount": "5.00" }, "to": { "symbol": "ETH", "amount": "0.00030000" } }, "created_at": "2026-10-05T12:00:00Z", "updated_at": "2026-10-05T12:00:00Z", "expires_at": "2026-10-05T12:02:00Z" } } }, "get-canceled-on-demand-conversion": { "summary": "A conversion canceled after its price lock expired", "value": { "data": { "id": "c1a7e2f4-31b9-4f0e-8d63-7a2b9c5d0e11", "status": "canceled", "from": { "symbol": "USD", "type": "bank", "amount": "1000.00", "status": "pending", "bank_account": { "via": "rfp", "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B" } }, "to": { "symbol": "ETH", "type": "wallet", "amount": "0.39770000", "status": "pending", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "ETH" }, "price": "0.0004" }, "fees": { "from": { "symbol": "USD", "amount": "0.00" }, "trade": { "symbol": "USD", "amount": "5.00" }, "to": { "symbol": "ETH", "amount": "0.00030000" } }, "created_at": "2026-10-05T12:00:00Z", "updated_at": "2026-10-05T12:02:00Z", "expires_at": "2026-10-05T12:02:00Z", "cancellation_reason": "expired" } } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "Validation error." }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden." }, "404": { "$ref": "#/components/responses/ConversionsNotFoundResponse", "description": "The requested on-demand conversion was not found." }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded." }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error." }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable." }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded." } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ] }, "post": { "tags": [ "Conversions" ], "summary": "Execute prepared on-demand conversion", "description": "Starts an on-demand conversion in status `prepared` at its locked price and fees. Call it before `expires_at`. After it starts, the conversion has the same lifecycle as a conversion from [Execute on-demand conversion](./execute-on-demand-conversion).\n\nFor an RfP (request for payment) source, direct the payer to `next_action.widget_url` to authorize the payment before `next_action.expires_at`. Payment authorization has its own expiry, separate from the deadline for executing the prepared conversion. Use [Get on-demand conversion](./get-on-demand-conversion) to follow its progress.\n\nAn `Idempotency-Key` identifies one execution request. If this endpoint or [Execute on-demand conversion](./execute-on-demand-conversion) already received the key, the conversion does not start again. The response is a `409` error with code `idempotency_key_already_used` and the `conversion_id` of the conversion that the first request started. To get the result of the first request, call [Get on-demand conversion](./get-on-demand-conversion) with that `conversion_id`.\n\nThis endpoint and [Execute on-demand conversion](./execute-on-demand-conversion) check keys together. [Prepare on-demand conversion](./prepare-on-demand-conversion) checks keys separately. Use a new key for each new request, different from the key used to prepare this conversion.", "operationId": "executePreparedOnDemandConversion", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "conversion_id", "required": true, "schema": { "description": "On-demand conversion identifier.", "type": "string", "format": "uuid" }, "style": "simple", "example": "c1a7e2f4-31b9-4f0e-8d63-7a2b9c5d0e11" }, { "$ref": "#/components/parameters/RequiredIdempotencyKey" } ], "responses": { "200": { "description": "On-demand conversion started.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversions_OnDemandConversion" } } }, "examples": { "execute-prepared-on-demand-conversion-ok": { "summary": "Started RfP-funded conversion that waits for payer authorization", "value": { "data": { "id": "c1a7e2f4-31b9-4f0e-8d63-7a2b9c5d0e11", "status": "converting", "from": { "symbol": "USD", "type": "bank", "amount": "1000.00", "status": "pending", "bank_account": { "via": "rfp", "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B" } }, "to": { "symbol": "ETH", "type": "wallet", "amount": "0.39770000", "status": "pending", "wallet": { "via": "ethereum", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } }, "rate": { "base": { "symbol": "USD" }, "quote": { "symbol": "ETH" }, "price": "0.0004" }, "fees": { "from": { "symbol": "USD", "amount": "0.00" }, "trade": { "symbol": "USD", "amount": "5.00" }, "to": { "symbol": "ETH", "amount": "0.00030000" } }, "created_at": "2026-10-05T12:00:00Z", "updated_at": "2026-10-05T12:00:30Z", "next_action": { "type": "hosted_payment", "widget_url": "https://pay.kraken.com/rfp/7f3e9a2c-5b1d-4e8f-a6c4-2d9b0e1f3a5c", "expires_at": "2026-10-05T12:10:00Z" } } } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "Validation error." }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden." }, "404": { "$ref": "#/components/responses/ConversionsNotFoundResponse", "description": "The requested on-demand conversion was not found." }, "409": { "$ref": "#/components/responses/ConversionsOnDemandExecuteConflictResponse", "description": "The conversion cannot be executed with its current status, the account state, the destination wallet address, or the supplied idempotency key." }, "410": { "$ref": "#/components/responses/ConversionsOnDemandCanceledResponse", "description": "The prepared conversion was canceled or its price lock expired." }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded." }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error." }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "A required dependency is unavailable." }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded." } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ] } }, "/v1/accounts/{account_id}/conversions": { "get": { "tags": [ "Conversions" ], "description": "Lists conversion rules for the caller, ordered by `created_at` descending.", "operationId": "listConversionRules", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "query", "name": "status", "schema": { "description": "Restrict results to conversion rules in this lifecycle state (`active` or `paused`). Soft-deleted conversion rules are never returned. They surface as `404 NotFound` on `GetConversionRule` instead.", "type": "string", "enum": [ "active", "paused", "provisioning" ], "title": "ConversionRuleStatus" }, "style": "form", "example": "active" }, { "in": "query", "name": "page_size", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Conversion rules on this page, ordered by `created_at` descending.", "type": "array", "items": { "description": "Full representation of a conversion rule.\n\nA conversion rule is the long-lived intent to convert one asset into another. `from` and `to` share the same `ConversionEndpoint` shape; for `wallet`/`bank` sources the inbound `address` or `bank_account` on `from` is populated by the service when autoramp provisions the inbound endpoint.", "type": "object", "properties": { "id": { "description": "Unique identifier for this conversion rule.", "type": "string", "format": "uuid" }, "name": { "description": "Optional partner-facing label for the conversion rule.", "type": "string" }, "from": { "description": "Source side. On reads, `address`/`bank_account` are populated by the service from the autoramp-provisioned inbound (where partner deposits funds). On writes, those fields are ignored. Partners only specify symbol, type, and via on the source side.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "payee_name": { "description": "Payee / account-holder name on the provisioned inbound (named account). Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 140 }, "bank_address": { "description": "Bank or EMI (electronic money institution) address on the provisioned inbound. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 256 }, "payee_address": { "description": "Payee's registered postal address on the provisioned inbound (on-ramp source only), distinct from `bank_address`, which is the bank or EMI address. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 256 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "type" ], "title": "ConversionEndpoint" }, "to": { "description": "Destination side. `address`/`bank_account` are partner-supplied.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "type" ], "title": "ConversionEndpoint" }, "status": { "description": "Lifecycle status (active | paused).", "type": "string", "enum": [ "active", "paused", "provisioning" ] }, "created_at": { "description": "Time at which the conversion rule was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the conversion rule was last updated.", "$ref": "#/components/schemas/DateTime" } }, "required": [ "id", "from", "to", "status", "created_at", "updated_at" ], "title": "ConversionRule" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "id-list-conversion-rules-ok": { "summary": "Conversion rules with deposit instructions", "value": { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "EUR autoramp to Polygon vault", "from": { "symbol": "EUR", "type": "bank", "bank_account": { "via": "sepa", "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "payee_name": "Delta Commerce B.V.", "bank_address": "Borschestraat 12, Amsterdam", "payee_address": "71 Sir John Rogerson's Quay, Dublin, D02 R296, Ireland" } }, "to": { "symbol": "USDC", "type": "wallet", "wallet": { "via": "polygon", "address": "0x1234567890abcdef1234567890abcdef12345678" } }, "status": "active", "created_at": "2026-05-25T10:30:00Z", "updated_at": "2026-05-25T10:30:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "Validation error" }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/ConversionsNotFoundResponse", "description": "Not found" }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded" }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error" }, "501": { "$ref": "#/components/responses/ConversionsUnimplementedResponse", "description": "Error response" }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable" }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "summary": "List conversion rules" }, "post": { "tags": [ "Conversions" ], "description": "Creates a new conversion rule. Provisions the inbound deposit endpoint (IBAN for fiat-source, crypto address for crypto-source) the caller will fund. Once funded, transactions are produced against this conversion rule and become observable via the transactions surface.", "operationId": "createConversionRule", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to create a new conversion rule.", "type": "object", "properties": { "name": { "description": "Optional partner-facing label for the conversion rule.", "type": "string", "minLength": 1, "maxLength": 128 }, "from": { "description": "Source side. Partners only specify `symbol`, `type`, and `via` here; any `address`/`bank_account` supplied is ignored (the inbound is provisioned by autoramp).", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "symbol", "type" ], "title": "ConversionEndpoint" }, "to": { "description": "Destination side. Requires `address` (wallet) or `bank_account` (bank).", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "symbol", "type" ], "title": "ConversionEndpoint" } }, "required": [ "from", "to" ] }, "examples": { "id-create-conversion-rule-ok": { "summary": "Convert EUR deposits to USDC on Polygon", "value": { "name": "EUR autoramp to Polygon vault", "from": { "symbol": "EUR", "type": "bank", "bank_account": { "via": "sepa" } }, "to": { "symbol": "USDC", "type": "wallet", "wallet": { "via": "polygon", "address": "0x1234567890abcdef1234567890abcdef12345678" } } } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The newly created conversion rule.", "type": "object", "properties": { "id": { "description": "Unique identifier for this conversion rule.", "type": "string", "format": "uuid" }, "name": { "description": "Optional partner-facing label for the conversion rule.", "type": "string" }, "from": { "description": "Source side. On reads, `address`/`bank_account` are populated by the service from the autoramp-provisioned inbound (where partner deposits funds). On writes, those fields are ignored. Partners only specify symbol, type, and via on the source side.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "payee_name": { "description": "Payee / account-holder name on the provisioned inbound (named account). Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 140 }, "bank_address": { "description": "Bank or EMI (electronic money institution) address on the provisioned inbound. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 256 }, "payee_address": { "description": "Payee's registered postal address on the provisioned inbound (on-ramp source only), distinct from `bank_address`, which is the bank or EMI address. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 256 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "type" ], "title": "ConversionEndpoint" }, "to": { "description": "Destination side. `address`/`bank_account` are partner-supplied.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "type" ], "title": "ConversionEndpoint" }, "status": { "description": "Lifecycle status (active | paused).", "type": "string", "enum": [ "active", "paused", "provisioning" ] }, "created_at": { "description": "Time at which the conversion rule was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the conversion rule was last updated.", "$ref": "#/components/schemas/DateTime" } }, "required": [ "id", "from", "to", "status", "created_at", "updated_at" ], "title": "ConversionRule" } }, "required": [ "data" ] }, "examples": { "id-create-conversion-rule-ok": { "summary": "Created conversion rule with deposit instructions", "value": { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "EUR autoramp to Polygon vault", "from": { "symbol": "EUR", "type": "bank", "bank_account": { "via": "sepa", "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "payee_name": "Delta Commerce B.V.", "bank_address": "Borschestraat 12, Amsterdam", "payee_address": "71 Sir John Rogerson's Quay, Dublin, D02 R296, Ireland" } }, "to": { "symbol": "USDC", "type": "wallet", "wallet": { "via": "polygon", "address": "0x1234567890abcdef1234567890abcdef12345678" } }, "status": "active", "created_at": "2026-05-25T10:30:00Z", "updated_at": "2026-05-25T10:30:00Z" } } } } } } }, "400": { "$ref": "#/components/responses/ConversionsInvalidWithdrawalAddressResponse", "description": "Validation error" }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/ConversionsNotFoundResponse", "description": "Not found" }, "409": { "$ref": "#/components/responses/ConversionsConversionLimitReachedResponse", "description": "Conflict" }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded" }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error" }, "501": { "$ref": "#/components/responses/ConversionsUnimplementedResponse", "description": "Error response" }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable" }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "summary": "Create conversion rule" } }, "/v1/accounts/{account_id}/conversions/{conversion_rule_id}": { "get": { "tags": [ "Conversions" ], "description": "Retrieves the current state of a previously created conversion rule.", "operationId": "getConversionRule", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "conversion_rule_id", "required": true, "schema": { "description": "Conversion rule identifier.", "type": "string", "format": "uuid" }, "style": "simple", "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The requested conversion rule.", "type": "object", "properties": { "id": { "description": "Unique identifier for this conversion rule.", "type": "string", "format": "uuid" }, "name": { "description": "Optional partner-facing label for the conversion rule.", "type": "string" }, "from": { "description": "Source side. On reads, `address`/`bank_account` are populated by the service from the autoramp-provisioned inbound (where partner deposits funds). On writes, those fields are ignored. Partners only specify symbol, type, and via on the source side.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "payee_name": { "description": "Payee / account-holder name on the provisioned inbound (named account). Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 140 }, "bank_address": { "description": "Bank or EMI (electronic money institution) address on the provisioned inbound. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 256 }, "payee_address": { "description": "Payee's registered postal address on the provisioned inbound (on-ramp source only), distinct from `bank_address`, which is the bank or EMI address. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 256 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "type" ], "title": "ConversionEndpoint" }, "to": { "description": "Destination side. `address`/`bank_account` are partner-supplied.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "type" ], "title": "ConversionEndpoint" }, "status": { "description": "Lifecycle status (active | paused).", "type": "string", "enum": [ "active", "paused", "provisioning" ] }, "created_at": { "description": "Time at which the conversion rule was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the conversion rule was last updated.", "$ref": "#/components/schemas/DateTime" } }, "required": [ "id", "from", "to", "status", "created_at", "updated_at" ], "title": "ConversionRule" } }, "required": [ "data" ] }, "examples": { "id-get-conversion-rule-ok": { "summary": "Conversion rule with deposit instructions", "value": { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "EUR autoramp to Polygon vault", "from": { "symbol": "EUR", "type": "bank", "bank_account": { "via": "sepa", "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "payee_name": "Delta Commerce B.V.", "bank_address": "Borschestraat 12, Amsterdam", "payee_address": "71 Sir John Rogerson's Quay, Dublin, D02 R296, Ireland" } }, "to": { "symbol": "USDC", "type": "wallet", "wallet": { "via": "polygon", "address": "0x1234567890abcdef1234567890abcdef12345678" } }, "status": "active", "created_at": "2026-05-25T10:30:00Z", "updated_at": "2026-05-25T10:30:00Z" } } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "Validation error" }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/ConversionsNotFoundResponse", "description": "Not found" }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded" }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error" }, "501": { "$ref": "#/components/responses/ConversionsUnimplementedResponse", "description": "Error response" }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable" }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "summary": "Get conversion rule" }, "put": { "tags": [ "Conversions" ], "description": "Updates an existing conversion rule. Replaces the destination, name, and status in a single full-state PUT (matching the autoramp rule update contract). The source side is immutable. Re-create the conversion rule if you need to change input asset, rail, or wallet.", "operationId": "updateConversionRule", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "conversion_rule_id", "required": true, "schema": { "description": "Conversion rule identifier.", "type": "string", "format": "uuid" }, "style": "simple", "example": "550e8400-e29b-41d4-a716-446655440000" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to update an existing conversion rule.\n\nFull-state replacement (matching the upstream contract): the supplied `to`, `name`, and `status` replace the conversion rule's current values. The source side (`from`) is immutable. Re-create the conversion rule to change input asset, rail, or source type.", "type": "object", "properties": { "name": { "description": "New partner-facing label for the conversion rule. This is a full replacement: omit to clear the existing label, send the current label to keep it.", "type": "string", "minLength": 1, "maxLength": 128 }, "to": { "description": "New destination side. Required (no partial updates supported).", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "symbol", "type" ], "title": "ConversionEndpoint" }, "status": { "description": "New lifecycle status. Must be `active` or `paused`; soft-delete via the delete endpoint when it lands.", "type": "string", "enum": [ "active", "paused" ] } }, "required": [ "to", "status" ] }, "examples": { "id-update-conversion-rule-ok": { "summary": "UpdateConversionRule returns the updated rule", "value": { "name": "Renamed EUR autoramp", "to": { "symbol": "USDC", "type": "wallet", "wallet": { "via": "polygon", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } }, "status": "paused" } }, "id-update-conversion-rule-rejects-symbol-change": { "summary": "UpdateConversionRule rejects an attempt to change to.symbol", "value": { "to": { "symbol": "USDT", "type": "wallet", "wallet": { "via": "polygon", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } }, "status": "active" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The updated conversion rule.", "type": "object", "properties": { "id": { "description": "Unique identifier for this conversion rule.", "type": "string", "format": "uuid" }, "name": { "description": "Optional partner-facing label for the conversion rule.", "type": "string" }, "from": { "description": "Source side. On reads, `address`/`bank_account` are populated by the service from the autoramp-provisioned inbound (where partner deposits funds). On writes, those fields are ignored. Partners only specify symbol, type, and via on the source side.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "payee_name": { "description": "Payee / account-holder name on the provisioned inbound (named account). Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 140 }, "bank_address": { "description": "Bank or EMI (electronic money institution) address on the provisioned inbound. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 256 }, "payee_address": { "description": "Payee's registered postal address on the provisioned inbound (on-ramp source only), distinct from `bank_address`, which is the bank or EMI address. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); the create response carries it only when the account was already provisioned at creation time. Rejected on a destination.", "type": "string", "minLength": 1, "maxLength": 256 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "type" ], "title": "ConversionEndpoint" }, "to": { "description": "Destination side. `address`/`bank_account` are partner-supplied.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EUR\", \"USDC\", \"BTC\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither.", "type": "string", "enum": [ "wallet", "bank" ], "title": "EndpointType" }, "wallet": { "description": "Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Memo for chains that require one (e.g., XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Destination tag for chains that require one (e.g., XRP). Passed through to the destination on off-ramp; populated on source responses.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "via" ], "title": "Wallet" }, "bank_account": { "description": "Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests.", "type": "object", "properties": { "via": { "description": "Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected.", "type": "string", "minLength": 1, "maxLength": 32 }, "bank": { "description": "Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp.", "type": "string", "maxLength": 256 }, "iban": { "description": "International Bank Account Number (SEPA, SWIFT).", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Bank Identifier Code (SEPA, SWIFT).", "type": "string", "minLength": 8, "maxLength": 11 }, "sort_code": { "description": "UK sort code (FPS).", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number. Required for FPS destinations; may also be populated on source bank accounts.", "type": "string", "minLength": 1, "maxLength": 34 }, "routing_number": { "description": "Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 1, "maxLength": 32 }, "swift": { "description": "SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations.", "type": "string", "minLength": 8, "maxLength": 11 }, "account_link_id": { "description": "Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "via" ], "title": "BankAccount" } }, "required": [ "type" ], "title": "ConversionEndpoint" }, "status": { "description": "Lifecycle status (active | paused).", "type": "string", "enum": [ "active", "paused", "provisioning" ] }, "created_at": { "description": "Time at which the conversion rule was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the conversion rule was last updated.", "$ref": "#/components/schemas/DateTime" } }, "required": [ "id", "from", "to", "status", "created_at", "updated_at" ], "title": "ConversionRule" } }, "required": [ "data" ] }, "examples": { "id-update-conversion-rule-ok": { "summary": "UpdateConversionRule returns the updated rule", "value": { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Renamed EUR autoramp", "from": { "symbol": "EUR", "type": "bank", "bank_account": { "via": "sepa", "payee_name": "Delta Commerce B.V.", "bank_address": "Borschestraat 12, Amsterdam", "payee_address": "71 Sir John Rogerson's Quay, Dublin, D02 R296, Ireland" } }, "to": { "symbol": "USDC", "type": "wallet", "wallet": { "via": "polygon", "address": "0xabcdef1234567890abcdef1234567890abcdef12" } }, "status": "paused", "created_at": "2026-05-25T10:30:00Z", "updated_at": "2026-05-25T11:00:00Z" } } } } } } }, "400": { "$ref": "#/components/responses/ConversionsInvalidWithdrawalAddressResponse", "description": "Validation error" }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/ConversionsNotFoundResponse", "description": "Not found" }, "409": { "$ref": "#/components/responses/ConversionsRuleAlreadyDeletedResponse", "description": "Conflict" }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded" }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error" }, "501": { "$ref": "#/components/responses/ConversionsUnimplementedResponse", "description": "Error response" }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable" }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "summary": "Update conversion rule" }, "delete": { "tags": [ "Conversions" ], "description": "Deletes a conversion rule (soft-delete). Inbound funds already received continue to settle; future deposits are rejected. Re-deleting an already-deleted conversion rule returns `404 NotFound`. Partners cannot distinguish \"deleted\" from \"never existed\".", "operationId": "deleteConversionRule", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "conversion_rule_id", "required": true, "schema": { "description": "Conversion rule identifier.", "type": "string", "format": "uuid" }, "style": "simple", "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "204": { "description": "No Content", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "Validation error" }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/ConversionsNotFoundResponse", "description": "Not found" }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded" }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error" }, "501": { "$ref": "#/components/responses/ConversionsUnimplementedResponse", "description": "Error response" }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable" }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "summary": "Delete conversion rule" } }, "/v1/accounts/{account_id}/conversions/{conversion_rule_id}/transactions": { "get": { "tags": [ "Conversions" ], "description": "Lists transactions produced by a single conversion rule, ordered by `created_at` descending.\n\nEach conversion rule accumulates zero-or-more transactions over its lifetime as deposits arrive and trades execute. Use `ListConversionRules` to enumerate the rules themselves.", "operationId": "listConversionRuleTransactions", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "conversion_rule_id", "required": true, "schema": { "description": "Identifier of the conversion rule whose transactions to list.", "type": "string", "format": "uuid" }, "style": "simple", "example": "12345678-1234-1234-1234-123456789012" }, { "in": "query", "name": "page_size", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Per-transaction summaries on this page, ordered by `created_at` descending.", "type": "array", "items": { "description": "Per-transaction summary returned by `ListConversionRuleTransactions`.", "type": "object", "properties": { "id": { "description": "Unique identifier for this transaction.", "type": "string" }, "status": { "description": "Lifecycle state of the transaction.", "type": "string", "enum": [ "pending_deposit", "converting", "settling", "completed", "failed", "held" ] }, "conversion_rule_id": { "description": "Identifier of the conversion rule that produced this transaction.", "type": "string" }, "from": { "description": "Source side: asset symbol/amount and funding rail. Absent on in-progress transactions before the inbound deposit has been observed.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol of the source side (e.g., \"EUR\").", "type": "string" }, "amount": { "description": "Decimal amount once the deposit has been observed.", "type": "string" }, "type": { "description": "Endpoint type (wallet, bank, balance).", "type": "string", "enum": [ "wallet", "bank" ] }, "via": { "description": "Rail or network identifier (e.g., \"ethereum\", \"sepa\").", "type": "string" }, "status": { "description": "Status of the inbound deposit.", "type": "string", "enum": [ "pending", "held", "settled", "failed" ], "title": "ConversionSettlementStatus" } }, "required": [ "amount", "type", "status" ], "title": "ConversionSummaryFrom" }, "to": { "description": "Destination side: asset symbol/amount and settlement rail. Absent on in-progress transactions before the outbound trade has produced withdrawal data.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol of the destination side (e.g., \"BTC\").", "type": "string" }, "amount": { "description": "Decimal amount once the trade has filled.", "type": "string" }, "status": { "description": "Status of the outbound withdrawal.", "type": "string", "enum": [ "pending", "held", "settled", "failed" ] }, "via": { "description": "Rail or network identifier (e.g., \"bitcoin\", \"sepa\").", "type": "string" } }, "required": [ "amount", "status" ], "title": "ConversionSummaryTo" }, "chain_references": { "description": "On-chain transaction references for inbound and outbound legs.", "type": "object", "properties": { "deposit_txid": { "description": "Inbound (deposit) transaction ID.", "type": "string" }, "withdraw_txid": { "description": "Outbound (withdrawal) transaction ID.", "type": "string" } }, "title": "ChainReferences" }, "created_at": { "description": "Time at which the conversion-rule transaction was created.", "$ref": "#/components/schemas/DateTime" } }, "required": [ "status", "conversion_rule_id", "chain_references", "created_at" ], "title": "ConversionSummary" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "id-list-conversion-rule-transactions-ok": { "summary": "Conversion rule transactions", "value": { "data": [ { "id": "conv_smoke_001", "status": "completed", "conversion_rule_id": "12345678-1234-1234-1234-123456789012", "from": { "symbol": "EUR", "amount": "100.00", "type": "bank", "via": "sepa", "status": "settled" }, "to": { "symbol": "BTC", "amount": "0.002", "status": "settled", "via": "bitcoin" }, "chain_references": { "deposit_txid": "deposit-eur-001", "withdraw_txid": "withdraw-btc-001" }, "created_at": "2026-04-01T12:00:00Z" }, { "id": "conv_smoke_002", "status": "pending_deposit", "conversion_rule_id": "12345678-1234-1234-1234-123456789012", "chain_references": {}, "created_at": "2026-04-02T09:30:00Z" }, { "id": "conv_smoke_003", "status": "held", "conversion_rule_id": "12345678-1234-1234-1234-123456789012", "from": { "symbol": "EUR", "amount": "250.00", "type": "bank", "via": "sepa", "status": "held" }, "chain_references": { "deposit_txid": "deposit-held-001" }, "created_at": "2026-04-03T14:15:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/ConversionsBadRequestResponse", "description": "Validation error" }, "401": { "$ref": "#/components/responses/ConversionsUnauthenticatedResponse", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/ConversionsForbiddenResponse", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/ConversionsNotFoundResponse", "description": "Not found" }, "429": { "$ref": "#/components/responses/ConversionsResourceExhaustedResponse", "description": "Rate limit exceeded" }, "500": { "$ref": "#/components/responses/ConversionsInternalResponse", "description": "Internal server error" }, "501": { "$ref": "#/components/responses/ConversionsUnimplementedResponse", "description": "Error response" }, "503": { "$ref": "#/components/responses/ConversionsUnavailableResponse", "description": "Service unavailable" }, "504": { "$ref": "#/components/responses/ConversionsDeadlineExceededResponse", "description": "Deadline exceeded" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "summary": "List conversion rule transactions" } }, "/v1/accounts/{account_id}/earn/auto": { "get": { "tags": [ "Auto Earn" ], "description": "Returns the current Auto Earn preferences for the specified account.\n\nA yield source key is present if the account is eligible for that yield source, currently enrolled in it, or has an enable in flight. A missing key means none of these apply. Each yield source is `enabled` or `disabled`, or is `pending_enabled` or `pending_disabled` while a change is being applied.", "operationId": "getAutoEarnPreferences", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "title": "AutoEarnPreferencesData", "description": "Auto Earn preferences for the account.", "type": "object", "properties": { "staking": { "title": "AutoEarnStatus", "description": "Current staking Auto Earn status. Absent unless the account is eligible for staking, currently enrolled in it, or has an enable in flight.", "type": "string", "enum": [ "enabled", "disabled", "pending_enabled", "pending_disabled" ] }, "base_rewards": { "title": "AutoEarnStatus", "description": "Current base-rewards Auto Earn status. Absent unless the account is eligible for base rewards, currently enrolled in them, or has an enable in flight.", "type": "string", "enum": [ "enabled", "disabled", "pending_enabled", "pending_disabled" ] }, "opt_in_rewards": { "title": "AutoEarnStatus", "description": "Current opt-in-rewards Auto Earn status. Absent unless the account is eligible for opt-in rewards, currently enrolled in them, or has an enable in flight.", "type": "string", "enum": [ "enabled", "disabled", "pending_enabled", "pending_disabled" ] } } } }, "required": [ "data" ] }, "examples": { "staking-enabled": { "summary": "Staking is active for this account", "value": { "data": { "staking": "enabled" } } }, "staking-pending": { "summary": "Staking activation is in progress", "value": { "data": { "staking": "pending_enabled" } } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "description": "Account not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEarn_AccountNotFoundError" }, "examples": { "account-not-found": { "summary": "Account not found", "value": { "error": { "type": "earn_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "account_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get Auto Earn preferences" }, "patch": { "tags": [ "Auto Earn" ], "description": "Sets Auto Earn preferences for the specified account.\n\nAll body fields are optional. Only fields that are present are updated; omitted yield sources are left unchanged.\n\nThe change is applied asynchronously, so a `200` response means the request was accepted. Poll Get Auto Earn preferences until the yield source leaves `pending_enabled` or `pending_disabled`. Enabling a yield source the account is not eligible for fails with `not_eligible`; disabling is always allowed. Only one change can be in progress per account: a second request while one is pending fails with `allocation_in_progress`.", "operationId": "setAutoEarnPreferences", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to set Auto Earn preferences for an account.", "type": "object", "properties": { "staking": { "title": "AutoEarnPreference", "description": "Staking Auto Earn preference. Omit to leave unchanged.", "type": "string", "enum": [ "enabled", "disabled" ] }, "base_rewards": { "title": "AutoEarnPreference", "description": "Base-rewards Auto Earn preference. Omit to leave unchanged.", "type": "string", "enum": [ "enabled", "disabled" ] }, "opt_in_rewards": { "title": "AutoEarnPreference", "description": "Opt-in-rewards Auto Earn preference. Omit to leave unchanged.", "type": "string", "enum": [ "enabled", "disabled" ] } } }, "examples": { "enable-staking": { "summary": "Enable staking Auto Earn", "value": { "staking": "enabled" } }, "disable-staking": { "summary": "Disable staking Auto Earn", "value": { "staking": "disabled" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutoEarn_SetAutoEarnPreferencesData" } }, "required": [ "data" ] }, "examples": { "accepted": { "summary": "Preference update accepted (empty response body)", "value": { "data": {} } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnSetPreferencesForbiddenResponse" }, "404": { "description": "Account not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEarn_AccountNotFoundError" }, "examples": { "account-not-found": { "summary": "Account not found", "value": { "error": { "type": "earn_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "account_not_found" } } } } } } }, "409": { "description": "Allocation in progress", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEarn_AllocationInProgressError" }, "examples": { "allocation-in-progress": { "summary": "Allocation in progress", "value": { "error": { "type": "earn_error", "status": 409, "instance": "req_01H00000000000000000000000", "code": "allocation_in_progress" } } } } } } }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Set Auto Earn preferences" } }, "/v1/accounts/{account_id}/earn/auto/allocations": { "get": { "tags": [ "Auto Earn" ], "description": "Returns current allocation info for the specified account, plus the total across all assets.\n\nResults are paginated and sorted by asset symbol, A-Z.", "operationId": "getAutoEarnAllocations", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Ticker symbol of the quote asset for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string", "maxLength": 10, "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Type of the quote asset. Only \"fiat\" is supported.", "type": "string", "maxLength": 16, "default": "fiat" }, "style": "form", "example": "fiat" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/AutoEarn_PageSize" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "total_allocated_in_quote": { "description": "Total of all allocations expressed in the quote currency.", "type": "string" }, "data": { "description": "Per-asset allocation entries for the requested page, sorted by symbol, A-Z.", "type": "array", "items": { "title": "AllocationEntry", "description": "Current allocation for one asset.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "allocated": { "description": "Decimal amount currently allocated in the native asset.", "type": "string" }, "allocated_in_quote": { "description": "Decimal amount currently allocated converted to the quote currency.", "type": "string" } }, "required": [ "symbol", "type", "name", "allocated", "allocated_in_quote" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "data", "total_allocated_in_quote", "quote_symbol", "quote_type" ] }, "examples": { "allocations-with-next-page": { "summary": "First page of allocations in USD", "value": { "quote_symbol": "USD", "quote_type": "fiat", "total_allocated_in_quote": "12345.12", "data": [ { "symbol": "ETH", "type": "crypto", "name": "Ethereum", "allocated": "3.5000", "allocated_in_quote": "8750.00" }, { "symbol": "DOT", "type": "crypto", "name": "Polkadot", "allocated": "450.00", "allocated_in_quote": "3595.12" } ], "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } }, "allocations-last-page": { "summary": "Last page; `next_page_token` is omitted", "value": { "quote_symbol": "USD", "quote_type": "fiat", "total_allocated_in_quote": "12345.12", "data": [ { "symbol": "ADA", "type": "crypto", "name": "Cardano", "allocated": "1200.00", "allocated_in_quote": "552.00" } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "description": "Account not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEarn_AccountNotFoundError" }, "examples": { "account-not-found": { "summary": "Account not found", "value": { "error": { "type": "earn_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "account_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get Auto Earn allocations" } }, "/v1/accounts/{account_id}/earn/auto/assets": { "get": { "tags": [ "Auto Earn" ], "description": "Returns Auto Earn asset info for assets available to the specified account.\n\nResults are paginated, with one entry per asset. Entries are sorted by APY from highest to lowest, and assets with the same APY are sorted by asset symbol, A-Z.", "operationId": "getAccountAutoEarnAssets", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/AutoEarn_PageSize" }, { "in": "query", "name": "yield_source", "schema": { "description": "Returns only assets backed by the selected yield sources.", "type": "array", "items": { "title": "YieldSource", "description": "Yield source that backs this asset (e.g., \"staking\").", "type": "string", "enum": [ "staking", "base_rewards", "opt_in_rewards" ] } }, "style": "form", "example": [ "base_rewards", "staking" ] } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Auto Earn asset entries available to the account for the requested page, sorted by APY (highest first), then by symbol, A-Z.", "type": "array", "items": { "title": "AutoEarnAsset", "description": "Auto Earn asset info entry.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "yield_source": { "title": "YieldSource", "description": "Yield source that backs this asset (e.g., \"staking\").", "type": "string", "enum": [ "staking", "base_rewards", "opt_in_rewards" ] }, "apy": { "description": "Annual percentage yield as a decimal string (e.g., \"3.41\"). Gross, before any reward fee.", "type": "string" }, "user_cap": { "description": "Maximum amount the user can have allocated, in the asset's native units. Absent when there is no cap.", "type": "string" } }, "required": [ "symbol", "type", "name", "yield_source", "apy" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "account-assets": { "summary": "Assets available for Auto Earn for this account", "value": { "data": [ { "symbol": "ETH", "type": "crypto", "name": "Ethereum", "yield_source": "staking", "apy": "3.41", "user_cap": "1000" }, { "symbol": "DOT", "type": "crypto", "name": "Polkadot", "yield_source": "staking", "apy": "12.50" } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "description": "Account not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEarn_AccountNotFoundError" }, "examples": { "account-not-found": { "summary": "Account not found", "value": { "error": { "type": "earn_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "account_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get account Auto Earn assets" } }, "/v1/accounts/{account_id}/earn/auto/rewards/summary": { "get": { "tags": [ "Auto Earn" ], "description": "Returns the total historical rewards across every Auto Earn asset of the specified account, converted to the quote currency. Use `GET /v1/accounts/{account_id}/earn/auto/rewards` for the per-asset breakdown.", "operationId": "getAutoEarnRewardSummary", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AutoEarn_QuoteSymbol" }, { "$ref": "#/components/parameters/AutoEarn_QuoteType" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "title": "AutoEarnRewardSummary", "description": "Total historical rewards across every Auto Earn asset.", "type": "object", "properties": { "total_rewarded_in_quote": { "description": "Sum of every asset's `rewarded_in_quote`. Each payout is valued when it is paid, so the total does not move with asset prices. For a non-USD quote, the USD total is converted at today's USD rate, so it still moves with that rate. Net of any reward fee.", "type": "string" }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "total_rewarded_in_quote", "quote_symbol", "quote_type" ] } }, "required": [ "data" ] }, "examples": { "reward-summary": { "summary": "Total Auto Earn rewards in USD", "value": { "data": { "total_rewarded_in_quote": "325.62", "quote_symbol": "USD", "quote_type": "fiat" } } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "description": "Account not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEarn_AccountNotFoundError" }, "examples": { "account-not-found": { "summary": "Account not found", "value": { "error": { "type": "earn_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "account_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get Auto Earn reward summary" } }, "/v1/accounts/{account_id}/earn/auto/rewards": { "get": { "tags": [ "Auto Earn" ], "description": "Returns the historical rewards of each Auto Earn asset of the specified account. Each amount is a lifetime total, net of any reward fee, in the asset and in the quote currency. Assets that have never paid a reward are omitted. Results are paginated and sorted by asset symbol, A-Z.\n\nUse `GET /v1/accounts/{account_id}/earn/auto/rewards/summary` for the total across assets and `GET /v1/accounts/{account_id}/earn/auto/rewards/upcoming` for the next payout.", "operationId": "listAutoEarnRewards", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AutoEarn_QuoteSymbol" }, { "$ref": "#/components/parameters/AutoEarn_QuoteType" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/AutoEarn_PageSize" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Historical rewards per asset for the requested page, sorted by symbol, A-Z.", "type": "array", "items": { "title": "AutoEarnRewardEntry", "description": "Lifetime rewards for one Auto Earn asset.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "rewarded": { "description": "Total rewarded to date, in the asset. Net of any reward fee. Includes rewards paid in other assets, converted to this asset at the time of the payout.", "type": "string" }, "rewarded_in_quote": { "description": "Same lifetime total in the quote currency. Each payout is valued when it is paid, so the total does not move with the asset price. For a non-USD quote, the USD total is converted at today's USD rate, so it still moves with that rate. Includes rewards paid in other assets.", "type": "string" } }, "required": [ "symbol", "type", "name", "rewarded", "rewarded_in_quote" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "rewards-by-asset": { "summary": "Historical rewards of one Auto Earn asset", "value": { "quote_symbol": "USD", "quote_type": "fiat", "data": [ { "symbol": "ETH", "type": "crypto", "name": "Ethereum", "rewarded": "0.0125", "rewarded_in_quote": "31.25" } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "description": "Account not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEarn_AccountNotFoundError" }, "examples": { "account-not-found": { "summary": "Account not found", "value": { "error": { "type": "earn_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "account_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List Auto Earn rewards" } }, "/v1/accounts/{account_id}/earn/auto/rewards/upcoming": { "get": { "tags": [ "Auto Earn" ], "description": "Returns the reward each Auto Earn asset of the specified account expects to pay out at the next payout, with the date of that payout.\n\nThe amount is what has accrued so far plus an estimate up to the payout date, net of the payout fee. It leaves out rewards that belong to a later payout period. It is an estimate, and the date is a target, so payouts can be delayed. `next_reward_date` is one date for the whole account: the earliest payout among the assets. Each amount is for its asset's own next payout, which can be later than that date.\n\nThe reward is split by reward asset: `other_assets` lists the part paid in assets other than the entry's own. Assets with nothing pending are omitted, and `next_reward_date` is then absent. Results are paginated and sorted by asset symbol, A-Z.", "operationId": "listAutoEarnUpcomingRewards", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/AutoEarn_QuoteSymbol" }, { "$ref": "#/components/parameters/AutoEarn_QuoteType" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/AutoEarn_PageSize" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Upcoming reward per asset for the requested page, sorted by symbol, A-Z.", "type": "array", "items": { "title": "AutoEarnUpcomingReward", "description": "Reward one Auto Earn asset expects to pay out at the next payout.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "upcoming_reward": { "description": "Accrued plus projected reward in the asset, net of the payout fee. Leaves out rewards that belong to a later payout period. Zero when the asset only has rewards in `other_assets`.", "type": "string" }, "upcoming_reward_in_quote": { "description": "Same net reward converted to the quote currency.", "type": "string" }, "other_assets": { "description": "Part of the reward paid in assets other than the entry's own (e.g., EIGEN paid on the ETH entry). Usually empty.", "type": "array", "items": { "title": "AutoEarnUpcomingOtherAssetReward", "description": "Part of an upcoming reward paid in another asset.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EIGEN\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Eigenlayer\").", "type": "string" }, "upcoming_reward": { "description": "Accrued plus projected reward in this asset, net of the payout fee. Leaves out rewards that belong to a later payout period.", "type": "string" }, "upcoming_reward_in_quote": { "description": "Same net reward converted to the quote currency.", "type": "string" } }, "required": [ "symbol", "type", "name", "upcoming_reward", "upcoming_reward_in_quote" ] } } }, "required": [ "symbol", "type", "name", "upcoming_reward", "upcoming_reward_in_quote", "other_assets" ] } }, "next_reward_date": { "description": "Earliest payout date among the assets with a pending reward. Covers every asset, not just this page, so it reads the same on every page. An asset can pay later than this date, and its amount is for that later payout. Absent if no reward is pending.", "$ref": "#/components/schemas/DateTime" }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "upcoming-rewards": { "summary": "Upcoming reward of a restaked ETH asset", "value": { "quote_symbol": "USD", "quote_type": "fiat", "next_reward_date": "2026-06-01T00:00:00Z", "data": [ { "symbol": "ETH", "type": "crypto", "name": "Ethereum", "upcoming_reward": "0.0056", "upcoming_reward_in_quote": "14.00", "other_assets": [ { "symbol": "EIGEN", "type": "crypto", "name": "Eigenlayer", "upcoming_reward": "0.1", "upcoming_reward_in_quote": "0.25" } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "description": "Account not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEarn_AccountNotFoundError" }, "examples": { "account-not-found": { "summary": "Account not found", "value": { "error": { "type": "earn_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "account_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List upcoming Auto Earn rewards" } }, "/v1/earn/auto/assets": { "get": { "tags": [ "Auto Earn" ], "description": "Returns Auto Earn asset info for a given country.\n\nUser-agnostic endpoint. Results are paginated, with one entry per asset. Entries are sorted by APY from highest to lowest, and assets with the same APY are sorted by asset symbol, A-Z.", "operationId": "getAutoEarnAssets", "parameters": [ { "in": "query", "name": "country", "schema": { "description": "ISO 3166-1 alpha-2 country code to filter eligible assets (e.g., \"US\", \"GB\"). Required.", "type": "string", "pattern": "^[A-Z]{2}$" }, "style": "form", "example": "DE", "required": true }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/AutoEarn_PageSize" }, { "in": "query", "name": "yield_source", "schema": { "description": "Returns only assets backed by the selected yield sources.", "type": "array", "items": { "title": "YieldSource", "description": "Yield source that backs this asset (e.g., \"staking\").", "type": "string", "enum": [ "staking", "base_rewards", "opt_in_rewards" ] } }, "style": "form", "example": [ "base_rewards", "staking" ] } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Auto Earn asset entries for the requested country and page, sorted by APY (highest first), then by symbol, A-Z.", "type": "array", "items": { "title": "AutoEarnAsset", "description": "Auto Earn asset info entry.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "yield_source": { "title": "YieldSource", "description": "Yield source that backs this asset (e.g., \"staking\").", "type": "string", "enum": [ "staking", "base_rewards", "opt_in_rewards" ] }, "apy": { "description": "Annual percentage yield as a decimal string (e.g., \"3.41\"). Gross, before any reward fee.", "type": "string" }, "user_cap": { "description": "Maximum amount the user can have allocated, in the asset's native units. Absent when there is no cap.", "type": "string" } }, "required": [ "symbol", "type", "name", "yield_source", "apy" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "country-assets": { "summary": "Assets eligible for Auto Earn in Germany", "value": { "data": [ { "symbol": "ETH", "type": "crypto", "name": "Ethereum", "yield_source": "staking", "apy": "3.41", "user_cap": "1000" }, { "symbol": "DOT", "type": "crypto", "name": "Polkadot", "yield_source": "staking", "apy": "12.50" } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get Auto Earn assets" } }, "/v1/accounts/{account_id}/earn/bonded/strategies/{strategy_id}/allocate": { "post": { "tags": [ "Bonded Earn" ], "summary": "Allocate to a Bonded Earn strategy", "description": "Submits a request to allocate funds from the specified account into the bonded earn strategy identified in the path.\n\nThe request is processed asynchronously. A successful response only confirms that the request was accepted and returns its `request_id`; poll the request status endpoint with that identifier to learn whether the allocation succeeded or failed.\n\nReuse the same `Idempotency-Key` only when retrying the same request. Keys are scoped to the account. Retrying with the same key, strategy, and `amount` returns the original `request_id` without allocating again. Reusing the key with a different strategy or `amount`, or for a deallocation instead of an allocation, returns a conflict error.\n\nRejected requests return a machine-readable `error.code`; branch on it rather than on the message text. Known codes are `strategy_not_found`, `amount_too_high`, `idempotency_key_reused`, and `allocation_in_progress`. An amount below the strategy's minimum allocation (`user_min_allocation` in the strategy list) returns a generic `bad_request`. An account that is not eligible for the strategy returns `forbidden`. A 403 with the code `gateway` is an authorization failure from the API gateway instead, so branch on `error.code` to tell the two apart.\n\nThe account balance and the strategy cap are checked after the request is accepted. If the request fails then, the request status endpoint reports it in `error.reason`, as `insufficient_balance`, `above_user_cap`, or `not_eligible`. A request that failed after it was accepted keeps its `Idempotency-Key`, so retry with a new key. New codes may be added, so treat an unknown code as a generic `bad_request`, `not_found`, or `request_conflict` error.", "operationId": "allocateBondedEarn", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/BondedEarn_BondedStrategyId" }, { "$ref": "#/components/parameters/RequiredIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Request to allocate funds into a bonded earn strategy.", "type": "object", "additionalProperties": false, "required": [ "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/BondedEarn_BondedAmount" } } }, "examples": { "allocate": { "summary": "Allocate 2 units of the strategy's asset", "value": { "amount": "2.0" } } } } } }, "responses": { "202": { "description": "The allocation request was accepted and is pending.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BondedEarn_BondedRequestAccepted" } }, "required": [ "data" ] }, "examples": { "accepted": { "summary": "Allocation request accepted", "value": { "data": { "request_id": "EBARERNY-PXH3CV-XQJL2O" } } } } } } }, "400": { "$ref": "#/components/responses/BondedEarnAllocateBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/BondedEarnWriteForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnWriteNotFoundResponse" }, "409": { "$ref": "#/components/responses/BondedEarnConflictResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ] } }, "/v1/accounts/{account_id}/earn/bonded/strategies/{strategy_id}/deallocate": { "post": { "tags": [ "Bonded Earn" ], "summary": "Deallocate from a Bonded Earn strategy", "description": "Submits a request to deallocate funds of the specified account from the bonded earn strategy identified in the path.\n\nPartial deallocation is allowed. To exit a strategy completely, send the full `earning` amount. The funds then pass through the exit queue (if any) and the unbonding period. For an instant strategy they return right away.\n\nThe request is processed asynchronously. A successful response only confirms that the request was accepted and returns its `request_id`; poll the request status endpoint with that identifier to learn whether the deallocation succeeded or failed.\n\nReuse the same `Idempotency-Key` only when retrying the same request. Keys are scoped to the account. Retrying with the same key, strategy, and `amount` returns the original `request_id` without deallocating again. Reusing the key with a different strategy or `amount`, or for an allocation instead of a deallocation, returns a conflict error.\n\nRejected requests return a machine-readable `error.code`; branch on it rather than on the message text. Known codes are `strategy_not_found`, `insufficient_balance`, `amount_too_high`, `idempotency_key_reused`, and `allocation_in_progress`. Only funds that are earning can be deallocated. `insufficient_balance` means the amount is more than those funds. Funds that are still bonding, unbonding, or in the exit queue do not count. An account that is not eligible for the strategy returns `forbidden`. A 403 with the code `gateway` is an authorization failure from the API gateway instead, so branch on `error.code` to tell the two apart.\n\nA request that is accepted can still fail later. The request status endpoint then reports it in `error.reason`, for example `insufficient_balance` or `not_eligible`. A request that failed after it was accepted keeps its `Idempotency-Key`, so retry with a new key. New codes may be added, so treat an unknown code as a generic `bad_request`, `not_found`, or `request_conflict` error.", "operationId": "deallocateBondedEarn", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/BondedEarn_BondedStrategyId" }, { "$ref": "#/components/parameters/RequiredIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Request to deallocate funds from a bonded earn strategy.", "type": "object", "additionalProperties": false, "required": [ "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/BondedEarn_BondedAmount" } } }, "examples": { "deallocate": { "summary": "Deallocate 2 units of the strategy's asset", "value": { "amount": "2.0" } } } } } }, "responses": { "202": { "description": "The deallocation request was accepted and is pending.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BondedEarn_BondedRequestAccepted" } }, "required": [ "data" ] }, "examples": { "accepted": { "summary": "Deallocation request accepted", "value": { "data": { "request_id": "EBARXUKF-PWQSJN-JNZQDS" } } } } } } }, "400": { "$ref": "#/components/responses/BondedEarnDeallocateBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/BondedEarnWriteForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnWriteNotFoundResponse" }, "409": { "$ref": "#/components/responses/BondedEarnConflictResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ] } }, "/v1/accounts/{account_id}/earn/bonded/allocations": { "get": { "tags": [ "Bonded Earn" ], "summary": "List Bonded Earn allocations", "description": "Returns current allocation totals for the specified account, grouped by strategy.\n\nEach entry splits the total by state (bonding, earning, exit queue, unbonding) and shows the soonest scheduled change. Amounts are in the strategy's asset and in the quote currency. Sorted by asset symbol (A-Z), then unbonding period (shortest first, variable last). Results are paginated.", "operationId": "listBondedEarnAllocations", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Ticker symbol of the quote asset for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string", "maxLength": 10, "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Type of the quote asset. Only \"fiat\" is supported.", "type": "string", "maxLength": 16, "default": "fiat" }, "style": "form", "example": "fiat" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/BondedEarn_PageSize" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Allocation totals for the requested page.", "type": "array", "items": { "$ref": "#/components/schemas/BondedEarn_BondedAllocation" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "allocations": { "summary": "One strategy allocation", "value": { "quote_symbol": "USD", "quote_type": "fiat", "data": [ { "strategy_id": "ESQEFMZ-JPPIY-3KXFJ2", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "strategy_type": "bonded", "total": "2.0", "total_in_quote": "4000.0", "bonding": "2.0", "bonding_in_quote": "4000.0", "earning": "0", "earning_in_quote": "0", "exit_queue": "0", "exit_queue_in_quote": "0", "unbonding": "0", "unbonding_in_quote": "0", "next_transition": { "amount": "2.0", "amount_in_quote": "4000.0", "state": "bonding", "next_state": "earning", "transitions_at": "2026-06-01T12:00:00Z" } } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotEnabledResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ] } }, "/v1/accounts/{account_id}/earn/bonded/allocation-states": { "get": { "tags": [ "Bonded Earn" ], "summary": "List Bonded Earn allocation states", "description": "Returns the current allocation transitions for the specified account, ordered by when each allocation leaves its current state (soonest first).\n\nA transition is a move to the next state: bonding to earning, exit queue to unbonding, or unbonding to available. Each entry also estimates when the funds become available, which is absent while bonding. For an exit queue entry, the estimate includes the unbonding period. Use it to follow funds after a deallocation.\n\nUse `state` more than once to return several states. Results are paginated.", "operationId": "listBondedEarnAllocationStates", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Ticker symbol of the quote asset for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string", "maxLength": 10, "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "description": "Type of the quote asset. Only \"fiat\" is supported.", "type": "string", "maxLength": 16, "default": "fiat" }, "style": "form", "example": "fiat" }, { "in": "query", "name": "strategy_id", "description": "Restrict results to one bonded earn strategy.", "required": false, "schema": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyId" }, "style": "form", "example": "ESQEFMZ-JPPIY-3KXFJ2" }, { "in": "query", "name": "state", "description": "Restrict results to one or more current allocation states. Omit to return all states.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BondedEarn_BondedAllocationTransitionState" } }, "style": "form", "explode": true, "example": [ "bonding", "unbonding" ] }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/BondedEarn_PageSize" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Allocation transitions for the requested page.", "type": "array", "items": { "$ref": "#/components/schemas/BondedEarn_BondedAllocationTransition" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "allocation-transition": { "summary": "A bonding allocation", "value": { "quote_symbol": "USD", "quote_type": "fiat", "data": [ { "strategy_id": "ESQEFMZ-JPPIY-3KXFJ2", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "amount": "2.0", "amount_in_quote": "4000.0", "state": "bonding", "next_state": "earning", "transitions_at": "2026-06-01T12:00:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotEnabledResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ] } }, "/v1/accounts/{account_id}/earn/bonded/requests": { "get": { "tags": [ "Bonded Earn" ], "summary": "List pending Bonded Earn requests", "description": "Returns the allocate and deallocate requests of the specified account that are still pending, oldest first by creation time.\n\nA request drops off this list once it reaches a final status. Use the request status endpoint with its identifier to see the outcome after that.\n\nResults are paginated.", "operationId": "listBondedEarnPendingRequests", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/BondedEarn_PageSize" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Pending requests for the requested page.", "type": "array", "items": { "$ref": "#/components/schemas/BondedEarn_BondedRequestStatus" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "pending-requests": { "summary": "One pending allocation", "value": { "data": [ { "id": "EBARERNY-PXH3CV-XQJL2O", "idempotency_key": "11111111-1111-4111-8111-111111111111", "request_type": "allocate", "strategy_id": "ESQEFMZ-JPPIY-3KXFJ2", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "strategy_type": "bonded", "amount": "2.0", "status": "pending", "created_at": "2026-06-01T12:00:00Z" } ] } }, "no-pending-requests": { "summary": "No pending requests", "value": { "data": [] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotEnabledResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ] } }, "/v1/accounts/{account_id}/earn/bonded/requests/{request_id}": { "get": { "tags": [ "Bonded Earn" ], "summary": "Get Bonded Earn request status", "description": "Returns the status of one allocate or deallocate request of the specified account.\n\nA request that failed is still returned successfully: its outcome is carried in the `status` and `error` fields of the response, not as an error response. A failed request keeps its `Idempotency-Key`, so retry with a new key.\n\nA completed request is kept for at least 24 hours. After that its identifier is not found, and its `Idempotency-Key` can be used again.", "operationId": "getBondedEarnRequestStatus", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/BondedEarn_BondedRequestId" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BondedEarn_BondedRequestStatus" } }, "required": [ "data" ] }, "examples": { "succeeded": { "summary": "Allocation succeeded", "value": { "data": { "id": "EBARERNY-PXH3CV-XQJL2O", "idempotency_key": "11111111-1111-4111-8111-111111111111", "request_type": "allocate", "strategy_id": "ESQEFMZ-JPPIY-3KXFJ2", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "strategy_type": "bonded", "amount": "2.0", "status": "succeeded", "created_at": "2026-06-01T12:00:00Z", "completed_at": "2026-06-01T12:00:05Z" } } }, "failed": { "summary": "Allocation failed", "value": { "data": { "id": "EBARERNY-PXH3CV-XQJL2O", "idempotency_key": "11111111-1111-4111-8111-111111111111", "request_type": "allocate", "strategy_id": "ESQEFMZ-JPPIY-3KXFJ2", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "strategy_type": "bonded", "amount": "2.0", "status": "failed", "created_at": "2026-06-01T12:00:00Z", "completed_at": "2026-06-01T12:00:05Z", "error": { "reason": "insufficient_balance", "message": "The account balance is insufficient for this allocation." } } } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotFoundResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ] } }, "/v1/accounts/{account_id}/earn/bonded/strategies": { "get": { "tags": [ "Bonded Earn" ], "description": "Returns the bonded and instant strategies the specified account can allocate into or still holds.\n\nEach entry says whether the account can allocate or deallocate now. A strategy the account is no longer eligible for stays listed while it holds funds, so the user can still deallocate.\n\nSorted by asset symbol (A-Z), then unbonding period (shortest first, variable last). Results are paginated.", "operationId": "listAccountBondedEarnStrategies", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/BondedEarn_PageSize" }, { "$ref": "#/components/parameters/BondedEarn_StrategyAssetTypeFilter" }, { "$ref": "#/components/parameters/BondedEarn_StrategyYieldSourceFilter" }, { "$ref": "#/components/parameters/BondedEarn_StrategySymbolFilter" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Strategies for the specified account and page.", "type": "array", "items": { "title": "BondedAccountStrategy", "description": "Bonded or instant strategy, with the account's eligibility.", "type": "object", "properties": { "id": { "description": "Strategy identifier, used to allocate and deallocate.", "type": "string" }, "strategy_type": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyType" }, "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "yield_source": { "title": "YieldSource", "description": "Yield source that backs this strategy (e.g., \"staking\").", "type": "string", "enum": [ "staking", "base_rewards", "opt_in_rewards" ] }, "apy": { "description": "Annual percentage yield as a decimal string (e.g., \"3.41\"), combined across reward assets. Gross, before any reward fee.", "type": "string" }, "other_assets": { "description": "Reward assets other than the strategy's own, each with its share of `apy`. Usually empty.", "type": "array", "items": { "title": "BondedOtherAssetApy", "description": "A reward asset other than the strategy's own, with its share of the APY.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EIGEN\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Eigenlayer\").", "type": "string" }, "apy": { "description": "This asset's share of the strategy's `apy`, as a decimal string.", "type": "string" } }, "required": [ "symbol", "type", "name", "apy" ] } }, "bonding_period": { "description": "Wait after an allocate before the funds start earning.", "$ref": "#/components/schemas/BondedEarn_BondedStrategyPeriod" }, "unbonding_period": { "description": "Wait after the exit queue before a deallocate reaches the account.", "$ref": "#/components/schemas/BondedEarn_BondedStrategyPeriod" }, "exit_queue_period": { "description": "Wait after a deallocate before unbonding starts. Always fixed and accruing.", "$ref": "#/components/schemas/BondedEarn_BondedStrategyPeriod" }, "reward_frequency_seconds": { "description": "Seconds between reward payouts.", "type": "integer", "format": "int32", "minimum": 0 }, "auto_compound": { "title": "AutoCompound", "description": "Whether rewards are added back to the allocation.", "type": "string", "enum": [ "disabled", "enabled" ] }, "user_min_allocation": { "description": "Smallest amount one allocate may move, in the strategy's asset, as a decimal string.", "type": "string" }, "user_cap": { "description": "Most the account may allocate, in the strategy's asset, as a decimal string. Absent when unlimited.", "type": "string" }, "can_allocate": { "description": "Whether the account can allocate into this strategy now.", "type": "boolean" }, "can_deallocate": { "description": "Whether the account can deallocate from this strategy now.", "type": "boolean" }, "fee_schedule": { "description": "Fee taken from this strategy's rewards for this account, by allocated volume. Absent when it cannot be shown as one schedule.", "$ref": "#/components/schemas/BondedEarn_BondedFeeSchedule" } }, "required": [ "id", "strategy_type", "symbol", "type", "name", "yield_source", "apy", "other_assets", "bonding_period", "unbonding_period", "exit_queue_period", "reward_frequency_seconds", "auto_compound", "user_min_allocation", "can_allocate", "can_deallocate" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "account-strategies": { "summary": "Bonded and instant strategies for an account", "value": { "data": [ { "id": "ESDQCOL-WTZEU-NU55QF", "strategy_type": "bonded", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "yield_source": "staking", "apy": "3.10", "other_assets": [], "bonding_period": { "type": "fixed", "seconds": 0, "rewards": "not_accruing" }, "unbonding_period": { "type": "variable", "seconds": 1209600, "rewards": "not_accruing" }, "exit_queue_period": { "type": "fixed", "seconds": 0, "rewards": "accruing" }, "reward_frequency_seconds": 604800, "auto_compound": "enabled", "user_min_allocation": "0.01", "user_cap": "100", "can_allocate": true, "can_deallocate": true, "fee_schedule": { "volume_basis": "shared_usd", "tiers": [ { "min_volume": "0", "fee_percentage": "25" }, { "min_volume": "1000000", "fee_percentage": "20" } ] } } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotEnabledResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List account Bonded Earn strategies" } }, "/v1/accounts/{account_id}/earn/bonded/rewards/summary": { "get": { "tags": [ "Bonded Earn" ], "description": "Returns the total historical rewards across every bonded and instant strategy of the specified account.", "operationId": "getBondedEarnRewardSummary", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/BondedEarn_QuoteSymbol" }, { "$ref": "#/components/parameters/BondedEarn_QuoteType" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "title": "BondedRewardSummary", "description": "Total historical rewards across every bonded and instant strategy.", "type": "object", "properties": { "total_rewarded_in_quote": { "description": "Sum of every strategy's `rewarded_in_quote`. Each payout is valued when it is paid, so the total does not move with asset prices. For a non-USD quote, the USD total is converted at today's USD rate, so it still moves with that rate. Net of any reward fee.", "type": "string" }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "total_rewarded_in_quote", "quote_symbol", "quote_type" ] } }, "required": [ "data" ] }, "examples": { "reward-summary": { "summary": "Total bonded rewards in USD", "value": { "data": { "total_rewarded_in_quote": "43.75", "quote_symbol": "USD", "quote_type": "fiat" } } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotEnabledResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get Bonded Earn reward summary" } }, "/v1/accounts/{account_id}/earn/bonded/rewards": { "get": { "tags": [ "Bonded Earn" ], "description": "Returns the historical rewards of each bonded and instant strategy of the specified account.\n\n`rewarded` is net of any reward fee. It includes rewards paid in other assets, converted into the strategy's asset at payout time. Strategies that have never paid a reward are omitted. Sorted by asset symbol (A-Z), then unbonding period (shortest first, variable last). Results are paginated.", "operationId": "listBondedEarnRewardsByStrategy", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/BondedEarn_QuoteSymbol" }, { "$ref": "#/components/parameters/BondedEarn_QuoteType" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/BondedEarn_PageSize" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Historical rewards per strategy for the requested page.", "type": "array", "items": { "title": "BondedRewardEntry", "description": "Historical rewards of one bonded or instant strategy.", "type": "object", "properties": { "strategy_id": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyId" }, "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "strategy_type": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyType" }, "rewarded": { "description": "Lifetime rewards in the strategy's asset, net of any reward fee. Includes rewards paid in other assets, converted at payout time.", "type": "string" }, "rewarded_in_quote": { "description": "Same lifetime total in the quote currency. Each payout is valued when it is paid, so the total does not move with the asset price. For a non-USD quote, the USD total is converted at today's USD rate, so it still moves with that rate.", "type": "string" } }, "required": [ "strategy_id", "symbol", "type", "name", "strategy_type", "rewarded", "rewarded_in_quote" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "rewards-by-strategy": { "summary": "Historical rewards of one bonded strategy", "value": { "quote_symbol": "USD", "quote_type": "fiat", "data": [ { "strategy_id": "ESDQCOL-WTZEU-NU55QF", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "strategy_type": "bonded", "rewarded": "0.0175", "rewarded_in_quote": "43.75" } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotEnabledResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List Bonded Earn rewards by strategy" } }, "/v1/accounts/{account_id}/earn/bonded/rewards/upcoming": { "get": { "tags": [ "Bonded Earn" ], "description": "Returns the reward each bonded and instant strategy of the specified account expects to pay at its next reward date.\n\nThe amount is what has accrued so far plus an estimate up to that date, net of any reward fee. It leaves out rewards that belong to a later payout period. It is an estimate, and the date is a target, so payouts can be delayed. How often a strategy pays is its `reward_frequency_seconds`.\n\nThe reward is split by reward asset: `other_assets` lists the part paid in assets other than the strategy's own. Strategies with nothing pending are omitted. Sorted by asset symbol (A-Z), then unbonding period (shortest first, variable last). Results are paginated.", "operationId": "listBondedEarnUpcomingRewards", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/BondedEarn_QuoteSymbol" }, { "$ref": "#/components/parameters/BondedEarn_QuoteType" }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/BondedEarn_PageSize" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Upcoming reward per strategy for the requested page.", "type": "array", "items": { "title": "BondedUpcomingReward", "description": "Reward one bonded or instant strategy expects to pay at its next reward date.", "type": "object", "properties": { "strategy_id": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyId" }, "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "upcoming_reward": { "description": "Accrued plus projected reward in the strategy's asset, net of any reward fee. Leaves out rewards that belong to a later payout period.", "type": "string" }, "upcoming_reward_in_quote": { "description": "Same net reward converted to the quote currency.", "type": "string" }, "next_reward_date": { "description": "When the reward is paid. Shared by every entry in other_assets.", "$ref": "#/components/schemas/DateTime" }, "other_assets": { "description": "Part of the reward paid in assets other than the strategy's own. Usually empty.", "type": "array", "items": { "title": "BondedUpcomingOtherAssetReward", "description": "Part of an upcoming reward paid in another asset.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EIGEN\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Eigenlayer\").", "type": "string" }, "upcoming_reward": { "description": "Accrued plus projected reward in this asset, net of any reward fee. Leaves out rewards that belong to a later payout period.", "type": "string" }, "upcoming_reward_in_quote": { "description": "Same net reward converted to the quote currency.", "type": "string" } }, "required": [ "symbol", "type", "name", "upcoming_reward", "upcoming_reward_in_quote" ] } } }, "required": [ "strategy_id", "symbol", "type", "name", "upcoming_reward", "upcoming_reward_in_quote", "next_reward_date", "other_assets" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 }, "quote_symbol": { "description": "Symbol of the quote asset used for converted amounts (e.g., \"USD\", \"EUR\").", "type": "string" }, "quote_type": { "description": "Type of the quote asset (e.g., \"fiat\").", "type": "string" } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "upcoming-rewards": { "summary": "Upcoming reward of a restaked ETH strategy", "value": { "quote_symbol": "USD", "quote_type": "fiat", "data": [ { "strategy_id": "ESDQCOL-WTZEU-NU55QF", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "upcoming_reward": "0.0056", "upcoming_reward_in_quote": "14.00", "next_reward_date": "2026-06-01T00:00:00Z", "other_assets": [ { "symbol": "EIGEN", "type": "crypto", "name": "Eigenlayer", "upcoming_reward": "0.1", "upcoming_reward_in_quote": "0.25" } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotEnabledResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List upcoming Bonded Earn rewards" } }, "/v1/earn/bonded/strategies": { "get": { "tags": [ "Bonded Earn" ], "description": "Returns the bonded and instant strategies available in a given country.\n\nUser-agnostic endpoint. Sorted by asset symbol (A-Z), then unbonding period (shortest first, variable last). Results are paginated.", "operationId": "listBondedEarnStrategies", "parameters": [ { "in": "query", "name": "country", "schema": { "description": "ISO 3166-1 alpha-2 country code to filter available strategies (e.g., \"US\", \"GB\").", "type": "string", "pattern": "^[A-Z]{2}$" }, "style": "form", "example": "DE", "required": true }, { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/BondedEarn_PageSize" }, { "$ref": "#/components/parameters/BondedEarn_StrategyAssetTypeFilter" }, { "$ref": "#/components/parameters/BondedEarn_StrategyYieldSourceFilter" }, { "$ref": "#/components/parameters/BondedEarn_StrategySymbolFilter" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Strategies for the requested country and page.", "type": "array", "items": { "title": "BondedStrategy", "description": "Bonded or instant strategy.", "type": "object", "properties": { "id": { "description": "Strategy identifier, used to allocate and deallocate.", "type": "string" }, "strategy_type": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyType" }, "symbol": { "description": "Asset ticker symbol (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Ethereum\").", "type": "string" }, "yield_source": { "title": "YieldSource", "description": "Yield source that backs this strategy (e.g., \"staking\").", "type": "string", "enum": [ "staking", "base_rewards", "opt_in_rewards" ] }, "apy": { "description": "Annual percentage yield as a decimal string (e.g., \"3.41\"), combined across reward assets. Gross, before any reward fee.", "type": "string" }, "other_assets": { "description": "Reward assets other than the strategy's own, each with its share of `apy`. Usually empty.", "type": "array", "items": { "title": "BondedOtherAssetApy", "description": "A reward asset other than the strategy's own, with its share of the APY.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"EIGEN\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name (e.g., \"Eigenlayer\").", "type": "string" }, "apy": { "description": "This asset's share of the strategy's `apy`, as a decimal string.", "type": "string" } }, "required": [ "symbol", "type", "name", "apy" ] } }, "bonding_period": { "description": "Wait after an allocate before the funds start earning.", "$ref": "#/components/schemas/BondedEarn_BondedStrategyPeriod" }, "unbonding_period": { "description": "Wait after the exit queue before a deallocate reaches the account.", "$ref": "#/components/schemas/BondedEarn_BondedStrategyPeriod" }, "exit_queue_period": { "description": "Wait after a deallocate before unbonding starts. Always fixed and accruing.", "$ref": "#/components/schemas/BondedEarn_BondedStrategyPeriod" }, "reward_frequency_seconds": { "description": "Seconds between reward payouts.", "type": "integer", "format": "int32", "minimum": 0 }, "auto_compound": { "title": "AutoCompound", "description": "Whether rewards are added back to the allocation.", "type": "string", "enum": [ "disabled", "enabled" ] }, "user_min_allocation": { "description": "Smallest amount one allocate may move, in the strategy's asset, as a decimal string.", "type": "string" }, "user_cap": { "description": "Most the account may allocate, in the strategy's asset, as a decimal string. Absent when unlimited.", "type": "string" }, "fee_schedule": { "description": "Fee taken from this strategy's rewards, by allocated volume. Absent when it cannot be shown as one schedule.", "$ref": "#/components/schemas/BondedEarn_BondedFeeSchedule" } }, "required": [ "id", "strategy_type", "symbol", "type", "name", "yield_source", "apy", "other_assets", "bonding_period", "unbonding_period", "exit_queue_period", "reward_frequency_seconds", "auto_compound", "user_min_allocation" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "country-strategies": { "summary": "Bonded and instant strategies available in Germany", "value": { "data": [ { "id": "ESDQCOL-WTZEU-NU55QF", "strategy_type": "bonded", "symbol": "ETH", "type": "crypto", "name": "Ethereum", "yield_source": "staking", "apy": "3.10", "other_assets": [], "bonding_period": { "type": "fixed", "seconds": 0, "rewards": "not_accruing" }, "unbonding_period": { "type": "variable", "seconds": 1209600, "rewards": "not_accruing" }, "exit_queue_period": { "type": "fixed", "seconds": 0, "rewards": "accruing" }, "reward_frequency_seconds": 604800, "auto_compound": "enabled", "user_min_allocation": "0.01", "user_cap": "100", "fee_schedule": { "volume_basis": "shared_usd", "tiers": [ { "min_volume": "0", "fee_percentage": "25" }, { "min_volume": "1000000", "fee_percentage": "20" } ] } } ] } } } } } }, "400": { "$ref": "#/components/responses/EarnBadRequestResponse" }, "401": { "$ref": "#/components/responses/EarnUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/EarnForbiddenResponse" }, "404": { "$ref": "#/components/responses/BondedEarnNotEnabledResponse" }, "429": { "$ref": "#/components/responses/EarnResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/EarnInternalResponse" }, "503": { "$ref": "#/components/responses/EarnUnavailableResponse" }, "504": { "$ref": "#/components/responses/EarnDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List Bonded Earn strategies" } }, "/v1/accounts/{account_id}/funds/methods/lookup": { "get": { "operationId": "getFundingMethods", "tags": [ "Funding" ], "summary": "Look up funding method metadata", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Retrieve funding method metadata for the selected account using either `method_ids` or `network_id`. Returned metadata does not establish eligibility to deposit or withdraw.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "method_ids", "in": "query", "description": "Methods to look up. Repeat this parameter for multiple IDs. Duplicates count toward the request limit but are looked up once.", "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 25, "items": { "type": "string", "format": "uuid" } }, "example": [ "00e4796b-a142-4589-a7c1-8927933788c9" ] }, { "name": "network_id", "in": "query", "description": "Network whose methods to look up, potentially spanning multiple assets and directions.", "schema": { "type": "string", "format": "uuid" }, "example": "0d7efc1a-3787-4a29-9b64-8ca937501a50" }, { "name": "direction", "in": "query", "description": "Filters by funding direction. When omitted, includes all directions enabled for your domain. Returns 403 if the requested direction is disabled or no direction is enabled.", "schema": { "$ref": "#/components/schemas/Funding_FundingMethodDirection" }, "example": "withdrawal" }, { "$ref": "#/components/parameters/Funding_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Funding method metadata resolved for the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_FundingMethodsResult" }, "examples": { "crypto": { "summary": "Crypto method metadata", "value": { "data": [ { "id": "00e4796b-a142-4589-a7c1-8927933788c9", "direction": "withdrawal", "asset": { "symbol": "USDC", "name": "USD Coin", "type": "stablecoin" }, "method": "USDC - Arbitrum One", "network": { "id": "0d7efc1a-3787-4a29-9b64-8ca937501a50", "name": "Arbitrum One", "explorer": "https://arbiscan.io/tx/{txid}", "contract_address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" }, "payment_rails": [], "requirements": [] } ] } }, "fiat": { "summary": "Fiat metadata with a reported rail", "value": { "data": [ { "id": "3d9c3f4e-2f2d-4f4e-9c8a-1f6c0b7f4a21", "direction": "withdrawal", "asset": { "symbol": "EUR", "name": "Euro", "type": "fiat" }, "method": "SEPA bank transfer", "payment_rails": [ "sepa" ], "requirements": [] } ] } }, "bank-link": { "summary": "Method requiring a linked bank account", "value": { "data": [ { "id": "568f754f-dcc1-43ce-bcf0-fc7262c02a5f", "direction": "deposit", "asset": { "symbol": "USD", "name": "US Dollar", "type": "fiat" }, "method": "Plaid US", "payment_rails": [], "requirements": [ "bank_link" ] } ] } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/deposits": { "post": { "operationId": "createDeposit", "tags": [ "Funding" ], "summary": "Create deposit", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Requests a deposit from an eligible linked bank account into the selected account. The Account Link must be active, and its parent Bank Link connection must be live.\n\nUse a deposit method whose `requirements` include `bank_link`, with a linked bank account from a provider that the method supports. A method that cannot run from a linked bank account is rejected with a `bad_request` error on `method_id`.\n\nThis operation is not idempotent. Do not automatically retry after a timeout or an ambiguous error because the deposit may already have been initiated.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateDepositBody" }, "examples": { "bank-link": { "value": { "method_id": "568f754f-dcc1-43ce-bcf0-fc7262c02a5f", "asset_symbol": "USD", "amount": "10.00", "source": { "type": "account_link", "account_link_id": "al_123e4567-e89b-12d3-a456-426614174000" } } } } } } }, "responses": { "202": { "description": "Deposit initiation accepted; settlement is asynchronous.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateDepositResult" }, "examples": { "accepted": { "value": { "data": { "reference": "FTZrZD9-miDLDeq3YH1uuy0lTh18Oe" } } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "404": { "$ref": "#/components/responses/FundingNotFoundResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/deposits/methods": { "get": { "operationId": "listDepositMethods", "tags": [ "Funding" ], "summary": "List deposit methods", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns the crypto and fiat deposit methods available to the selected account for an asset. A page may contain fewer methods than requested or no methods even when `next_page_token` is present. Continue requesting pages until `next_page_token` is absent.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "asset_symbol", "in": "query", "required": true, "description": "Public asset symbol whose deposit methods to return.", "example": "BTC", "schema": { "$ref": "#/components/schemas/AssetSymbol" } }, { "$ref": "#/components/parameters/Funding_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Deposit methods available for the selected account and asset.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_DepositMethodsResult" }, "examples": { "bitcoin": { "summary": "Bitcoin deposit method", "value": { "data": [ { "id": "2fa11f79-eeba-4d4e-afda-029abff6e29e", "asset": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto" }, "method": "Bitcoin", "network": "Bitcoin", "requirements": [], "network_info": { "explorer": "https://mempool.space/tx/", "confirmations": "3", "est_confirmation_time": "45" }, "minimum": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.0001" }, "maximum": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "500" }, "supports_virtual_accounts": false } ] } }, "usd-ach": { "summary": "USD ACH deposit method", "value": { "data": [ { "id": "5e764f4c-f924-47f0-9fcb-6f98c37d1575", "asset": { "symbol": "USD", "name": "US Dollar", "type": "fiat" }, "method": "ACH", "network": "ACH", "requirements": [], "activation_status": "completed", "supports_virtual_accounts": true, "minimum": { "symbol": "USD", "name": "US Dollar", "type": "fiat", "amount": "1.00" } } ] } }, "plaid-us": { "summary": "USD deposit method requiring a linked bank account", "value": { "data": [ { "id": "568f754f-dcc1-43ce-bcf0-fc7262c02a5f", "asset": { "symbol": "USD", "name": "US Dollar", "type": "fiat" }, "method": "Plaid US", "network": "Plaid US", "requirements": [ "bank_link" ] } ] } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/deposits/methods/{method_id}/activation": { "post": { "operationId": "activateDepositMethod", "tags": [ "Funding" ], "summary": "Activate deposit method", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Requests activation of a deposit method whose `activation_status` is `needed`. A successful response acknowledges the request; check `activation_status` to determine when the method is ready.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "method_id", "in": "path", "required": true, "description": "Deposit funding method identifier returned by the deposit-methods endpoint.", "example": "5e764f4c-f924-47f0-9fcb-6f98c37d1575", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deposit method activation accepted. Activation may still be pending.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/FundingDepositActivationBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/deposits/limits/{asset_symbol}": { "get": { "operationId": "listDepositLimits", "tags": [ "Funding" ], "summary": "List deposit limits", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns current deposit limits for the selected account and asset, grouped by funding method.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "asset_symbol", "in": "path", "required": true, "description": "Public asset symbol whose deposit limits to return.", "example": "BTC", "schema": { "type": "string", "minLength": 1, "maxLength": 16 } }, { "$ref": "#/components/parameters/Funding_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Deposit limits for the selected account and asset.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_DepositLimitsResult" }, "examples": { "bitcoin": { "summary": "Bitcoin deposit limits", "value": { "data": [ { "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e", "maximum_amount": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.75" }, "period_limits": [ { "type": "amount", "period": "daily", "period_seconds": 86400, "asset": { "symbol": "USD", "type": "fiat" }, "remaining": "50000", "maximum": "100000" } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/withdrawals/methods": { "get": { "operationId": "listWithdrawalMethods", "tags": [ "Funding" ], "summary": "List withdrawal methods", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns the fiat and cryptocurrency withdrawal methods available to the selected account for an asset. A page may contain fewer methods than requested or no methods even when `next_page_token` is present. Continue requesting pages until `next_page_token` is absent.\n\nListing a method does not establish that the account meets every eligibility requirement. Use List withdrawal limits for balance and rolling-limit constraints.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "asset_symbol", "in": "query", "required": true, "description": "Public asset symbol whose withdrawal methods to return.", "example": "BTC", "schema": { "$ref": "#/components/schemas/AssetSymbol" } }, { "$ref": "#/components/parameters/Funding_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Withdrawal methods available for the selected account and asset.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_WithdrawalMethodsResult" }, "examples": { "bitcoin": { "summary": "Bitcoin withdrawal method", "value": { "data": [ { "id": "2fa11f79-eeba-4d4e-afda-029abff6e29e", "asset": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto" }, "method": "Bitcoin", "network": "Bitcoin", "network_info": { "explorer": "https://mempool.space/tx/", "confirmations": "3", "est_confirmation_time": "45" }, "minimum": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.0005" }, "requirements": [], "address_fields": [ { "key": "address", "required": true, "allowed_values": [] } ] } ] } }, "sepa": { "summary": "SEPA fiat withdrawal method", "value": { "data": [ { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "asset": { "symbol": "EUR", "name": "Euro", "type": "fiat" }, "method": "SEPA", "network": "SEPA", "minimum": { "symbol": "EUR", "name": "Euro", "type": "fiat", "amount": "10.00" }, "requirements": [], "address_fields": [ { "key": "iban", "required": true, "allowed_values": [] }, { "key": "bic", "required": false, "allowed_values": [] } ] } ] } }, "linked-bank-account": { "summary": "Fiat method requiring a linked bank account", "value": { "data": [ { "id": "1d1b1a62-0e7b-4cee-80ab-9fdbdf8cb3a2", "asset": { "symbol": "USD", "name": "US Dollar", "type": "fiat" }, "method": "Linked bank account", "requirements": [ "bank_link" ], "address_fields": [] } ] } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/withdrawals/limits/{asset_symbol}": { "get": { "operationId": "listWithdrawalLimits", "tags": [ "Funding" ], "summary": "List withdrawal limits", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns the selected account's current withdrawal limits by funding method for an asset.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "asset_symbol", "in": "path", "required": true, "description": "Public asset symbol whose withdrawal limits to return.", "example": "BTC", "schema": { "type": "string", "minLength": 1, "maxLength": 16 } }, { "$ref": "#/components/parameters/Funding_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Withdrawal limits for the selected account and asset.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_WithdrawalLimitsResult" }, "examples": { "bitcoin": { "summary": "Bitcoin withdrawal limits", "value": { "data": [ { "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e", "maximum_amount": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.75" }, "maximum_reason": "limits", "period_limits": [ { "type": "amount", "period": "daily", "period_seconds": 86400, "asset": { "symbol": "USD", "type": "fiat" }, "remaining": "50000", "maximum": "100000" } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/withdrawals/holds": { "get": { "operationId": "listWithdrawalHolds", "tags": [ "Funding" ], "summary": "List withdrawal holds", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns the active holds that reduce the selected account's balance available for withdrawal, ordered by scheduled release time. Held funds remain in the account but cannot be withdrawn until the hold ends, so a withdrawal limit whose `maximum_reason` is `balance` can be lower than the account balance while holds are active. For example, a bank-transfer deposit can be held for several days after it is credited. When continuing with a page token, omit `page_size` or reuse the previous value. A different value returns a `400` error for `page_size`. Each page reflects the active holds at the time of the request. Holds that end between pages are omitted. Holds created or rescheduled to release before the last returned hold are not included in later pages. Restart the listing to see them. If a change prevents safe continuation, the API returns a `400` error for `page_token`; restart the listing without a page token.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/Funding_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Active withdrawal holds for the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_WithdrawalHoldsResult" }, "examples": { "bank-deposit-hold": { "summary": "A held bank-transfer deposit", "value": { "data": [ { "asset": { "symbol": "USD", "type": "fiat" }, "equivalent_amount": { "symbol": "USD", "name": "US Dollar", "type": "fiat", "amount": "20.00" }, "release_at": "2026-10-09T14:32:10Z", "type": "deposit", "deposit_transaction_id": "FTB4EdB-xPnSiIF3gkyExWxxKdzMs3" } ] } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/fees": { "post": { "operationId": "calculateFundingFees", "tags": [ "Funding" ], "summary": "Calculate funding fees", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Calculates a fee quote for a gross amount using one deposit or withdrawal method. Each request creates a new quote and moves no funds.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CalculateFundingFeesBody" }, "examples": { "bitcoin": { "summary": "Quote a Bitcoin withdrawal fee", "value": { "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e", "amount": "0.01000000" } } } } } }, "responses": { "201": { "description": "Fee quote created for the selected account, method, and gross amount.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CalculateFundingFeesResult" }, "examples": { "bitcoin-withdrawal": { "summary": "Bitcoin withdrawal fee quote", "value": { "data": { "fee": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.00005000" }, "gross_amount": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.01000000" }, "net_amount": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.00995000" }, "fee_token": "sMBfm8D9i3TqR-k1zP2cX7vL0nH5aJ4u" } } }, "bitcoin-deposit": { "summary": "Bitcoin deposit fee quote, without a fee token", "value": { "data": { "fee": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.00000000" }, "gross_amount": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.01000000" }, "net_amount": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.01000000" } } } } } } } }, "400": { "$ref": "#/components/responses/FundingWithdrawalFeeQuoteBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/withdrawals": { "post": { "operationId": "createWithdrawal", "tags": [ "Funding" ], "summary": "Create withdrawal", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Creates a fiat or cryptocurrency withdrawal from the selected account to a registered funding address or a supported linked bank account.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateWithdrawalBody" }, "examples": { "fiat-method": { "summary": "Withdraw euros to a registered bank address", "value": { "scope": { "method_id": "fb3ec7fd-3280-4142-ae14-708b995bedef" }, "destination": { "type": "funding_address", "address_id": "AB12345-6789A-BCDEFG" }, "symbol": "EUR", "amount": "10.00" } }, "linked-bank-account": { "summary": "Withdraw dollars to a linked bank account", "value": { "scope": { "method_id": "d5d39ce4-9218-4ffb-9166-52d41801a58a" }, "destination": { "type": "account_link", "account_link_id": "al_550e8400-e29b-41d4-a716-446655440000" }, "symbol": "USD", "amount": "10.00" } }, "bitcoin-method": { "summary": "Withdraw Bitcoin through a specific funding method", "value": { "scope": { "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e" }, "destination": { "type": "funding_address", "address_id": "AB12345-6789A-BCDEFG" }, "symbol": "BTC", "amount": "0.01000000", "fee_token": "sMBfm8D9i3TqR-k1zP2cX7vL0nH5aJ4u" } }, "bitcoin-network": { "summary": "Withdraw Bitcoin through a network with one eligible method", "value": { "scope": { "network_id": "6d7f9c7e-588d-4e56-a6f7-f1e9ada7e639" }, "destination": { "type": "funding_address", "address_id": "AB12345-6789A-BCDEFG" }, "symbol": "BTC", "amount": "0.01000000" } } } } } }, "responses": { "201": { "description": "Withdrawal created for the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateWithdrawalResult" }, "examples": { "fiat-withdrawal": { "summary": "Euro withdrawal created", "value": { "data": { "withdrawal_id": "FTSBuuG-9BctU4m3Emt88submmZVKY", "net_amount": { "symbol": "EUR", "name": "Euro", "type": "fiat", "amount": "9.50" }, "gross_amount": { "symbol": "EUR", "name": "Euro", "type": "fiat", "amount": "10.00" }, "fee": { "symbol": "EUR", "name": "Euro", "type": "fiat", "amount": "0.50" } } } }, "bitcoin": { "summary": "Bitcoin withdrawal created", "value": { "data": { "withdrawal_id": "FTSBuuG-9BctU4m3Emt88submmZVKY", "net_amount": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.00995000" }, "gross_amount": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.01000000" }, "fee": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.00005000" } } } } } } } }, "400": { "$ref": "#/components/responses/FundingWithdrawalBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "description": "Access is forbidden, the funding method requires activation, or activation was denied.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Forbidden", "$ref": "#/components/schemas/ForbiddenError" }, { "title": "Funding method activation required", "$ref": "#/components/schemas/Funding_FundingMethodActivationRequiredError" }, { "title": "Funding method activation denied", "$ref": "#/components/schemas/Funding_FundingMethodActivationDeniedError" } ] }, "examples": { "forbidden": { "summary": "Access forbidden", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "activation-required": { "summary": "Funding method activation required", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "funding_method_activation_required" } } }, "activation-denied": { "summary": "Funding method activation denied", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "funding_method_activation_denied" } } } } } } }, "404": { "description": "The withdrawal destination does not exist or is not available to the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "account-link-not-found": { "summary": "Account Link not found", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "not_found" } } } } } } }, "409": { "description": "The withdrawal requires address-ownership verification, or account settings temporarily block withdrawals.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Address-ownership verification required", "$ref": "#/components/schemas/Funding_WithdrawalVerificationRequiredError" }, { "title": "Account settings locked", "$ref": "#/components/schemas/Funding_WithdrawalAccountSettingsLockedError" } ] }, "examples": { "verification-required": { "summary": "Address-ownership verification required", "value": { "verification_methods": [ "self_attestation", "satoshi_test", "digital_signature" ], "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "withdrawal_verification_required" } } }, "account-settings-locked": { "summary": "Account settings locked", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "withdrawal_account_settings_locked" } } } } } } }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/deposits/addresses": { "get": { "operationId": "listDepositAddresses", "tags": [ "Funding" ], "summary": "List deposit addresses", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Lists deposit destinations available for a funding method on the selected account. Reuse a page token only with the account and funding method used to obtain it.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "method_id", "in": "query", "required": true, "description": "Deposit method whose usable destinations to return. A destination may have been claimed under a compatible method.", "example": "479c45eb-6558-430a-8794-4308137d2588", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Funding_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Deposit addresses available for the selected account and method.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ListDepositAddressesResult" }, "examples": { "crypto-and-fiat": { "summary": "Crypto and fiat deposit addresses", "value": { "data": [ { "address_details": { "fiat": { "bank": "Banking Circle", "iban": "GB29NWBK60161331926819", "bic": "NWBKGB2L", "name_on_account": "Payward Ltd", "reference": "AA71 N84G 7JER CJPQ" } } }, { "address_details": { "crypto": { "address": "bc1qexampledepositaddress" } }, "expire_time": "2026-08-11T09:20:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } }, "post": { "operationId": "claimDepositAddress", "tags": [ "Funding" ], "summary": "Claim deposit address", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Claims a crypto deposit address for a funding method available to the selected account. Bitcoin over Lightning uses a per-payment invoice instead of a reusable address; use Create Lightning invoice. Compatible funding methods can share address limits, so list and reuse an existing address before claiming another. This operation is non-idempotent; after an unknown outcome, list deposit addresses before retrying.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ClaimDepositAddressBody" }, "examples": { "stellar": { "summary": "Claim a Stellar deposit address", "value": { "method_id": "479c45eb-6558-430a-8794-4308137d2588" } } } } } }, "responses": { "200": { "description": "Crypto deposit address claimed for the selected account and method.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ClaimDepositAddressResult" }, "examples": { "stellar": { "summary": "Stellar deposit address with memo", "value": { "data": { "address": "GABCD1234EXAMPLEDEPOSITADDRESS", "memo": "123456789" } } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "409": { "description": "The funding method has reached its deposit-address limit.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_DepositAddressLimitReachedError" }, "examples": { "address-limit-reached": { "summary": "Deposit-address limit reached", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "deposit_address_limit_reached" } } } } } } }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/addresses": { "get": { "operationId": "listFundingAddresses", "tags": [ "Funding" ], "summary": "List funding addresses", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Lists user-added withdrawal addresses registered for the selected account. Omit both filters to list all user-added withdrawal addresses. Use List deposit addresses for claimed deposit addresses.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/Funding_PageSize" }, { "$ref": "#/components/parameters/PageToken" }, { "name": "method_id", "in": "query", "required": false, "description": "Withdrawal method identifier returned as `id` by List withdrawal methods. Returns addresses registered for the method, its network, or its network group. Cannot be combined with `network_id`. An empty value is rejected.", "example": "479c45eb-6558-430a-8794-4308137d2588", "schema": { "type": "string", "format": "uuid" } }, { "name": "network_id", "in": "query", "required": false, "description": "Network identifier returned as `network_id` by List withdrawal methods. Returns addresses registered for the network or its network group; excludes addresses registered for individual methods. Cannot be combined with `method_id`. An empty value is rejected.", "example": "6d7f9c7e-588d-4e56-a6f7-f1e9ada7e639", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "User-added withdrawal addresses for the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ListFundingAddressesResult" }, "examples": { "crypto": { "summary": "Crypto funding addresses", "value": { "data": [ { "address_id": "AB12345-6789A-BCDEFG", "scope": { "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e" }, "name": "My cold wallet", "address_details": { "crypto": { "address": "bc1qexampleaddress", "tag": "123", "memo": "456" } } } ], "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } }, "network-filter": { "summary": "Addresses filtered by network", "value": { "data": [ { "address_id": "AB98765-4321Z-YXWVUT", "scope": { "network_id": "6d7f9c7e-588d-4e56-a6f7-f1e9ada7e639" }, "name": "My Ethereum address", "address_details": { "crypto": { "address": "0x0123456789abcdef0123456789abcdef01234567" } } } ] } }, "empty": { "summary": "No funding addresses", "value": { "data": [] } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } }, "post": { "operationId": "createFundingAddress", "tags": [ "Funding" ], "summary": "Create funding address", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Registers a user-added fiat or cryptocurrency funding address for withdrawals on the selected account. Registration may activate an applicable funding method.\n\nRequires the **Add withdrawal addresses** API key permission.\n\nThis operation is not idempotent. After an unknown outcome, list funding addresses before retrying.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateFundingAddressBody" }, "examples": { "sepa": { "summary": "Register a SEPA funding address", "value": { "scope": { "method_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "name": "My SEPA account", "address_details": { "fiat": { "iban": "DE89370400440532013000" } } } }, "ach": { "summary": "Register an ACH funding address", "value": { "scope": { "method_id": "c82d46e3-2719-48a2-85fd-a2907a6a8bd4" }, "name": "My bank account", "address_details": { "fiat": { "account_number": "12345678", "routing_number": "021000021", "account_type": "checking" } } } }, "wire": { "summary": "Register a wire funding address", "value": { "scope": { "method_id": "1879e694-4427-48f3-91d8-9fd61a2e91a0" }, "name": "My wire account", "address_details": { "fiat": { "account_number": "12345678", "routing_number": "021000021", "bank": "Example Bank" } } } }, "bitcoin": { "summary": "Register a Bitcoin funding address", "value": { "scope": { "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e" }, "name": "My cold wallet", "address_details": { "crypto": { "address": "bc1qexampleaddress" } } } } } } } }, "responses": { "200": { "description": "Funding address registered for the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateFundingAddressResult" }, "examples": { "sepa": { "summary": "SEPA funding address registered", "value": { "data": { "address_id": "AB12345-6789A-BCDEFG" } } } } } } }, "400": { "$ref": "#/components/responses/FundingCreateAddressBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "description": "Access is forbidden, the funding method requires activation, or activation was denied.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Forbidden", "$ref": "#/components/schemas/ForbiddenError" }, { "title": "Funding method activation required", "$ref": "#/components/schemas/Funding_FundingMethodActivationRequiredError" }, { "title": "Funding method activation denied", "$ref": "#/components/schemas/Funding_FundingMethodActivationDeniedError" } ] }, "examples": { "forbidden": { "summary": "Access forbidden", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "activation-required": { "summary": "Funding method activation required", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "funding_method_activation_required" } } }, "activation-denied": { "summary": "Funding method activation denied", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "funding_method_activation_denied" } } } } } } }, "409": { "description": "An address limit applying to the selected scope has been reached, an address with the same name already exists for the account owner, or account settings temporarily block address changes.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Funding address limit reached", "$ref": "#/components/schemas/Funding_WithdrawalAddressLimitReachedError" }, { "title": "Funding address already exists", "$ref": "#/components/schemas/Funding_WithdrawalAddressAlreadyExistsError" }, { "title": "Account settings locked", "$ref": "#/components/schemas/Funding_WithdrawalAddressAccountSettingsLockedError" } ] }, "examples": { "address-limit-reached": { "summary": "Funding address limit reached", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "withdrawal_address_limit_reached" } } }, "address-already-exists": { "summary": "Funding address already exists", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "withdrawal_address_already_exists" } } }, "account-settings-locked": { "summary": "Account settings locked", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "withdrawal_address_account_settings_locked" } } } } } } }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/deposits/lightning-invoices": { "post": { "operationId": "createLightningInvoice", "tags": [ "Funding" ], "summary": "Create Lightning invoice", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Creates a single-use BOLT11 invoice for a fixed-amount Bitcoin Lightning deposit. Each request creates a new invoice and is non-idempotent; after an unknown outcome, request a new invoice. Amounts outside the Lightning deposit limits reported by List deposit methods return `400`. Completed deposits appear in Portfolio transactions and trigger `transaction.deposit` webhook events when a webhook subscription is configured.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateLightningInvoiceBody" }, "examples": { "bitcoin": { "summary": "Invoice for a Bitcoin deposit", "value": { "asset_symbol": "BTC", "amount": "0.0005" } } } } } }, "responses": { "200": { "description": "Lightning invoice created for the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateLightningInvoiceResult" }, "examples": { "bitcoin": { "summary": "Invoice for a Bitcoin deposit", "value": { "data": { "invoice": "lnbc500u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sqdqqcqzpgxqyz5vqsp5usyc4lk9chsfp53kvcnvq456ganh60d89reykdngsmtj6yw3nhvq9qyyssqjcewm5cjwz4a6rfjx77c490yced6pemk0upkxhy89cmm7sct66k8gneanwykzgdrwrfje69h9u5u0w57rrcsysas7gadwmzxc8c6t0spjazup6", "expires_at": "2026-08-03T12:34:56Z" } } } } } } }, "400": { "$ref": "#/components/responses/FundingLightningInvoiceBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/addresses/{address_id}": { "get": { "operationId": "getFundingAddress", "tags": [ "Funding" ], "summary": "Get funding address", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns one user-added fiat or cryptocurrency funding address registered for the selected account.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "address_id", "in": "path", "required": true, "description": "Stable identifier returned when the funding address was registered.", "example": "AB12345-6789A-BCDEFG", "schema": { "type": "string", "minLength": 20, "maxLength": 20, "pattern": "^AB[A-Za-z0-9]{5}-[A-Za-z0-9]{5}-[A-Za-z0-9]{6}$" } } ], "responses": { "200": { "description": "Funding address retrieved for the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_GetFundingAddressResult" }, "examples": { "bitcoin": { "summary": "Bitcoin funding address", "value": { "data": { "address_id": "AB12345-6789A-BCDEFG", "scope": { "method_id": "2fa11f79-eeba-4d4e-afda-029abff6e29e" }, "name": "My cold wallet", "address_details": { "crypto": { "address": "bc1qexampleaddress", "tag": "123", "memo": "456" } } } } }, "sepa": { "summary": "SEPA funding address", "value": { "data": { "address_id": "AB98765-4321Z-YXWVUT", "scope": { "method_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "name": "My SEPA account", "address_details": { "fiat": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX" } } } } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "404": { "$ref": "#/components/responses/FundingNotFoundResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } }, "patch": { "operationId": "updateFundingAddress", "tags": [ "Funding" ], "summary": "Update funding address", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Renames a user-added funding address for the selected account.\n\nRequires the **Add withdrawal addresses** API key permission.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "address_id", "in": "path", "required": true, "description": "Identifier of the user-added funding address to rename.", "example": "AB12345-6789A-BCDEFG", "schema": { "type": "string", "pattern": "^AB[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{6}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_UpdateFundingAddressBody" }, "examples": { "bitcoin": { "summary": "Rename a Bitcoin funding address", "value": { "name": "My cold wallet" } } } } } }, "responses": { "204": { "description": "Funding address renamed.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/FundingUpdateAddressBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingUpdateAddressForbiddenResponse" }, "404": { "$ref": "#/components/responses/FundingNotFoundResponse" }, "409": { "description": "An address with the same name already exists for the account owner.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_WithdrawalAddressAlreadyExistsError" }, "examples": { "address-already-exists": { "summary": "Withdrawal address already exists", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "withdrawal_address_already_exists" } } } } } } }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } }, "delete": { "operationId": "deleteFundingAddress", "tags": [ "Funding" ], "summary": "Delete funding address", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Permanently deletes a user-added funding address for the selected account. Claimed deposit addresses cannot be deleted through this operation.\n\nRequires the **Add withdrawal addresses** API key permission.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "address_id", "in": "path", "required": true, "description": "Stable funding-address identifier.", "example": "AB12345-6789A-BCDEFG", "schema": { "type": "string", "pattern": "^AB[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{6}$" } } ], "responses": { "204": { "description": "Funding address deleted.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "404": { "description": "The funding address does not exist or is not available to the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "funding-address-not-found": { "$ref": "#/components/examples/funding-not-found" } } } } }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "501": { "$ref": "#/components/responses/FundingUnimplementedResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/transfers": { "post": { "operationId": "createTransfer", "tags": [ "Funding" ], "summary": "Create transfer", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Creates a transfer between accounts in the authenticated caller's program.\n\n`Idempotency-Key` is optional. Reuse the same key with an unchanged request to prevent duplicate execution. Without a key, do not retry an unknown outcome until you reconcile the `from` account's Portfolio transactions.\n\nOnce recorded, a key remains globally reserved beyond 24 hours and cannot be reused for another transfer, including one for a different acting user or account.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Request to create an account-funded transfer.", "type": "object", "required": [ "from", "to", "asset", "amount" ], "properties": { "from": { "description": "Public account ID to debit.", "$ref": "#/components/schemas/AccountId" }, "to": { "description": "Public account ID to credit.", "$ref": "#/components/schemas/AccountId" }, "asset": { "description": "Asset ticker symbol to transfer. Currency assets and tokenized assets such as xStocks are supported when eligible for transfers.", "$ref": "#/components/schemas/AssetSymbol" }, "amount": { "description": "Positive amount to transfer, denominated in `asset` and represented as a string to preserve precision.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "examples": { "account-recipient": { "summary": "Transfer a currency asset to an account", "value": { "from": "WVSD33HRMGSZUBM7", "to": "WNPY3PJZYD4L9E7B", "asset": "USD", "amount": "25.50" } }, "xstock-recipient": { "summary": "Transfer an xStock to an account", "value": { "from": "WVSD33HRMGSZUBM7", "to": "WNPY3PJZYD4L9E7B", "asset": "TSLAx", "amount": "1.00" } } } } } }, "responses": { "201": { "description": "Transfer created. Replaying an unchanged request with the same idempotency key returns the transfer's current recorded outcome. It may differ from the first response and does not include an `Idempotent-Replayed` header.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_CreateTransferEnvelope" }, "examples": { "created": { "summary": "Transfer accepted", "value": { "data": { "transfer_id": "TRYCMN7-WXKJM-F47YIM", "status": "pending" } } }, "completed": { "summary": "Transfer creation completed", "value": { "data": { "transfer_id": "TRYCMN7-WXKJM-F47YIM", "status": "complete" } } } } } } }, "400": { "$ref": "#/components/responses/FundingTransferBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "409": { "description": "The idempotency key conflicts with a recorded transfer request, or the conversion rate used for the transfer is stale.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Idempotency key conflict", "$ref": "#/components/schemas/Funding_IdempotencyConflictError" }, { "title": "Stale conversion rate", "$ref": "#/components/schemas/Funding_StaleConversionRateError" } ] }, "examples": { "idempotency-key-conflict": { "$ref": "#/components/examples/funding-idempotency-conflict" }, "stale-conversion-rate": { "$ref": "#/components/examples/funding-stale-conversion-rate" } } } } }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/transfers/derivatives": { "post": { "operationId": "createDerivativesTransfer", "tags": [ "Derivative transfers" ], "summary": "Create derivatives transfer", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Creates a transfer between the selected account's spot and futures balances.\n\nThis operation is not idempotent. If the outcome is unknown, reconcile the balances before retrying.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Derivatives transfer request.", "type": "object", "required": [ "asset", "amount", "from", "to" ], "properties": { "asset": { "description": "Currency to transfer.", "type": "string", "minLength": 1, "maxLength": 16 }, "amount": { "description": "Amount to transfer.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(0*[1-9][0-9]*(\\.[0-9]+)?|0+\\.(0?[1-9][0-9]*))$" }, "from": { "description": "Balance to debit.", "$ref": "#/components/schemas/DerivativeTransfers_DerivativesTransferLocation" }, "to": { "description": "Balance to credit.", "$ref": "#/components/schemas/DerivativeTransfers_DerivativesTransferLocation" } } }, "examples": { "spot-to-futures": { "summary": "Move funds from spot to futures", "value": { "asset": "USD", "amount": "25.50", "from": "spot", "to": "futures" } }, "futures-to-spot": { "summary": "Move funds from futures to spot", "value": { "asset": "USD", "amount": "25.50", "from": "futures", "to": "spot" } } } } } }, "responses": { "200": { "description": "Derivatives transfer accepted for processing.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DerivativeTransfers_CreateDerivativesTransferEnvelope" }, "examples": { "accepted": { "summary": "Derivatives transfer accepted", "value": { "data": { "transfer_id": "FTSBuuG-9BctU4m3Emt88submmZVKY", "status": "accepted" } } } } } } }, "400": { "$ref": "#/components/responses/FundingDerivativesTransferBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "404": { "$ref": "#/components/responses/FundingDerivativesTransferNotFoundResponse" }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/funds/testing/deposit": { "post": { "operationId": "simulateFundingDeposit", "tags": [ "Funding" ], "summary": "Simulate funding deposit", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Inserts a synthetic successful deposit for a funding method available to the selected account. Use this operation only in non-production test environments. It is unavailable in production.\n\nUse a stable `method_id` returned by the deposit-methods endpoint. Payward Services resolves the method's asset and internal gateway routing; callers must not supply internal funding identifiers, gateway numbers, statuses, or flags.\n\nThis operation is not idempotent. If a request times out or otherwise has an unknown outcome, do not retry it automatically because the deposit may already have been inserted. Reconcile the account's Portfolio transactions before submitting another simulation.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_SimulateFundingDepositBody" }, "examples": { "ethereum": { "summary": "Simulate an Ethereum deposit", "value": { "method_id": "479c45eb-6558-430a-8794-4308137d2588", "amount": "0.25", "name": "PWS funding deposit test", "reference": "PWSPAY-1229" } } } } } }, "responses": { "200": { "description": "Simulated deposit accepted for processing.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_SimulateFundingDepositResult" }, "examples": { "accepted": { "summary": "Deposit simulation accepted", "value": { "data": { "simulated": true } } } } } } }, "400": { "$ref": "#/components/responses/FundingBadRequestResponse" }, "401": { "$ref": "#/components/responses/FundingUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/FundingForbiddenResponse" }, "404": { "description": "The funding method is not available to the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "funding-method-not-found": { "$ref": "#/components/examples/funding-method-not-found" } } } } }, "429": { "$ref": "#/components/responses/FundingResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/FundingInternalResponse" }, "503": { "$ref": "#/components/responses/FundingUnavailableResponse" }, "504": { "$ref": "#/components/responses/FundingDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/portfolio": { "get": { "tags": [ "Portfolio" ], "summary": "Get portfolio", "description": "Returns one account portfolio snapshot containing account-level values and the per-asset breakdown. Quote-denominated monetary amounts use an `_in_quote` suffix; native asset amounts omit the suffix.", "operationId": "getPortfolio", "parameters": [ { "in": "query", "name": "quote_symbol", "schema": { "description": "Quote asset symbol. Required when `quote_type` is `stablecoin`. The `USD` default applies only when `quote_type` is omitted or `fiat`.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "$ref": "#/components/schemas/Portfolio_QuoteAssetType" }, "description": "Quote asset classification. Supports fiat and stablecoin.", "style": "form", "example": "fiat" }, { "in": "query", "name": "with_zero_balances", "schema": { "type": "boolean", "default": false }, "description": "Whether to include assets with zero balances.", "style": "form", "example": true }, { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Portfolio_Portfolio" } }, "required": [ "data" ] }, "examples": { "portfolio": { "value": { "data": { "as_of": "2026-08-25T12:34:56Z", "quote": { "symbol": "USD", "type": "fiat", "usd_index_rate": "1" }, "total_in_quote": "41000.00", "availability": { "available_in_quote": "30000.00", "withheld": { "total_in_quote": "11000.00", "open_orders_in_quote": "2000.00", "earn_in_quote": "4000.00", "other_in_quote": "5000.00" } }, "assets": [ { "symbol": "BTC", "type": "crypto", "balances": { "total": "0.5", "total_in_quote": "31000.00", "main": { "total": "0.5", "total_in_quote": "31000.00" } }, "index_price_in_quote": "62000.00", "availability": { "trade": "0.5" }, "pnl": { "reference_currency": { "symbol": "USD", "type": "fiat" }, "unrealized_in_quote": "3500.00", "cost_basis_in_quote": "27500.00", "avg_entry_price_in_quote": "55000.00", "status": { "avg_entry_price": "ready", "cost_basis": "ready", "unrealized": "ready", "realized": "in_progress" } } }, { "symbol": "USD", "type": "fiat", "balances": { "total": "10000.00", "total_in_quote": "10000.00", "main": { "total": "10000.00", "total_in_quote": "10000.00" } }, "index_price_in_quote": "1" } ], "pnl": { "reference_currency": { "symbol": "USD", "type": "fiat" }, "unrealized_in_quote": "3500.00", "realized_in_quote": "-3.7440", "status": { "unrealized": "ready", "realized": "in_progress" } } } } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/portfolio-bad-request" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/portfolio-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/portfolio-forbidden" } } } } }, "404": { "description": "Not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/portfolio-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/portfolio-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/portfolio-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/portfolio-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/portfolio-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/portfolio-deadline-exceeded" } } } } } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ] } }, "/v1/accounts/{account_id}/portfolio/history": { "get": { "tags": [ "Portfolio" ], "description": "Returns daily portfolio valuation snapshots for an account over the requested time window. Use `assets` to include per-asset balances for selected holdings.", "operationId": "listPortfolioHistory", "parameters": [ { "in": "query", "name": "assets", "schema": { "description": "Asset filters to include in the per-data-point breakdown. Each entry is a {symbol, type} pair. Empty or omitted returns no per-asset rows.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_AssetFilter" } }, "style": "form", "example": [ { "symbol": "BTC", "type": "crypto" } ] }, { "in": "query", "name": "start_timestamp", "description": "Lower bound of the portfolio history time window.", "schema": { "$ref": "#/components/schemas/DateTime" }, "style": "form", "example": "2025-01-01T00:00:00Z" }, { "in": "query", "name": "end_timestamp", "description": "Upper bound of the portfolio history time window.", "schema": { "$ref": "#/components/schemas/DateTime" }, "style": "form", "example": "2025-12-31T23:59:59Z" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Quote asset symbol to denominate values in. Required when `quote_type` is `stablecoin`. The `USD` default applies only when `quote_type` is omitted or `fiat`.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "$ref": "#/components/schemas/Portfolio_QuoteAssetType" }, "description": "Quote asset classification. Supports fiat and stablecoin.", "style": "form", "example": "fiat" }, { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "description": "Response for ListPortfolioHistory.", "type": "object", "properties": { "data": { "description": "Portfolio data points ordered by ascending timestamp. Always present; serialized as an empty array when there is no history in the window.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_PortfolioHistoryDataPoint" } }, "quote_symbol": { "description": "Quote asset the values are denominated in.", "type": "string" }, "quote_type": { "$ref": "#/components/schemas/Portfolio_QuoteAssetType" }, "start_timestamp": { "description": "Start of the resolved portfolio history time window.", "$ref": "#/components/schemas/DateTime" }, "end_timestamp": { "description": "End of the resolved portfolio history time window.", "$ref": "#/components/schemas/DateTime" } }, "required": [ "data", "quote_symbol", "quote_type", "start_timestamp", "end_timestamp" ] }, "examples": { "btc-usd-tslax-year": { "summary": "Mixed crypto, fiat, and xStocks history quoted in USD", "value": { "data": [ { "timestamp": "2025-01-01T00:00:00Z", "assets": [ { "symbol": "XBT", "type": "crypto", "amount": "0.50000000" }, { "symbol": "USD", "type": "fiat", "amount": "100.00" }, { "symbol": "TSLAx", "type": "xstock", "amount": "2.00000000" } ], "value": "20000.50", "total_pnl": "100.00" }, { "timestamp": "2025-06-01T00:00:00Z", "assets": [ { "symbol": "XBT", "type": "crypto", "amount": "0.50000000" }, { "symbol": "USD", "type": "fiat", "amount": "100.00" }, { "symbol": "TSLAx", "type": "xstock", "amount": "2.50000000" } ], "value": "22500.75", "total_pnl": "2600.25" }, { "timestamp": "2025-12-31T00:00:00Z", "assets": [ { "symbol": "XBT", "type": "crypto", "amount": "0.55000000" }, { "symbol": "USD", "type": "fiat", "amount": "150.00" }, { "symbol": "TSLAx", "type": "xstock", "amount": "3.00000000" } ], "value": "25000.75", "total_pnl": "5100.50" } ], "quote_symbol": "USD", "quote_type": "fiat", "start_timestamp": "2025-01-01T00:00:00Z", "end_timestamp": "2025-12-31T00:00:00Z" } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/portfolio-bad-request" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/portfolio-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/portfolio-forbidden" } } } } }, "404": { "description": "Not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/portfolio-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/portfolio-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/portfolio-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/portfolio-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/portfolio-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/portfolio-deadline-exceeded" } } } } } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List portfolio history" } }, "/v1/accounts/{account_id}/portfolio/transactions": { "get": { "tags": [ "Portfolio" ], "description": "Lists account portfolio transactions with optional filters for type, asset, status, transaction ID, originating reference, time range, and sort direction. Results are cursor-paginated. Results are ordered newest first by default; set `sort_direction=asc` for oldest first. Page tokens are valid for up to 24 hours. A page can contain fewer than `page_size` matching transactions, including no transactions, while still returning `next_page_token`; continue until the token is absent.\n\nTransactions can appear asynchronously. To discover new activity, poll this operation with the applicable `types` filters and an appropriate time range, omitting `statuses` or including `in_progress` while a transaction is being processed. For a transfer created by `POST /v1/transfers`, use `types=transfer` and the `from` account from the create request. For an accepted derivatives transfer created by `POST /v1/accounts/{account_id}/transfers/derivatives`, use `types=transfer` and the `account_id` from the request path. The `transfer_id` returned by either create operation is the `id` in a `reference` with `kind=transfer`. Once the transaction appears, that reference can be submitted in `references` for deterministic subsequent lookup. A transfer may appear with `status=in_progress` before it reaches the terminal `successful` or `failed` status; filtering only by `successful` can therefore hide a newly materialized transfer. The first Portfolio response after a transfer is created may contain no matching transaction even when a generic transfer has `status=complete` or a derivatives transfer has `status=accepted`; continue polling until the transaction is present.\n\nFor deposits and withdrawals, `reference.kind=funding` identifies the originating funding transaction. For deposits, it is not the deposit destination or a payment reference from bank-transfer instructions; those values describe how to make the payment and are not accepted by `references`. For withdrawals, use `types=withdrawal` and, when the originating funding identifier is known, submit it in `references` as the `id` with `kind=funding`. Poll with `statuses` omitted until the withdrawal appears, then continue polling without that filter until its status is terminal: `successful` or `failed`. Filtering only by `in_progress` is useful for discovering pending withdrawals, but it excludes terminal results and must be removed or changed before polling for completion. Once a funding transaction appears, its reference can be used for deterministic subsequent lookup. The returned Portfolio transaction `id` uses the `TX` namespace and is distinct from the funding identifier in `reference.id`.\n\nSuccessful `swap`, `recurring_swap`, and `price_trigger_swap` transactions include the executed quote identifier in `details.quote_id`. Failed swap attempts are returned with `status=failed` and include a type-specific `details.failure_reason`.", "operationId": "listPortfolioTransactions", "parameters": [ { "$ref": "#/components/parameters/PageToken" }, { "in": "query", "name": "types", "schema": { "description": "Filter by transaction type.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_TransactionType" } }, "style": "form", "example": [ "swap", "price_trigger_swap", "withdrawal", "transfer" ] }, { "$ref": "#/components/parameters/Portfolio_PageSize" }, { "in": "query", "name": "assets", "schema": { "description": "Filter transactions by specific assets.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_AssetFilter" } }, "style": "form", "example": [ { "symbol": "BTC", "type": "crypto" } ] }, { "in": "query", "name": "start_timestamp", "description": "Lower bound of the transaction timestamp filter.", "schema": { "$ref": "#/components/schemas/DateTime" }, "style": "form", "example": "2025-01-01T00:00:00Z" }, { "in": "query", "name": "end_timestamp", "description": "Upper bound of the transaction timestamp filter.", "schema": { "$ref": "#/components/schemas/DateTime" }, "style": "form", "example": "2025-12-31T23:59:59Z" }, { "in": "query", "name": "statuses", "schema": { "description": "Filter transactions by lifecycle status. When polling a newly created transfer or withdrawal through completion, omit this filter or provide an empty array so both `in_progress` and the terminal `successful` or `failed` status can be observed. Filtering only by `in_progress` discovers pending transactions but excludes terminal results; remove or change that filter before polling for completion.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_TransactionStatusFilter" } }, "style": "form", "example": [ "successful" ] }, { "in": "query", "name": "ids", "schema": { "description": "Filter transactions by specific transaction IDs.", "type": "array", "items": { "type": "string" } }, "style": "form", "example": [ "TX-2025-0001" ] }, { "in": "query", "name": "sort_direction", "schema": { "$ref": "#/components/schemas/Portfolio_SortDirection" }, "style": "form", "example": "desc" }, { "in": "query", "name": "quote_symbol", "schema": { "description": "Asset in which amounts and fees are quoted. Each `amount_in_quote` uses the rate at that transaction's time and is absent when no rate is available. Required when `quote_type` is `stablecoin`. The `USD` default applies only when `quote_type` is omitted or `fiat`.", "$ref": "#/components/schemas/AssetSymbol", "default": "USD" }, "style": "form", "example": "USD" }, { "in": "query", "name": "quote_type", "schema": { "$ref": "#/components/schemas/Portfolio_QuoteAssetType" }, "description": "Quote asset classification. Supports fiat and stablecoin.", "style": "form", "example": "fiat" }, { "in": "query", "name": "references", "schema": { "description": "Filter by originating references. Entries are ORed together and combined with `types` and other filters using AND semantics. Reference kind selects the originating system namespace. For a deposit or withdrawal, use `kind=funding` and the originating funding identifier. For a transfer, use `kind=transfer` and the `transfer_id` returned by `POST /v1/transfers` or an accepted `POST /v1/accounts/{account_id}/transfers/derivatives` request. Reference identifiers are distinct from the `TX` identifiers accepted by `ids`.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_TransactionReference" } }, "style": "form", "examples": { "funding-reference": { "summary": "Originating Funding reference", "value": [ { "kind": "funding", "id": "FTSBuuG-9BctU4m3Emt88submmZVKY" } ] }, "transfer-reference": { "summary": "Originating Transfer reference", "value": [ { "kind": "transfer", "id": "TRYCMN7-WXKJM-F47YIM" } ] } } }, { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "List of portfolio transactions matching the query parameters. Always present; serialized as an empty array when no transactions match.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_Transaction" } }, "quote_symbol": { "description": "Quote asset for every `amount_in_quote` value in this response.", "type": "string" }, "quote_type": { "$ref": "#/components/schemas/Portfolio_QuoteAssetType" }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data", "quote_symbol", "quote_type" ] }, "examples": { "first-page-btc-buy": { "summary": "First page with a single BTC buy", "value": { "data": [ { "id": "TX-2025-0001", "timestamp": "2025-09-12T14:23:11Z", "type": "swap", "status": "successful", "spend": { "sub_total": { "symbol": "USD", "amount": "5000.00", "type": "fiat", "name": "US Dollar", "amount_in_quote": "5000.00" }, "total": { "symbol": "USD", "amount": "5025.00", "type": "fiat", "name": "US Dollar", "amount_in_quote": "5025.00" }, "timestamp": "2025-09-12T14:23:11Z", "fee": { "symbol": "USD", "amount": "25.00", "type": "fiat", "name": "US Dollar", "amount_in_quote": "25.00" }, "balance": { "symbol": "USD", "amount": "4975.00", "type": "fiat", "name": "US Dollar", "amount_in_quote": "4975.00" } }, "receive": { "sub_total": { "symbol": "BTC", "amount": "0.08064516", "type": "crypto", "name": "Bitcoin", "amount_in_quote": "5000.00" }, "total": { "symbol": "BTC", "amount": "0.08064516", "type": "crypto", "name": "Bitcoin", "amount_in_quote": "5000.00" }, "timestamp": "2025-09-12T14:23:11Z", "balance": { "symbol": "BTC", "amount": "0.58064516", "type": "crypto", "name": "Bitcoin", "amount_in_quote": "35990.00" } }, "details": { "type": "swap", "quote_id": "Q-2025-0001" } } ], "quote_symbol": "USD", "quote_type": "fiat", "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } }, "failed-swap": { "summary": "Failed standard swap", "value": { "data": [ { "id": "TX-2025-0002", "timestamp": "2025-09-12T14:24:11Z", "type": "swap", "status": "failed", "details": { "type": "failed_swap", "failure_reason": "insufficient_funds" } } ], "quote_symbol": "USD", "quote_type": "fiat" } }, "successful-price-trigger-swap": { "summary": "Successful price-triggered swap", "value": { "data": [ { "id": "TX-2025-0003", "timestamp": "2025-09-12T14:25:11Z", "type": "price_trigger_swap", "status": "successful", "details": { "type": "price_trigger_swap", "quote_id": "Q-2025-0003" } } ], "quote_symbol": "USD", "quote_type": "fiat" } }, "failed-price-trigger-swap": { "summary": "Failed price-triggered swap", "value": { "data": [ { "id": "TX-2025-0004", "timestamp": "2025-09-12T14:26:11Z", "type": "price_trigger_swap", "status": "failed", "details": { "type": "failed_price_trigger_swap", "failure_reason": "card_issue" } } ], "quote_symbol": "USD", "quote_type": "fiat" } }, "received-deposit": { "summary": "Received crypto deposit", "value": { "data": [ { "id": "TXYMPOO-MRYLI-54G4MY", "timestamp": "2026-07-13T10:15:30Z", "type": "deposit", "status": "successful", "receive": { "sub_total": { "symbol": "BTC", "amount": "1.00", "type": "crypto", "name": "Bitcoin", "amount_in_quote": "62000.00" }, "total": { "symbol": "BTC", "amount": "1.00", "type": "crypto", "name": "Bitcoin", "amount_in_quote": "62000.00" }, "timestamp": "2026-07-13T10:15:30Z" }, "reference": { "kind": "funding", "id": "FTSBuuG-9BctU4m3Emt88submmZVKY" }, "details": { "type": "funding", "crypto_transaction_id": "0xabc123def4567890", "vout": 7 } } ], "quote_symbol": "USD", "quote_type": "fiat" } }, "processing-fiat-deposit": { "summary": "Fiat bank deposit still processing", "value": { "data": [ { "id": "TXFIATD-H4K2N-Q7M9PL", "timestamp": "2026-08-17T09:15:30Z", "type": "deposit", "status": "in_progress", "receive": { "sub_total": { "symbol": "USD", "amount": "1000.00", "type": "fiat", "amount_in_quote": "1000.00" }, "total": { "symbol": "USD", "amount": "997.50", "type": "fiat", "amount_in_quote": "997.50" }, "timestamp": "2026-08-17T09:15:30Z", "fee": { "symbol": "USD", "amount": "2.50", "type": "fiat", "amount_in_quote": "2.50" } }, "reference": { "kind": "funding", "id": "FTf7QpL-4nB2xM8vK5dR9sT3wY6zA1" }, "details": { "type": "funding", "vendor_transaction_id": "4f3c2a1908e7d6c5b4a39281706f5e4d3c2b1a0987654321fedcba9876543210" } } ], "quote_symbol": "USD", "quote_type": "fiat" } }, "processing-withdrawal": { "summary": "Crypto withdrawal awaiting settlement", "value": { "data": [ { "id": "TXWDRWL-H4K2N-Q7M9PL", "timestamp": "2026-08-20T09:15:30Z", "type": "withdrawal", "status": "in_progress", "spend": { "sub_total": { "symbol": "BTC", "amount": "0.01000000", "type": "crypto", "amount_in_quote": "620.00" }, "total": { "symbol": "BTC", "amount": "0.01010000", "type": "crypto", "amount_in_quote": "626.20" }, "timestamp": "2026-08-20T09:15:30Z", "fee": { "symbol": "BTC", "amount": "0.00010000", "type": "crypto", "amount_in_quote": "6.20" } }, "reference": { "kind": "funding", "id": "FTw8RkN-6pC3yM9vL2dS5tU7xZ4aB1" }, "details": { "type": "funding" } } ], "quote_symbol": "USD", "quote_type": "fiat" } }, "processing-fiat-withdrawal": { "summary": "Fiat withdrawal awaiting completion", "value": { "data": [ { "id": "TXFIATW-H4K2N-Q7M9PL", "timestamp": "2026-09-22T09:15:30Z", "type": "withdrawal", "status": "in_progress", "spend": { "sub_total": { "symbol": "EUR", "amount": "10.00", "type": "fiat" }, "total": { "symbol": "EUR", "amount": "10.25", "type": "fiat" }, "fee": { "symbol": "EUR", "amount": "0.25", "type": "fiat" } }, "reference": { "kind": "funding", "id": "FTEURia-4nB2xM8vK5dR9sT3wY6zA1" }, "details": { "type": "funding" } } ], "quote_symbol": "USD", "quote_type": "fiat" } }, "created-transfer": { "summary": "Created transfer still in progress", "value": { "data": [ { "id": "TXYCMN8-ABCD2-EFGH3I", "timestamp": "2026-07-23T10:15:30Z", "type": "transfer", "status": "in_progress", "spend": { "sub_total": { "symbol": "USD", "amount": "25.50", "type": "fiat", "name": "US Dollar", "amount_in_quote": "25.50" }, "total": { "symbol": "USD", "amount": "25.50", "type": "fiat", "name": "US Dollar", "amount_in_quote": "25.50" }, "timestamp": "2026-07-23T10:15:30Z" }, "receive": { "sub_total": { "symbol": "USD", "amount": "25.50", "type": "fiat", "name": "US Dollar", "amount_in_quote": "25.50" }, "total": { "symbol": "USD", "amount": "25.50", "type": "fiat", "name": "US Dollar", "amount_in_quote": "25.50" }, "timestamp": "2026-07-23T10:15:30Z" }, "reference": { "kind": "transfer", "id": "TRYCMN7-WXKJM-F47YIM" } } ], "quote_symbol": "USD", "quote_type": "fiat" } } } } } }, "400": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/portfolio-bad-request" }, "invalid-reference": { "$ref": "#/components/examples/portfolio-invalid-reference" } } } } }, "401": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/portfolio-unauthenticated" } } } } }, "403": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/portfolio-forbidden" } } } } }, "404": { "description": "Not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/portfolio-not-found" } } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/portfolio-resource-exhausted" } } } } }, "500": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/portfolio-internal" } } } } }, "501": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "not-implemented": { "$ref": "#/components/examples/portfolio-unimplemented" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/portfolio-unavailable" } } } } }, "504": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/portfolio-deadline-exceeded" } } } } } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List portfolio transactions" } }, "/v1/accounts/{account_id}/funds/bank-links": { "get": { "tags": [ "Ramp" ], "description": "Lists an account's materialized Bank Links with their nested active Account Links, ordered by link time descending. Links that are still being completed are not returned. Results are paged: follow `next_page_token` until it is absent. Eligibility is computed fresh on every read, so a link's rails and verdict can change between pages.", "operationId": "listBankLinks", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "example": 20 }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Bank Links for the account, ordered by link time descending.", "type": "array", "items": { "description": "A provider-neutral linking operation and persistent bank connection.", "$ref": "#/components/schemas/Ramp_BankLink" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "examples": { "page-of-bank-links": { "summary": "One page of Bank Links, with more to fetch", "value": { "data": [ { "bank_link_id": "bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "method_id": "3f9a1c2e-8b7d-4e6f-9a1b-2c3d4e5f6a7b", "status": "linked", "institution": { "name": "Pacific Trust Bank" }, "account_links": [ { "account_link_id": "al_7c2b8d19-4e35-4a71-b0c6-1d8f5e9a2b34", "account_last4": "4242", "status": "active", "eligible_rails": [ "ach", "rtp", "rfp" ], "rail_limits": { "rfp": { "max_daily_amount": "15000" } }, "eligibility_status": "eligible" } ], "accounts_eligibility_status": "eligible" } ], "next_page_token": "AY7dRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } }, "no-bank-links": { "summary": "Account with no Bank Links", "value": { "data": [] } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List bank links" }, "post": { "tags": [ "Ramp" ], "description": "Creates a Bank Link for a funding method that requires linking. Returns it in `pending` with a hosted-widget URL to complete it. `method_id` must be one this account can currently use. Use `GET /v1/accounts/{account_id}/funds/deposits/methods?asset_symbol={asset_symbol}` to discover them. Any other value is rejected with `bank_link_method_not_linkable` rather than creating a link that cannot complete. Provider identifiers, access tokens, owner names and raw bank numbers are never returned: the link and its accounts are referenced only by `bank_link_id` and `account_link_id`.", "operationId": "createBankLink", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method_id": { "description": "Funding method to link. Use a method ID, never a name. Use `GET /v1/accounts/{account_id}/funds/deposits/methods?asset_symbol={asset_symbol}` to discover the methods available to this account.", "type": "string", "minLength": 1, "maxLength": 64 }, "return_url": { "description": "Optional partner URL to return the user to after the hosted widget completes. When supplied it must be an absolute `https` URL without userinfo; other values are rejected.", "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048 }, "external_reference": { "description": "Optional partner correlation value.", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "method_id" ] }, "examples": { "create-bank-link": { "summary": "Create a Bank Link", "value": { "method_id": "3f9a1c2e-8b7d-4e6f-9a1b-2c3d4e5f6a7b", "return_url": "https://partner.example.com/bank-link/return", "external_reference": "order-abc-123" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The Bank Link, in `pending` with a `next_action`.", "$ref": "#/components/schemas/Ramp_BankLink" } }, "required": [ "data" ] }, "examples": { "pending-link": { "summary": "Pending link with hosted-widget URL", "value": { "data": { "bank_link_id": "bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "method_id": "3f9a1c2e-8b7d-4e6f-9a1b-2c3d4e5f6a7b", "status": "pending", "next_action": { "type": "hosted_link", "widget_url": "https://bank-link.services.payward.com/link/bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "expires_at": "2026-07-02T16:00:00Z" }, "accounts_eligibility_status": "unknown" } } } } } } }, "400": { "$ref": "#/components/responses/RampBankLinkMethodNotLinkableBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "404": { "$ref": "#/components/responses/RampNotFoundResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Create bank link" } }, "/v1/ramp/buy/crypto": { "get": { "tags": [ "Ramp" ], "description": "List cryptocurrency assets supported for Ramp buy transactions, including networks and withdrawal methods.", "operationId": "getRampBuyCryptoAssets", "parameters": [ { "in": "query", "name": "country", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "style": "form", "description": "ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values.", "example": "US", "required": true }, { "in": "query", "name": "subdivision", "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "ISO 3166-2 subdivision code suffix (e.g., `CA` for California when country is `US`). Use `GET /v1/ramp/countries` to discover supported values.", "example": "CA" }, { "$ref": "#/components/parameters/PageToken" }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 200, "default": 20 }, "style": "form", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "example": 20 } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Supported cryptocurrency assets for Ramp buy operations.", "type": "array", "items": { "description": "Cryptocurrency asset metadata for Ramp buy operations.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset (e.g., \"BTC\", \"ETH\", \"SOL\").", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "description": "Classification of the asset.", "type": "string", "enum": [ "crypto", "stablecoin" ], "title": "RampBuyCryptoAssetType" }, "wrapped_asset": { "description": "Optional wrapped-asset code for the asset (e.g., \"WSOL\" for wrapped Solana).", "$ref": "#/components/schemas/AssetSymbol" }, "market_cap_rank": { "description": "Asset's ranking based on market capitalization (lower number = higher rank).", "type": "integer", "format": "int32", "minimum": 0 }, "network": { "description": "Withdrawal network label for the asset (e.g., \"Lightning\", \"Bitcoin\", \"Ethereum\").", "type": "string", "minLength": 1, "maxLength": 128 }, "method": { "description": "Unique name for the withdrawal method.", "type": "string", "minLength": 1, "maxLength": 128 }, "disabled_against": { "description": "List of fiat assets that cannot be paired with this cryptocurrency asset.", "type": "array", "items": { "description": "Reference to an asset by its ticker symbol and classification.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"BTC\", \"USD\", \"TSLAx\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "stablecoin" ], "title": "RampAssetReferenceType" } }, "title": "RampAssetReference", "required": [ "symbol", "type" ] } } }, "title": "RampBuyCryptoAsset", "required": [ "symbol", "name", "type", "market_cap_rank", "network", "method" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "buy-crypto-assets": { "summary": "Supported buy crypto assets", "value": { "data": [ { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "market_cap_rank": 1, "network": "Bitcoin", "method": "Bitcoin", "disabled_against": [] }, { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "wrapped_asset": "kBTC", "market_cap_rank": 1, "network": "Ink", "method": "kBTC - Ink", "disabled_against": [] }, { "symbol": "ETH", "name": "Ethereum", "type": "crypto", "market_cap_rank": 2, "network": "Ethereum", "method": "Ether", "disabled_against": [] }, { "symbol": "USDC", "name": "USD Coin", "type": "stablecoin", "market_cap_rank": 6, "network": "Ethereum", "method": "USDC", "disabled_against": [ { "symbol": "GBP", "type": "fiat" } ] } ], "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List Ramp buy cryptocurrency assets" } }, "/v1/ramp/checkout": { "get": { "tags": [ "Ramp" ], "description": "Generate a hosted Ramp checkout URL for the provided transaction configuration. The response echoes the request parameters so the Ramp partner can confirm what was submitted.", "operationId": "getRampCheckout", "parameters": [ { "in": "query", "name": "from_symbol", "schema": { "$ref": "#/components/schemas/AssetSymbol" }, "style": "form", "description": "Source asset ticker symbol (e.g., \"USD\"). Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies.", "example": "USD", "required": true }, { "in": "query", "name": "from_type", "schema": { "$ref": "#/components/schemas/Ramp_SourceAssetType" }, "style": "form", "description": "Classification of the source asset. Pair with `from_symbol` to disambiguate when the same ticker exists across asset classes (e.g., `USDC` as `stablecoin` vs `crypto`). Only fiat sources are currently supported (on-ramp).", "example": "fiat" }, { "in": "query", "name": "from_method", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "style": "form", "description": "Funding method used for the source side. Use `GET /v1/ramp/payment-methods` to discover supported payment methods.", "example": "credit_card", "required": true }, { "in": "query", "name": "from_amount", "schema": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "Amount to spend, denominated in the source asset, as a decimal string.", "example": "100.00", "required": true }, { "in": "query", "name": "to_symbol", "schema": { "$ref": "#/components/schemas/AssetSymbol" }, "style": "form", "description": "Destination asset ticker symbol (e.g., \"BTC\"). Use `GET /v1/ramp/buy/crypto` to discover supported destination assets.", "example": "BTC", "required": true }, { "in": "query", "name": "to_type", "schema": { "$ref": "#/components/schemas/Ramp_DestinationAssetType" }, "style": "form", "description": "Classification of the destination asset. Pair with `to_symbol` to disambiguate when the same ticker exists across asset classes (e.g., `USDC` as `stablecoin` vs `crypto`). Only crypto and stablecoin destinations are currently supported (on-ramp).", "example": "crypto" }, { "in": "query", "name": "to_method", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "style": "form", "description": "Withdrawal method for the destination asset. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset.", "example": "Bitcoin", "required": true }, { "in": "query", "name": "to_network", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "style": "form", "description": "Optional withdrawal network identifier. Use `GET /v1/ramp/buy/crypto` to discover available networks for each destination asset.", "example": "Bitcoin" }, { "in": "query", "name": "to_address", "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "style": "form", "description": "Optional destination wallet address for the crypto withdrawal.", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" }, { "in": "query", "name": "to_memo", "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "style": "form", "description": "Optional memo/tag/note for the crypto withdrawal (used for certain assets).", "example": "123456" }, { "in": "query", "name": "affiliate_fee_bps", "schema": { "type": "string", "pattern": "^(10000|[0-9]{1,4})$", "minLength": 1, "maxLength": 5 }, "style": "form", "description": "Affiliate fee in basis points to attribute to the partner (0-10000 where 100 = 1%). This fee is additive to the platform fee, increasing the total fee charged to the user. The affiliate_fee in webhook payloads reflects the partner's portion of the total fee for transactions originating from this checkout.", "example": "250" }, { "in": "query", "name": "country", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "style": "form", "description": "ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values.", "example": "US", "required": true }, { "in": "query", "name": "subdivision", "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "ISO 3166-2 subdivision code suffix (e.g., `CA` for California when country is `US`). Use `GET /v1/ramp/countries` to discover supported values.", "example": "CA" }, { "in": "query", "name": "redirect_url", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "style": "form", "description": "URL to redirect the user after completing checkout successfully.", "example": "https://example.com/checkout/success" }, { "in": "query", "name": "failure_url", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "style": "form", "description": "URL to redirect the user after a failed checkout.", "example": "https://example.com/checkout/failure" }, { "in": "query", "name": "external_user_id", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "Optional partner-supplied user identifier.", "example": "user_123" }, { "in": "query", "name": "external_partner_id", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "Optional partner-supplied partner identifier.", "example": "partner_456" }, { "in": "query", "name": "external_transaction_id", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "Optional partner transaction identifier.", "example": "txn_789" }, { "in": "query", "name": "external_metadata", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "style": "form", "description": "Optional metadata to store alongside the checkout.", "example": "campaign=spring" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Checkout details for the requested Ramp route.", "type": "object", "properties": { "checkout_url": { "description": "Hosted checkout URL.", "type": "string", "minLength": 1, "maxLength": 2048 }, "request_data": { "description": "Original request payload for client confirmation.", "type": "object", "properties": { "from": { "description": "Echo of the source (pay) side of the checkout.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"USD\"). Required. Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Ramp_SourceAssetType" }, "method": { "description": "Funding method used for the source side. Required. Use `GET /v1/ramp/payment-methods` to discover supported payment methods.", "type": "string", "minLength": 1, "maxLength": 128 }, "amount": { "description": "Amount to spend, denominated in the source asset, as a decimal string. Required.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "minLength": 1, "maxLength": 64 } }, "title": "RampCheckoutFrom", "required": [ "symbol", "method", "amount" ] }, "to": { "description": "Echo of the destination (receive) side of the checkout.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"BTC\"). Required. Use `GET /v1/ramp/buy/crypto` to discover supported destination assets.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Ramp_DestinationAssetType" }, "method": { "description": "Withdrawal method for the destination asset. Required. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset.", "type": "string", "minLength": 1, "maxLength": 128 }, "network": { "description": "Optional withdrawal network identifier. Use `GET /v1/ramp/buy/crypto` to discover available networks for each destination asset.", "type": "string", "minLength": 1, "maxLength": 128 }, "address": { "description": "Optional destination wallet address for the crypto withdrawal.", "type": "string", "minLength": 1, "maxLength": 512 }, "memo": { "description": "Optional memo/tag/note for the crypto withdrawal (used for certain assets).", "type": "string", "minLength": 1, "maxLength": 256 } }, "title": "RampCheckoutTo", "required": [ "symbol", "method" ] }, "affiliate_fee_bps": { "description": "Affiliate fee in basis points (0-10000 where 100 = 1%).", "type": "string", "pattern": "^(10000|[0-9]{1,4})$", "minLength": 1, "maxLength": 5 }, "country": { "description": "ISO 3166-1 alpha-2 country code", "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "subdivision": { "description": "ISO 3166-2 subdivision code suffix (e.g., CA for California when country is US)", "type": "string", "pattern": "^[A-Za-z0-9-]+$", "minLength": 1, "maxLength": 64 }, "redirect_url": { "description": "URL where the ramp provider should redirect the user after successful checkout", "type": "string", "minLength": 1, "maxLength": 255 }, "failure_url": { "description": "URL where the ramp provider should redirect the user after failed checkout", "type": "string", "minLength": 1, "maxLength": 255 }, "external_user_id": { "description": "Partner-provided user identifier (max 64 characters)", "type": "string", "minLength": 1, "maxLength": 64 }, "external_partner_id": { "description": "Partner-provided partner identifier (max 64 characters)", "type": "string", "minLength": 1, "maxLength": 64 }, "external_transaction_id": { "description": "Partner-provided transaction identifier (max 64 characters)", "type": "string", "minLength": 1, "maxLength": 64 }, "external_metadata": { "description": "Additional partner-provided metadata (max 1000 characters)", "type": "string", "minLength": 1, "maxLength": 1000 } }, "title": "RampCheckoutRequestData", "required": [ "country" ] } }, "title": "RampCheckoutData", "required": [ "checkout_url" ] } }, "required": [ "data" ] }, "examples": { "checkout": { "summary": "Hosted checkout URL", "value": { "data": { "checkout_url": "https://checkout.ramp.network/?session=checkout-123", "request_data": { "from": { "symbol": "USD", "type": "fiat", "method": "credit_card", "amount": "100.00" }, "to": { "symbol": "BTC", "type": "crypto", "method": "Bitcoin", "network": "Bitcoin", "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", "memo": "123456" }, "affiliate_fee_bps": "250", "country": "US", "subdivision": "CA", "redirect_url": "https://example.com/checkout/success", "failure_url": "https://example.com/checkout/failure", "external_user_id": "user_01J0M7C0Z9F8YX3GQH8E", "external_transaction_id": "INV-2026-04-0042", "external_metadata": "{\"order_id\":\"order_12345\"}" } } } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get Ramp checkout URL" } }, "/v1/ramp/countries": { "get": { "tags": [ "Ramp" ], "description": "List countries and subdivision groups supported for Ramp deposits.", "operationId": "getRampCountries", "parameters": [ { "$ref": "#/components/parameters/PageToken" }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "example": 20 } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Countries and sub-regions that support Ramp transactions.", "type": "array", "items": { "description": "Supported Ramp country entry.", "type": "object", "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code.", "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2 }, "subdivisions": { "description": "ISO 3166-2 subdivision suffixes for countries that support a subdivision parameter, such as US states, Canadian provinces, or Ukrainian regions.", "type": "array", "items": { "type": "string" } } }, "title": "RampCountry", "required": [ "country" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "countries": { "summary": "Supported countries", "value": { "data": [ { "country": "GB" }, { "country": "DE" }, { "country": "US", "subdivisions": [ "CA", "NY", "TX", "FL", "WA" ] }, { "country": "CA", "subdivisions": [ "ON", "BC", "QC" ] } ], "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List Ramp countries" } }, "/v1/ramp/fiat-currencies": { "get": { "tags": [ "Ramp" ], "description": "List fiat currencies supported for funding Ramp transactions.", "operationId": "getRampFiatCurrencies", "parameters": [ { "in": "query", "name": "country", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "style": "form", "description": "ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values.", "example": "US", "required": true }, { "in": "query", "name": "subdivision", "schema": { "type": "string" }, "style": "form", "description": "ISO 3166-2 subdivision code suffix (e.g., `CA` for California when country is `US`). Use `GET /v1/ramp/countries` to discover supported values.", "example": "CA" }, { "$ref": "#/components/parameters/PageToken" }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "example": 20 } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Fiat currencies that can be used for Ramp deposits.", "type": "array", "items": { "description": "Fiat currency metadata for Ramp deposits.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset using ISO 4217 currency codes (e.g., \"USD\", \"EUR\", \"GBP\").", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"US Dollar\" for USD).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto" ], "title": "CurrencyAssetType" } }, "title": "RampFiatCurrency", "required": [ "symbol", "name", "type" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "fiat-currencies": { "summary": "Supported fiat currencies", "value": { "data": [ { "symbol": "USD", "name": "US Dollar", "type": "fiat" }, { "symbol": "EUR", "name": "Euro", "type": "fiat" }, { "symbol": "GBP", "name": "British Pound", "type": "fiat" }, { "symbol": "CAD", "name": "Canadian Dollar", "type": "fiat" } ], "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List Ramp fiat currencies" } }, "/v1/ramp/limits": { "get": { "tags": [ "Ramp" ], "description": "Retrieve combined min/max limits for a Ramp transaction configuration.", "operationId": "getRampLimits", "parameters": [ { "in": "query", "name": "from_symbol", "schema": { "$ref": "#/components/schemas/AssetSymbol" }, "style": "form", "description": "Source asset ticker symbol (e.g., \"USD\"). Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies.", "example": "USD", "required": true }, { "in": "query", "name": "from_type", "schema": { "$ref": "#/components/schemas/Ramp_SourceAssetType" }, "style": "form", "description": "Classification of the source asset. Pair with `from_symbol` to disambiguate when the same ticker exists across asset classes (e.g., `USDC` as `stablecoin` vs `crypto`). Only fiat sources are currently supported (on-ramp).", "example": "fiat" }, { "in": "query", "name": "from_method", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "style": "form", "description": "Funding method used for the source side. Use `GET /v1/ramp/payment-methods` to discover supported payment methods.", "example": "credit_card", "required": true }, { "in": "query", "name": "to_symbol", "schema": { "$ref": "#/components/schemas/AssetSymbol" }, "style": "form", "description": "Destination asset ticker symbol (e.g., \"BTC\"). Use `GET /v1/ramp/buy/crypto` to discover supported destination assets.", "example": "BTC", "required": true }, { "in": "query", "name": "to_type", "schema": { "$ref": "#/components/schemas/Ramp_DestinationAssetType" }, "style": "form", "description": "Classification of the destination asset. Pair with `to_symbol` to disambiguate when the same ticker exists across asset classes (e.g., `USDC` as `stablecoin` vs `crypto`). Only crypto and stablecoin destinations are currently supported (on-ramp).", "example": "crypto" }, { "in": "query", "name": "to_method", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "style": "form", "description": "Withdrawal method for the destination asset. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset.", "example": "Bitcoin", "required": true }, { "in": "query", "name": "country", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "style": "form", "description": "ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values.", "example": "US", "required": true }, { "in": "query", "name": "subdivision", "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "ISO 3166-2 subdivision code suffix (e.g., `CA` for California when country is `US`). Use `GET /v1/ramp/countries` to discover supported values.", "example": "CA" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Effective limits for the requested Ramp route.", "type": "object", "properties": { "limits": { "description": "Transaction limits for the source and destination sides.", "type": "object", "properties": { "from": { "description": "Min/max transaction range for the source (pay) side, expressed in asset amount.", "type": "object", "properties": { "minimum": { "description": "Money-like value: an amount denominated in a specific asset. Used across Ramp endpoints for limits, breakdowns, and prices.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/components/schemas/Ramp_LimitAssetType" }, "amount": { "description": "Decimal amount string as returned by the limits provider.", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampLimitAmount", "required": [ "symbol", "name", "type", "amount" ] }, "maximum": { "description": "Money-like value: an amount denominated in a specific asset. Used across Ramp endpoints for limits, breakdowns, and prices.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/components/schemas/Ramp_LimitAssetType" }, "amount": { "description": "Decimal amount string as returned by the limits provider.", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampLimitAmount", "required": [ "symbol", "name", "type", "amount" ] } }, "title": "RampTransactionRange" }, "to": { "description": "Min/max transaction range for the destination (receive) side, expressed in asset amount.", "type": "object", "properties": { "minimum": { "description": "Money-like value: an amount denominated in a specific asset. Used across Ramp endpoints for limits, breakdowns, and prices.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/components/schemas/Ramp_LimitAssetType" }, "amount": { "description": "Decimal amount string as returned by the limits provider.", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampLimitAmount", "required": [ "symbol", "name", "type", "amount" ] }, "maximum": { "description": "Money-like value: an amount denominated in a specific asset. Used across Ramp endpoints for limits, breakdowns, and prices.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/components/schemas/Ramp_LimitAssetType" }, "amount": { "description": "Decimal amount string as returned by the limits provider.", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampLimitAmount", "required": [ "symbol", "name", "type", "amount" ] } }, "title": "RampTransactionRange" } }, "title": "RampLimits" }, "final_combined": { "description": "Combined limits converted to both source and destination assets.", "type": "object", "properties": { "from": { "description": "Min/max transaction range denominated in the source asset.", "type": "object", "properties": { "minimum": { "description": "Money-like value: an amount denominated in a specific asset. Used across Ramp endpoints for limits, breakdowns, and prices.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/components/schemas/Ramp_LimitAssetType" }, "amount": { "description": "Decimal amount string as returned by the limits provider.", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampLimitAmount", "required": [ "symbol", "name", "type", "amount" ] }, "maximum": { "description": "Money-like value: an amount denominated in a specific asset. Used across Ramp endpoints for limits, breakdowns, and prices.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/components/schemas/Ramp_LimitAssetType" }, "amount": { "description": "Decimal amount string as returned by the limits provider.", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampLimitAmount", "required": [ "symbol", "name", "type", "amount" ] } }, "title": "RampTransactionRange" }, "to": { "description": "Min/max transaction range denominated in the destination asset.", "type": "object", "properties": { "minimum": { "description": "Money-like value: an amount denominated in a specific asset. Used across Ramp endpoints for limits, breakdowns, and prices.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/components/schemas/Ramp_LimitAssetType" }, "amount": { "description": "Decimal amount string as returned by the limits provider.", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampLimitAmount", "required": [ "symbol", "name", "type", "amount" ] }, "maximum": { "description": "Money-like value: an amount denominated in a specific asset. Used across Ramp endpoints for limits, breakdowns, and prices.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol of the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\" for BTC).", "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/components/schemas/Ramp_LimitAssetType" }, "amount": { "description": "Decimal amount string as returned by the limits provider.", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampLimitAmount", "required": [ "symbol", "name", "type", "amount" ] } }, "title": "RampTransactionRange" } }, "title": "RampFinalCombinedLimits" } }, "title": "RampLimitsData" } }, "required": [ "data" ] }, "examples": { "limits": { "summary": "Transaction limits", "value": { "data": { "limits": { "from": { "minimum": { "symbol": "USD", "name": "US Dollar", "type": "fiat", "amount": "20.00" }, "maximum": { "symbol": "USD", "name": "US Dollar", "type": "fiat", "amount": "5000.00" } }, "to": { "minimum": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.00010000" }, "maximum": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.50000000" } } }, "final_combined": { "from": { "minimum": { "symbol": "USD", "name": "US Dollar", "type": "fiat", "amount": "20.00" }, "maximum": { "symbol": "USD", "name": "US Dollar", "type": "fiat", "amount": "5000.00" } }, "to": { "minimum": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.00031746" }, "maximum": { "symbol": "BTC", "name": "Bitcoin", "type": "crypto", "amount": "0.07936507" } } } } } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get Ramp limits" } }, "/v1/ramp/payment-methods": { "get": { "tags": [ "Ramp" ], "description": "List fiat funding methods supported for Ramp deposits.", "operationId": "getRampPaymentMethods", "parameters": [ { "in": "query", "name": "country", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "style": "form", "description": "ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values.", "example": "US", "required": true }, { "in": "query", "name": "subdivision", "schema": { "type": "string" }, "style": "form", "description": "ISO 3166-2 subdivision code suffix (e.g., `CA` for California when country is `US`). Use `GET /v1/ramp/countries` to discover supported values.", "example": "CA" }, { "$ref": "#/components/parameters/PageToken" }, { "in": "query", "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "example": 20 } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Supported funding methods for Ramp operations.", "type": "array", "items": { "description": "Supported Ramp payment method.", "type": "object", "properties": { "method": { "description": "Unique payment-method name.", "type": "string" } }, "title": "RampPaymentMethod", "required": [ "method" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "payment-methods": { "summary": "Supported payment methods", "value": { "data": [ { "method": "credit_card" }, { "method": "fps" }, { "method": "sepa" } ], "next_page_token": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List Ramp payment methods" } }, "/v1/ramp/quotes/prospective": { "get": { "tags": [ "Ramp" ], "description": "Retrieve a prospective quote for a Ramp transaction without reserving liquidity. Use this to preview the from/to amounts before creating a checkout URL.", "operationId": "getRampProspectiveQuote", "parameters": [ { "in": "query", "name": "from_symbol", "schema": { "$ref": "#/components/schemas/AssetSymbol" }, "style": "form", "description": "Source asset ticker symbol (e.g., \"USD\"). Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies.", "example": "USD", "required": true }, { "in": "query", "name": "from_type", "schema": { "$ref": "#/components/schemas/Ramp_SourceAssetType" }, "style": "form", "description": "Classification of the source asset. Pair with `from_symbol` to disambiguate when the same ticker exists across asset classes (e.g., `USDC` as `stablecoin` vs `crypto`). Only fiat sources are currently supported (on-ramp).", "example": "fiat" }, { "in": "query", "name": "from_method", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "style": "form", "description": "Funding method used for the source side. Use `GET /v1/ramp/payment-methods` to discover supported payment methods.", "example": "credit_card", "required": true }, { "in": "query", "name": "from_amount", "schema": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "Amount to spend, denominated in the source asset, as a decimal string. The quote is calculated for this fixed source amount.", "example": "100.00", "required": true }, { "in": "query", "name": "to_symbol", "schema": { "$ref": "#/components/schemas/AssetSymbol" }, "style": "form", "description": "Destination asset ticker symbol (e.g., \"BTC\"). Use `GET /v1/ramp/buy/crypto` to discover supported destination assets.", "example": "BTC", "required": true }, { "in": "query", "name": "to_type", "schema": { "$ref": "#/components/schemas/Ramp_DestinationAssetType" }, "style": "form", "description": "Classification of the destination asset. Pair with `to_symbol` to disambiguate when the same ticker exists across asset classes (e.g., `USDC` as `stablecoin` vs `crypto`). Only crypto and stablecoin destinations are currently supported (on-ramp).", "example": "crypto" }, { "in": "query", "name": "to_method", "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "style": "form", "description": "Withdrawal method for the destination asset. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset.", "example": "Bitcoin", "required": true }, { "in": "query", "name": "country", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "style": "form", "description": "ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values.", "example": "US", "required": true }, { "in": "query", "name": "subdivision", "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]+$", "minLength": 1, "maxLength": 64 }, "style": "form", "description": "ISO 3166-2 subdivision code suffix (e.g., `CA` for California when country is `US`). Use `GET /v1/ramp/countries` to discover supported values.", "example": "CA" }, { "in": "query", "name": "affiliate_fee_bps", "schema": { "type": "string", "pattern": "^(10000|[0-9]{1,4})$", "minLength": 1, "maxLength": 5 }, "style": "form", "description": "Affiliate fee in basis points to attribute to the partner (0-10000 where 100 = 1%). This fee is additive to the platform fee, increasing the total fee charged to the user. The resulting affiliate_fee in the response reflects the partner's portion of the total fee.", "example": "250" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Prospective quote for the requested Ramp route.", "type": "object", "properties": { "from": { "description": "Total the user pays, inclusive of fees, on the source side.", "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Ramp_AssetRef" }, "total": { "description": "Total amount after all fees. On the from side: subtotal + fee + deposit_fee. On the to side: subtotal - withdrawal_fee.", "type": "string", "minLength": 1, "maxLength": 64 }, "subtotal": { "description": "Base trade amount before any fees are applied.", "type": "string", "minLength": 1, "maxLength": 64 }, "fee": { "description": "Trading fee amount. This includes the affiliate fee portion when affiliate_fee_bps was provided.", "type": "string", "minLength": 1, "maxLength": 64 }, "deposit_fee": { "description": "Deposit or funding fee charged on the fiat payment method.", "type": "string", "minLength": 1, "maxLength": 64 }, "affiliate_fee": { "description": "Portion of fee attributed to the partner, based on the affiliate_fee_bps rate provided during checkout. This amount is already included in fee, not additional to it.", "type": "string", "minLength": 1, "maxLength": 64 }, "withdrawal_fee": { "description": "Crypto withdrawal or network fee (if applicable).", "type": "string", "minLength": 1, "maxLength": 64 }, "in_display": { "description": "Optional display currency projection for this asset breakdown.", "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Ramp_AssetRef" }, "total": { "description": "Total amount in display currency after all fees. On the from side: subtotal + fee + deposit_fee. On the to side: subtotal - withdrawal_fee.", "type": "string", "minLength": 1, "maxLength": 64 }, "subtotal": { "description": "Base trade amount in display currency before any fees are applied.", "type": "string", "minLength": 1, "maxLength": 64 }, "fee": { "description": "Trading fee amount in display currency. This includes the affiliate fee portion when affiliate_fee_bps was provided.", "type": "string", "minLength": 1, "maxLength": 64 }, "deposit_fee": { "description": "Deposit or funding fee in display currency.", "type": "string", "minLength": 1, "maxLength": 64 }, "affiliate_fee": { "description": "Portion of fee attributed to the partner in display currency, based on the affiliate_fee_bps rate provided during checkout. This amount is already included in fee, not additional to it.", "type": "string", "minLength": 1, "maxLength": 64 }, "withdrawal_fee": { "description": "Crypto withdrawal or network fee in display currency (if applicable).", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampQuoteAssetDetailsInDisplay", "required": [ "total", "subtotal" ] } }, "title": "RampQuoteAssetDetails", "required": [ "total", "subtotal" ] }, "to": { "description": "Total the user receives, net of fees, on the destination side.", "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Ramp_AssetRef" }, "total": { "description": "Total amount after all fees. On the from side: subtotal + fee + deposit_fee. On the to side: subtotal - withdrawal_fee.", "type": "string", "minLength": 1, "maxLength": 64 }, "subtotal": { "description": "Base trade amount before any fees are applied.", "type": "string", "minLength": 1, "maxLength": 64 }, "fee": { "description": "Trading fee amount. This includes the affiliate fee portion when affiliate_fee_bps was provided.", "type": "string", "minLength": 1, "maxLength": 64 }, "deposit_fee": { "description": "Deposit or funding fee charged on the fiat payment method.", "type": "string", "minLength": 1, "maxLength": 64 }, "affiliate_fee": { "description": "Portion of fee attributed to the partner, based on the affiliate_fee_bps rate provided during checkout. This amount is already included in fee, not additional to it.", "type": "string", "minLength": 1, "maxLength": 64 }, "withdrawal_fee": { "description": "Crypto withdrawal or network fee (if applicable).", "type": "string", "minLength": 1, "maxLength": 64 }, "in_display": { "description": "Optional display currency projection for this asset breakdown.", "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Ramp_AssetRef" }, "total": { "description": "Total amount in display currency after all fees. On the from side: subtotal + fee + deposit_fee. On the to side: subtotal - withdrawal_fee.", "type": "string", "minLength": 1, "maxLength": 64 }, "subtotal": { "description": "Base trade amount in display currency before any fees are applied.", "type": "string", "minLength": 1, "maxLength": 64 }, "fee": { "description": "Trading fee amount in display currency. This includes the affiliate fee portion when affiliate_fee_bps was provided.", "type": "string", "minLength": 1, "maxLength": 64 }, "deposit_fee": { "description": "Deposit or funding fee in display currency.", "type": "string", "minLength": 1, "maxLength": 64 }, "affiliate_fee": { "description": "Portion of fee attributed to the partner in display currency, based on the affiliate_fee_bps rate provided during checkout. This amount is already included in fee, not additional to it.", "type": "string", "minLength": 1, "maxLength": 64 }, "withdrawal_fee": { "description": "Crypto withdrawal or network fee in display currency (if applicable).", "type": "string", "minLength": 1, "maxLength": 64 } }, "title": "RampQuoteAssetDetailsInDisplay", "required": [ "total", "subtotal" ] } }, "title": "RampQuoteAssetDetails", "required": [ "total", "subtotal" ] }, "unit_price": { "description": "Unit price information returned in Ramp quotes.", "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Ramp_AssetRef" }, "denomination_asset": { "description": "Asset in which the quoted asset's unit price is denominated.", "$ref": "#/components/schemas/Ramp_AssetRef" }, "unit_price": { "description": "Price of one unit of the asset denominated in the denomination asset.", "$ref": "#/components/schemas/Price" }, "in_display": { "description": "Optional unit price projection in a different display currency.", "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Ramp_AssetRef" }, "unit_price": { "description": "Price of one unit of the asset denominated in the display asset.", "$ref": "#/components/schemas/Price" } }, "title": "RampQuoteUnitPriceInDisplay", "required": [ "unit_price" ] } }, "title": "RampQuoteUnitPrice", "required": [ "unit_price" ] } }, "title": "RampProspectiveQuoteData" } }, "required": [ "data" ] }, "examples": { "prospective-quote": { "summary": "Prospective quote", "value": { "data": { "from": { "asset": { "symbol": "USD", "type": "fiat", "name": "US Dollar" }, "total": "1015.00", "subtotal": "1000.00", "fee": "10.00", "deposit_fee": "5.00", "affiliate_fee": "2.50" }, "to": { "asset": { "symbol": "BTC", "type": "crypto", "name": "Bitcoin" }, "total": "0.01587302", "subtotal": "0.01587302", "withdrawal_fee": "0.00010000" }, "unit_price": { "asset": { "symbol": "BTC", "type": "crypto", "name": "Bitcoin" }, "denomination_asset": { "symbol": "USD", "type": "fiat", "name": "US Dollar" }, "unit_price": "63000.00" } } } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get Ramp prospective quote" } }, "/v1/users/{user_id}/ramp/checkouts": { "post": { "tags": [ "Ramp" ], "description": "Creates a Ramp checkout for a selected user and returns the widget redirect URL with the checkout UUID in the fragment. No access token is minted here; the widget mints it via the bootstrap call (`BootstrapRampCheckout`). The URL must still be treated as sensitive because the UUID is a capability handle.\n\nFor loginless SEPA checkouts, submit `from.method = \"sepa\"`, `from.symbol = \"EUR\"`, and an EEA `country`.", "operationId": "createRampCheckoutSession", "parameters": [ { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to create a token-bound Ramp checkout session.\n\nThe `from`/`to` pairing determines the Ramp direction. Only on-ramp (`from` fiat, `to` crypto or stablecoin) is currently supported; other pairings are rejected with `400 BadRequest`. For loginless SEPA checkouts, submit `from.method = \"sepa\"`, `from.symbol = \"EUR\"`, and an EEA `country`.", "type": "object", "properties": { "from": { "description": "Asset the user pays with at checkout.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"USD\"). Required. Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Ramp_SourceAssetType" }, "method": { "description": "Funding method used for the source side. Required. Use `GET /v1/ramp/payment-methods` to discover supported payment methods.", "type": "string", "minLength": 1, "maxLength": 128 }, "amount": { "description": "Amount to spend, denominated in the source asset, as a decimal string. Required.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "minLength": 1, "maxLength": 64 } }, "title": "RampCheckoutFrom", "required": [ "symbol", "method", "amount" ] }, "to": { "description": "Asset the user receives at checkout.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"BTC\"). Required. Use `GET /v1/ramp/buy/crypto` to discover supported destination assets.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Ramp_DestinationAssetType" }, "method": { "description": "Withdrawal method for the destination asset. Required. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset.", "type": "string", "minLength": 1, "maxLength": 128 }, "network": { "description": "Optional withdrawal network identifier. Use `GET /v1/ramp/buy/crypto` to discover available networks for each destination asset.", "type": "string", "minLength": 1, "maxLength": 128 }, "address": { "description": "Optional destination wallet address for the crypto withdrawal.", "type": "string", "minLength": 1, "maxLength": 512 }, "memo": { "description": "Optional memo/tag/note for the crypto withdrawal (used for certain assets).", "type": "string", "minLength": 1, "maxLength": 256 } }, "title": "RampCheckoutTo", "required": [ "symbol", "method" ] }, "affiliate_fee_bps": { "description": "Affiliate fee in basis points to attribute to the partner (0-10000 where 100 = 1%).", "type": "string", "pattern": "^(10000|[0-9]{1,4})$", "minLength": 1, "maxLength": 5 }, "country": { "description": "ISO 3166-1 alpha-2 country code. Use `GET /v1/ramp/countries` to discover supported values.", "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "subdivision": { "description": "ISO 3166-2 subdivision code suffix (e.g., `CA` for California when country is `US`). Use `GET /v1/ramp/countries` to discover supported values.", "type": "string", "pattern": "^[A-Za-z0-9-]+$", "minLength": 1, "maxLength": 64 }, "redirect_url": { "description": "URL to redirect the user after completing checkout successfully.", "type": "string", "minLength": 1, "maxLength": 255 }, "failure_url": { "description": "URL to redirect the user after a failed checkout.", "type": "string", "minLength": 1, "maxLength": 255 }, "external_user_id": { "description": "Optional partner-supplied user identifier.", "type": "string", "minLength": 1, "maxLength": 64 }, "external_partner_id": { "description": "Optional partner-supplied partner identifier.", "type": "string", "minLength": 1, "maxLength": 64 }, "external_transaction_id": { "description": "Optional partner transaction identifier.", "type": "string", "minLength": 1, "maxLength": 64 }, "external_metadata": { "description": "Optional metadata to store alongside the checkout.", "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "from", "to", "country" ] }, "examples": { "create-checkout": { "summary": "Create hosted checkout", "value": { "from": { "symbol": "USD", "type": "fiat", "method": "credit_card", "amount": "100.00" }, "to": { "symbol": "BTC", "type": "crypto", "method": "Bitcoin", "network": "Bitcoin", "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", "memo": "123456" }, "affiliate_fee_bps": "250", "country": "US", "subdivision": "CA", "redirect_url": "https://example.com/checkout/success", "failure_url": "https://example.com/checkout/failure", "external_user_id": "user_01J0M7C0Z9F8YX3GQH8E", "external_partner_id": "partner_456", "external_transaction_id": "INV-2026-04-0042", "external_metadata": "{\"order_id\":\"order_12345\"}" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Created checkout session details.", "type": "object", "properties": { "checkout_id": { "description": "Public checkout session identifier.", "type": "string", "minLength": 36, "maxLength": 36 }, "checkout_url": { "description": "Widget redirect URL with the checkout UUID in the fragment. No access token is present; the widget mints one via the bootstrap call. The UUID is a capability handle, so the URL is still sensitive.", "type": "string", "minLength": 1, "maxLength": 2048 }, "expires_in": { "description": "Checkout URL validity window, in seconds. This is how long the partner has to redirect the user before the handle should be considered stale. This is the creation-to-bootstrap window, not a token lifetime; the token TTL starts at bootstrap and is reported there.", "type": "integer", "format": "int64", "minimum": 0 }, "request_data": { "description": "Original request payload for client confirmation.", "type": "object", "properties": { "from": { "description": "Echo of the source (pay) side of the checkout.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"USD\"). Required. Use `GET /v1/ramp/fiat-currencies` to discover supported source currencies.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Ramp_SourceAssetType" }, "method": { "description": "Funding method used for the source side. Required. Use `GET /v1/ramp/payment-methods` to discover supported payment methods.", "type": "string", "minLength": 1, "maxLength": 128 }, "amount": { "description": "Amount to spend, denominated in the source asset, as a decimal string. Required.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "minLength": 1, "maxLength": 64 } }, "title": "RampCheckoutFrom", "required": [ "symbol", "method", "amount" ] }, "to": { "description": "Echo of the destination (receive) side of the checkout.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"BTC\"). Required. Use `GET /v1/ramp/buy/crypto` to discover supported destination assets.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Ramp_DestinationAssetType" }, "method": { "description": "Withdrawal method for the destination asset. Required. Use `GET /v1/ramp/buy/crypto` to discover available withdrawal methods for each asset.", "type": "string", "minLength": 1, "maxLength": 128 }, "network": { "description": "Optional withdrawal network identifier. Use `GET /v1/ramp/buy/crypto` to discover available networks for each destination asset.", "type": "string", "minLength": 1, "maxLength": 128 }, "address": { "description": "Optional destination wallet address for the crypto withdrawal.", "type": "string", "minLength": 1, "maxLength": 512 }, "memo": { "description": "Optional memo/tag/note for the crypto withdrawal (used for certain assets).", "type": "string", "minLength": 1, "maxLength": 256 } }, "title": "RampCheckoutTo", "required": [ "symbol", "method" ] }, "affiliate_fee_bps": { "description": "Affiliate fee in basis points (0-10000 where 100 = 1%).", "type": "string", "pattern": "^(10000|[0-9]{1,4})$", "minLength": 1, "maxLength": 5 }, "country": { "description": "ISO 3166-1 alpha-2 country code", "type": "string", "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2 }, "subdivision": { "description": "ISO 3166-2 subdivision code suffix (e.g., CA for California when country is US)", "type": "string", "pattern": "^[A-Za-z0-9-]+$", "minLength": 1, "maxLength": 64 }, "redirect_url": { "description": "URL where the ramp provider should redirect the user after successful checkout", "type": "string", "minLength": 1, "maxLength": 255 }, "failure_url": { "description": "URL where the ramp provider should redirect the user after failed checkout", "type": "string", "minLength": 1, "maxLength": 255 }, "external_user_id": { "description": "Partner-provided user identifier (max 64 characters)", "type": "string", "minLength": 1, "maxLength": 64 }, "external_partner_id": { "description": "Partner-provided partner identifier (max 64 characters)", "type": "string", "minLength": 1, "maxLength": 64 }, "external_transaction_id": { "description": "Partner-provided transaction identifier (max 64 characters)", "type": "string", "minLength": 1, "maxLength": 64 }, "external_metadata": { "description": "Additional partner-provided metadata (max 1000 characters)", "type": "string", "minLength": 1, "maxLength": 1000 } }, "title": "RampCheckoutRequestData", "required": [ "country" ] } }, "title": "RampCreatedCheckoutData", "required": [ "checkout_id", "checkout_url", "expires_in" ] } }, "required": [ "data" ] }, "examples": { "checkout-created": { "summary": "Created hosted checkout", "value": { "data": { "checkout_id": "018fdb88-4a87-73b2-9b9f-b5f38d11b924", "checkout_url": "https://ramp.kraken.com/confirmation#checkout_id=018fdb88-4a87-73b2-9b9f-b5f38d11b924", "expires_in": 600, "request_data": { "from": { "symbol": "USD", "type": "fiat", "method": "credit_card", "amount": "100.00" }, "to": { "symbol": "BTC", "type": "crypto", "method": "Bitcoin", "network": "Bitcoin", "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", "memo": "123456" }, "affiliate_fee_bps": "250", "country": "US", "subdivision": "CA", "redirect_url": "https://example.com/checkout/success", "failure_url": "https://example.com/checkout/failure", "external_user_id": "user_01J0M7C0Z9F8YX3GQH8E", "external_partner_id": "partner_456", "external_transaction_id": "INV-2026-04-0042", "external_metadata": "{\"order_id\":\"order_12345\"}" } } } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Create Ramp checkout session" } }, "/v1/accounts/{account_id}/funds/bank-links/{bank_link_id}": { "delete": { "tags": [ "Ramp" ], "description": "Severs the whole Bank Link: the link becomes `unlinked` and every Account Link is soft-removed. Unlinked links disappear from get/list and are rejected for new money movement; Account Link ids remain referenceable by history. Repeating the call returns the same final snapshot. Unlinking a link that never finished activating cancels its pending session and returns that same `unlinked` snapshot. A link busy with an in-flight provider operation (activation, reconnect, or an earlier unlink attempt) returns `Unavailable`; retry shortly. Unlinking also severs the provider-side connection; if the provider refuses (for example, transactions are still settling) the link is not unlinked. It keeps its current status, and the call returns `bank_link_provider_rejected`. If the provider outcome is unknown (for example, the provider was unreachable) the call also returns `Unavailable` and the link stays busy until the pending attempt expires; retry after that to finish the unlink.", "operationId": "unlinkBankLink", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "bank_link_id", "required": true, "schema": { "description": "Opaque public bank-link id.", "type": "string", "minLength": 4, "maxLength": 128 }, "style": "simple", "example": "bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Final snapshot: `unlinked`, with every Account Link `removed`.", "$ref": "#/components/schemas/Ramp_BankLink" } }, "required": [ "data" ] }, "examples": { "unlinked-bank-link": { "summary": "Severed link with every account removed", "value": { "data": { "bank_link_id": "bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "method_id": "3f9a1c2e-8b7d-4e6f-9a1b-2c3d4e5f6a7b", "status": "unlinked", "institution": { "name": "Pacific Trust Bank" }, "account_links": [ { "account_link_id": "al_7c2b8d19-4e35-4a71-b0c6-1d8f5e9a2b34", "account_last4": "4242", "status": "removed", "eligibility_status": "ineligible" } ], "accounts_eligibility_status": "ineligible" } } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "404": { "$ref": "#/components/responses/RampBankLinkNotFoundResponse" }, "409": { "$ref": "#/components/responses/RampUnlinkProviderRejectedResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Unlink bank link" }, "get": { "tags": [ "Ramp" ], "description": "Retrieves a Bank Link and its nested active Account Links. Ownership validation runs on every read rather than being stored: an account that fails it carries `ineligibility_reasons` such as `name_mismatch`, and an account that could not be evaluated carries none and reports `unknown`.", "operationId": "getBankLink", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "bank_link_id", "required": true, "schema": { "description": "Opaque public bank-link id.", "type": "string", "minLength": 4, "maxLength": 128 }, "style": "simple", "example": "bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "description": "A provider-neutral linking operation and persistent bank connection.", "$ref": "#/components/schemas/Ramp_BankLink" } } }, "examples": { "linked-bank-link": { "summary": "Linked connection with an eligible and an ineligible account", "value": { "data": { "bank_link_id": "bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "method_id": "3f9a1c2e-8b7d-4e6f-9a1b-2c3d4e5f6a7b", "status": "linked", "institution": { "name": "Pacific Trust Bank" }, "account_links": [ { "account_link_id": "al_7c2b8d19-4e35-4a71-b0c6-1d8f5e9a2b34", "account_last4": "4242", "status": "active", "eligible_rails": [ "ach", "rtp", "rfp" ], "rail_limits": { "rfp": { "max_daily_amount": "15000" } }, "eligibility_status": "eligible" }, { "account_link_id": "al_9e1f6a03-2c58-4bd9-8f47-3a6b0c7d5e82", "account_last4": "8815", "status": "active", "ineligibility_reasons": [ "name_mismatch" ], "eligibility_status": "ineligible" } ], "not_linked_accounts": [ { "account_last4": "5309", "reason": "missing_identity" } ], "accounts_eligibility_status": "eligible" } } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "404": { "$ref": "#/components/responses/RampBankLinkNotFoundResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get bank link" } }, "/v1/accounts/{account_id}/funds/bank-links/{bank_link_id}/reconnect": { "post": { "tags": [ "Ramp" ], "description": "Reconnects a Bank Link whose provider connection expired or was revoked. Returns it in `pending` with a fresh hosted-widget URL; the user re-authorizes through the provider and a stored credential is never reused. Completing it reconciles the account set: accounts shared again keep their `account_link_id`, newly shared accounts appear, and accounts no longer shared become `removed`, which drops them from get and list. An `account_link_id` is therefore stable but revocable, not permanent.", "operationId": "reconnectBankLink", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "in": "path", "name": "bank_link_id", "required": true, "schema": { "description": "Opaque public bank-link id.", "type": "string", "minLength": 4, "maxLength": 128 }, "style": "simple", "example": "bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "description": "Optional partner URL to return the user to after the hosted widget completes. When supplied it must be an absolute `https` URL without userinfo; other values are rejected.", "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048 } } }, "examples": { "reconnect-bank-link": { "summary": "Reconnect and return the user to the partner", "value": { "return_url": "https://partner.example.com/bank-link/return" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A provider-neutral linking operation and persistent bank connection.", "type": "object", "properties": { "bank_link_id": { "description": "Opaque public bank-link id.", "type": "string" }, "method_id": { "description": "Funding method this Bank Link was created for.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "activating", "linked", "expired", "unlinked" ], "title": "BankLinkStatus" }, "next_action": { "description": "How the partner completes the link while it is `pending`.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "hosted_link" ], "title": "NextActionType" }, "widget_url": { "description": "Kraken-hosted widget URL. Not a Plaid URL and carries no Plaid Link token.", "type": "string" }, "expires_at": { "description": "Time at which the hosted-link action expires.", "$ref": "#/components/schemas/DateTime" } }, "title": "NextAction", "required": [ "type", "widget_url", "expires_at" ] }, "institution": { "description": "Display-safe institution details. Provider account and item references are never exposed.", "type": "object", "properties": { "name": { "description": "Institution display name.", "type": "string", "minLength": 1, "maxLength": 256 } }, "title": "Institution", "required": [ "name" ] }, "account_links": { "description": "Account Links owned by this Bank Link.", "type": "array", "items": { "description": "A provider-neutral account linked under one Bank Link.", "type": "object", "properties": { "account_link_id": { "description": "Opaque public account-link id.", "type": "string" }, "account_last4": { "description": "The account's last four digits, safe to display.", "type": "string" }, "status": { "type": "string", "enum": [ "active", "removed" ], "title": "AccountLinkStatus" }, "eligible_rails": { "description": "Rails this account can currently use. Values are provider-neutral method identifiers such as `ach`, `rtp`, or `rfp`.", "type": "array", "items": { "type": "string" } }, "ineligibility_reasons": { "description": "Safe reasons why no rail is eligible. Empty when at least one rail is eligible or eligibility has not yet been evaluated.", "type": "array", "items": { "type": "string" } }, "eligibility_status": { "description": "Whether this account can move money, from its own ownership validation and rail capability. Always present, and consistent with this account's `eligible_rails` and `ineligibility_reasons`.", "$ref": "#/components/schemas/Ramp_AccountEligibilityStatus" }, "rail_limits": { "description": "Published limits for individual rails on this account.", "$ref": "#/components/schemas/Ramp_RailLimits" } }, "title": "AccountLink", "required": [ "account_link_id", "account_last4", "status", "eligibility_status" ] } }, "accounts_eligibility_status": { "description": "Whether any Account Link under this Bank Link can move money: the fold of the accounts' own `eligibility_status`. Always present. `eligible` means at least one account is eligible. `ineligible` means every account is conclusively ruled out, as a link that finished linking without a single account vacuously is. `unknown` means no account is confirmed eligible while at least one is still inconclusive, because its ownership or its rails were not evaluated. A `pending` link has no accounts to evaluate yet, so it reports `unknown` rather than the denial `ineligible` would be.", "type": "string", "enum": [ "eligible", "ineligible", "unknown" ], "title": "AccountsEligibilityStatus" }, "not_linked_accounts": { "description": "Accounts the user selected at the provider that could not be linked under this Bank Link. They hold no `account_link_id`, are excluded from `account_links` and from `accounts_eligibility_status`, and can never move money. Surfaced so a partner can tell the user that an account they picked was left out. Absent or empty when every selected account linked.", "type": "array", "items": { "description": "An account selected at the provider that could not be linked.", "type": "object", "properties": { "account_last4": { "description": "The account's last four digits, safe to display. May be empty when the provider reported none.", "type": "string" }, "reason": { "description": "Safe reason the account could not be linked. Known values are `missing_identity` means the provider could not verify the account holder's identity for this account. `missing_balance` means the provider could not read the account's balance; `unknown` is also possible. New reasons may be introduced over time; treat any unrecognized value as `unknown`.", "type": "string" } }, "title": "NotLinkedAccount", "required": [ "account_last4", "reason" ] } }, "linked_at": { "description": "When the connection became active. Absent until the link finishes linking.", "$ref": "#/components/schemas/DateTime" }, "expires_at": { "description": "When the connection is due to expire, if the provider has reported an expiry.", "$ref": "#/components/schemas/DateTime" } }, "title": "BankLink", "required": [ "bank_link_id", "method_id", "status", "next_action", "accounts_eligibility_status" ] } }, "required": [ "data" ] }, "examples": { "pending-reconnect": { "summary": "Reconnect started, with a fresh hosted-widget URL", "value": { "data": { "bank_link_id": "bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "method_id": "3f9a1c2e-8b7d-4e6f-9a1b-2c3d4e5f6a7b", "status": "pending", "next_action": { "type": "hosted_link", "widget_url": "https://bank-link.services.payward.com/link/bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "expires_at": "2026-08-19T11:45:00Z" }, "accounts_eligibility_status": "unknown" } } } } } } }, "400": { "$ref": "#/components/responses/RampBadRequestResponse" }, "401": { "$ref": "#/components/responses/RampUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/RampForbiddenResponse" }, "404": { "$ref": "#/components/responses/RampBankLinkNotFoundResponse" }, "409": { "$ref": "#/components/responses/RampBankLinkActivationRestartRequiredResponse" }, "429": { "$ref": "#/components/responses/RampResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/RampInternalResponse" }, "501": { "$ref": "#/components/responses/RampUnimplementedResponse" }, "503": { "$ref": "#/components/responses/RampUnavailableResponse" }, "504": { "$ref": "#/components/responses/RampDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Reconnect bank link" } }, "/v1/reports/settlement": { "get": { "tags": [ "Reports" ], "description": "Retrieves a paginated list of settlement reports available to the authenticated Master User, with optional filters for date range and report type.", "operationId": "listSettlementReports", "parameters": [ { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/Reports_PageSize" }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "style": "form", "example": "2026-04-25", "description": "The inclusive start date for filtering settlement reports. Use in combination with `end_date` to specify a date range. Use RFC 3339 full-date format (`YYYY-MM-DD`)." }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "style": "form", "example": "2026-04-26", "description": "The inclusive end date for filtering settlement reports. Use in combination with `start_date` to specify a date range. Use RFC 3339 full-date format (`YYYY-MM-DD`)." }, { "in": "query", "name": "report_type", "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Reports_SettlementReportType" } }, "style": "form", "explode": true, "example": [ "price_trigger_swaps", "swaps" ], "description": "Filters the returned reports by one or more report types. If omitted, all report types are included. Repeat the query parameter to request multiple types, for example `report_type=price_trigger_swaps&report_type=swaps`. Unknown values and the reserved `unspecified` value return a 400 response." } ], "responses": { "200": { "description": "Successful response containing a list of settlement reports and pagination details.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "An array of settlement report objects that match the specified filter criteria.", "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Reports_SettlementReport" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ], "example": { "data": [ { "id": "00000000-0000-0000-0000-000000000001", "date": "2026-04-25", "type": "swaps", "size": "18342", "name": "settlement-2026-04-25.csv" }, { "id": "00000000-0000-0000-0000-000000000003", "date": "2026-04-27", "type": "price_trigger_swaps", "size": "7341", "name": "settlement-2026-04-27.csv" }, { "id": "00000000-0000-0000-0000-000000000004", "date": "2026-04-28", "type": "earn_rewards", "size": "8102", "name": "settlement-2026-04-28.csv" } ] } }, "examples": { "settlement-reports": { "summary": "Settlement reports", "value": { "data": [ { "id": "00000000-0000-0000-0000-000000000001", "date": "2026-04-25", "type": "swaps", "size": "18342", "name": "settlement-2026-04-25.csv" }, { "id": "00000000-0000-0000-0000-000000000003", "date": "2026-04-27", "type": "price_trigger_swaps", "size": "7341", "name": "settlement-2026-04-27.csv" }, { "id": "00000000-0000-0000-0000-000000000004", "date": "2026-04-28", "type": "earn_rewards", "size": "8102", "name": "settlement-2026-04-28.csv" } ] } } } } } }, "400": { "$ref": "#/components/responses/ReportsBadRequestResponse" }, "401": { "$ref": "#/components/responses/ReportsUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/ReportsForbiddenResponse" }, "429": { "$ref": "#/components/responses/ReportsResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/ReportsInternalResponse" }, "501": { "$ref": "#/components/responses/ReportsUnimplementedResponse" }, "503": { "$ref": "#/components/responses/ReportsUnavailableResponse" }, "504": { "$ref": "#/components/responses/ReportsDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List settlement reports", "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X GET \"https://api.sandbox.services.payward.com/v1/reports/settlement?start_date=2026-04-25&end_date=2026-04-26&report_type=price_trigger_swaps&report_type=swaps&page_size=1\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\"" } ] } }, "/v1/reports/settlement/{id}": { "get": { "tags": [ "Reports" ], "description": "Retrieves a settlement report and provides a secure download URL for the authenticated Master User.", "operationId": "getSettlementReport", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "format": "uuid" }, "style": "simple", "example": "00000000-0000-0000-0000-000000000001", "description": "The unique identifier of the settlement report to retrieve." } ], "responses": { "200": { "description": "Successful response containing the settlement report details and secure download URL.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The settlement report details and secure download URL.", "$ref": "#/components/schemas/Reports_SettlementReportDownload" } }, "required": [ "data" ], "example": { "data": { "id": "00000000-0000-0000-0000-000000000001", "date": "2026-04-25", "type": "swaps", "size": "18342", "name": "settlement-2026-04-25.csv", "download_url": "https://reports.payward.com/dl/settlement-2026-04-25.csv", "expires_at": "2026-04-26T18:24:11Z" } } }, "examples": { "settlement-report": { "summary": "Settlement report", "value": { "data": { "id": "00000000-0000-0000-0000-000000000001", "date": "2026-04-25", "type": "swaps", "size": "18342", "name": "settlement-2026-04-25.csv", "download_url": "https://reports.payward.com/dl/settlement-2026-04-25.csv", "expires_at": "2026-04-26T18:24:11Z" } } } } } } }, "400": { "$ref": "#/components/responses/ReportsBadRequestResponse" }, "401": { "$ref": "#/components/responses/ReportsUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/ReportsForbiddenResponse" }, "404": { "description": "Settlement report not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reports_SettlementReportNotFoundError" }, "examples": { "settlement-report-not-found": { "summary": "Settlement report not found", "value": { "error": { "type": "reports_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "settlement_report_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/ReportsResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/ReportsInternalResponse" }, "501": { "$ref": "#/components/responses/ReportsUnimplementedResponse" }, "503": { "$ref": "#/components/responses/ReportsUnavailableResponse" }, "504": { "$ref": "#/components/responses/ReportsDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get settlement report", "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X GET \"https://api.sandbox.services.payward.com/v1/reports/settlement/00000000-0000-0000-0000-000000000001\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\"" } ] } }, "/v1/accounts/{account_id}/quotes": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "operationId": "createQuote", "tags": [ "Swaps" ], "summary": "Create quote", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Creates an account-funded quote.\n\nThe quote must be executed before `expires_at`. Expired quotes cannot be used.\n\nSet `amount` on exactly one of `from` or `to`; the other side is calculated when the quote is created.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "$ref": "#/components/schemas/Swaps_CreateQuoteFrom" }, "to": { "$ref": "#/components/schemas/Swaps_CreateQuoteTo" }, "fee": { "description": "Optional partner fee applied to the quote.", "$ref": "#/components/schemas/Swaps_QuoteFee" } } }, "examples": { "buy-crypto-with-a-fixed-fiat-amount": { "summary": "Buy crypto with a fixed fiat amount", "value": { "from": { "symbol": "USD", "type": "fiat", "amount": "100.00" }, "to": { "symbol": "ETH", "type": "crypto" } } }, "buy-a-fixed-amount-of-crypto": { "summary": "Buy a fixed amount of crypto", "value": { "from": { "symbol": "USD", "type": "fiat" }, "to": { "symbol": "ETH", "type": "crypto", "amount": "1" } } } } } } }, "responses": { "201": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Swaps_Quote" } } }, "examples": { "quote-ready-to-execute": { "summary": "Quote ready to execute", "value": { "data": { "id": "BQ5U74K-XV6GP-TTQ567", "status": "offered", "expires_at": "2026-01-01T00:02:00Z", "from": { "symbol": "USD", "type": "fiat", "amount": "3209.00" }, "to": { "symbol": "ETH", "type": "crypto", "amount": "1" }, "fees": { "trade": { "symbol": "USD", "type": "fiat", "amount": "9.00" } }, "rate": { "base": { "symbol": "ETH", "type": "crypto" }, "quote": { "symbol": "USD", "type": "fiat" }, "price": "3200" } } } } } } } }, "400": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BadRequestError" }, { "$ref": "#/components/schemas/Swaps_QuoteAmountTooSmallError" }, { "$ref": "#/components/schemas/Swaps_QuoteAmountTooLargeError" }, { "$ref": "#/components/schemas/Swaps_QuoteAmountPrecisionTooHighError" }, { "$ref": "#/components/schemas/Swaps_TotalMarginTooLowError" }, { "$ref": "#/components/schemas/Swaps_TotalMarginTooHighError" } ] }, "examples": { "quote-request-validation-failed": { "$ref": "#/components/examples/swap-quote-validation" }, "quote-amount-too-small": { "$ref": "#/components/examples/swap-quote-amount-too-small" }, "quote-amount-too-large": { "$ref": "#/components/examples/swap-quote-amount-too-large" }, "quote-amount-precision-too-high": { "$ref": "#/components/examples/swap-quote-amount-precision-too-high" }, "total-margin-too-low": { "$ref": "#/components/examples/swap-total-margin-too-low" }, "total-margin-too-high": { "$ref": "#/components/examples/swap-total-margin-too-high" } } } } }, "401": { "$ref": "#/components/responses/SwapQuoteUnauthenticatedResponse" }, "403": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ForbiddenError" }, { "$ref": "#/components/schemas/Swaps_TradeLockedError" } ] }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/swap-quote-forbidden" }, "trade-is-locked": { "$ref": "#/components/examples/swap-quote-trade-locked" } } } } }, "409": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Swaps_SellOnlyAssetError" }, { "$ref": "#/components/schemas/Swaps_FractionalExtendedHoursError" }, { "$ref": "#/components/schemas/Swaps_IpoAssetError" }, { "$ref": "#/components/schemas/Swaps_OtcRegularHoursOnlyError" }, { "$ref": "#/components/schemas/Swaps_OtcSellOnlyError" }, { "$ref": "#/components/schemas/Swaps_EquityMarketClosedError" }, { "$ref": "#/components/schemas/Swaps_IllegalOrderTypeAfterHoursError" }, { "$ref": "#/components/schemas/Swaps_InsufficientLiquidityError" } ] }, "examples": { "sell-only-asset": { "$ref": "#/components/examples/swap-sell-only-asset" }, "fractional-trading-during-extended-hours": { "$ref": "#/components/examples/swap-fractional-extended-hours" }, "ipo-asset": { "$ref": "#/components/examples/swap-ipo-asset" }, "otc-regular-hours-only": { "$ref": "#/components/examples/swap-otc-regular-hours-only" }, "otc-sell-only": { "$ref": "#/components/examples/swap-otc-sell-only" }, "equity-market-closed": { "$ref": "#/components/examples/swap-equity-market-closed" }, "illegal-order-type-after-hours": { "$ref": "#/components/examples/swap-illegal-order-type-after-hours" }, "insufficient-liquidity": { "$ref": "#/components/examples/swap-quote-insufficient-liquidity" } } } } }, "429": { "$ref": "#/components/responses/SwapQuoteResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapQuoteInternalResponse" }, "503": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/swap-quote-service-unavailable" } } } } }, "504": { "$ref": "#/components/responses/SwapQuoteDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/quotes/limits": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "get": { "operationId": "getQuoteLimits", "tags": [ "Swaps" ], "summary": "Get quote limits", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns the effective amount limits for a swap on the selected account.\n\nLimits reflect current liquidity and trading constraints. They are a point-in-time estimate and can change before a quote is created. When available, `limit_reasons` explains which constraints contributed to `maximum`.\n\nSet `amount_side` to the side whose amount the partner will fix when creating a quote. The returned asset and amounts are denominated in that side's asset. Clamp create-quote amounts to `[minimum_swap, maximum]`. Amount-too-large/small errors apply to create quote, not to this discovery call. Dust-only floors are intentionally not exposed here and may be added later for dust-sweep flows.", "parameters": [ { "name": "from_symbol", "in": "query", "description": "Source asset ticker symbol.", "required": true, "example": "USD", "style": "form", "schema": { "$ref": "#/components/schemas/AssetSymbol" } }, { "name": "from_type", "in": "query", "description": "Classification of the source asset.", "required": true, "example": "fiat", "style": "form", "schema": { "$ref": "#/components/schemas/Swaps_AssetType" } }, { "name": "to_symbol", "in": "query", "description": "Destination asset ticker symbol.", "required": true, "example": "ETH", "style": "form", "schema": { "$ref": "#/components/schemas/AssetSymbol" } }, { "name": "to_type", "in": "query", "description": "Classification of the destination asset.", "required": true, "example": "crypto", "style": "form", "schema": { "$ref": "#/components/schemas/Swaps_AssetType" } }, { "name": "amount_side", "in": "query", "description": "Side whose amount will be fixed when creating the quote and whose asset denominates the returned limits.", "required": true, "example": "from", "style": "form", "schema": { "$ref": "#/components/schemas/Swaps_QuoteLimitAmountSide" } } ], "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Swaps_QuoteLimits" } } }, "examples": { "fixed-source-limits": { "summary": "Limits for a fixed source amount", "value": { "data": { "asset": { "symbol": "USD", "type": "fiat" }, "minimum_swap": "1", "maximum": "150000", "precision": 2, "limit_reasons": [ "liquidity" ] } } } } } } }, "400": { "$ref": "#/components/responses/SwapQuoteBadRequestResponse" }, "401": { "$ref": "#/components/responses/SwapQuoteUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/SwapQuoteForbiddenResponse" }, "429": { "$ref": "#/components/responses/SwapQuoteResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapQuoteInternalResponse" }, "503": { "$ref": "#/components/responses/SwapQuoteUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapQuoteDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/quotes/{quote_id}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/Swaps_QuoteId" } ], "get": { "operationId": "getQuote", "tags": [ "Swaps" ], "summary": "Get quote", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns a quote by ID. Use this to check status after creating or executing a quote.", "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Swaps_Quote" } } }, "examples": { "executed-quote": { "summary": "Executed quote", "value": { "data": { "id": "BQ5U74K-XV6GP-TTQ567", "status": "executed", "expires_at": "2026-01-01T00:02:00Z", "from": { "symbol": "USD", "type": "fiat", "amount": "10" }, "to": { "symbol": "XBT", "type": "crypto", "amount": "0.00057962" }, "fees": { "trade": { "symbol": "USD", "type": "fiat", "amount": "0.15" } }, "rate": { "base": { "symbol": "XBT", "type": "crypto" }, "quote": { "symbol": "USD", "type": "fiat" }, "price": "16997.7" } } } } } } } }, "400": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/swap-quote-bad-request" } } } } }, "401": { "$ref": "#/components/responses/SwapQuoteUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/SwapQuoteForbiddenResponse" }, "404": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swaps_QuoteNotFoundError" }, "examples": { "quote-not-found": { "$ref": "#/components/examples/swap-quote-not-found" } } } } }, "429": { "$ref": "#/components/responses/SwapQuoteResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapQuoteInternalResponse" }, "503": { "$ref": "#/components/responses/SwapQuoteUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapQuoteDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/quotes/{quote_id}/execute": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/Swaps_QuoteId" } ], "post": { "operationId": "executeQuote", "tags": [ "Swaps" ], "summary": "Execute quote", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Executes a quote that is still `offered` and not expired.\n\nExecution may finish asynchronously, after this response returns. Use **Get quote** (`GET /v1/accounts/{account_id}/quotes/{quote_id}`) to check the final status.", "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Swaps_QuoteExecution" } } }, "examples": { "quote-execution-started": { "summary": "Quote execution started", "value": { "data": { "id": "BQ5U74K-XV6GP-TTQ567", "status": "executing" } } } } } }, "links": { "GetQuote": { "operationId": "getQuote", "parameters": { "account_id": "$request.path.account_id", "quote_id": "$request.path.quote_id" }, "description": "Check the quote's final status." } } }, "400": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BadRequestError" }, { "$ref": "#/components/schemas/Swaps_OnchainExecutionUnsupportedError" } ] }, "examples": { "invalid-request": { "$ref": "#/components/examples/swap-quote-validation" }, "onchain-execution-unsupported": { "$ref": "#/components/examples/swap-onchain-execution-unsupported" } } } } }, "401": { "$ref": "#/components/responses/SwapQuoteUnauthenticatedResponse" }, "403": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ForbiddenError" }, { "$ref": "#/components/schemas/Swaps_TradeLockedError" }, { "$ref": "#/components/schemas/Swaps_AcquisitionLimitExceededError" }, { "$ref": "#/components/schemas/Swaps_SuitabilityLimitExceededError" }, { "$ref": "#/components/schemas/Swaps_PatternDayTradingProtectionError" }, { "$ref": "#/components/schemas/Swaps_PotentialWashTradeError" } ] }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/swap-quote-forbidden" }, "trade-is-locked": { "$ref": "#/components/examples/swap-quote-trade-locked" }, "acquisition-limit-exceeded": { "$ref": "#/components/examples/swap-acquisition-limit-exceeded" }, "suitability-limit-exceeded": { "$ref": "#/components/examples/swap-suitability-limit-exceeded" }, "pattern-day-trading-protection": { "$ref": "#/components/examples/swap-pattern-day-trading-protection" }, "potential-wash-trade": { "$ref": "#/components/examples/swap-potential-wash-trade" } } } } }, "404": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swaps_QuoteNotFoundError" }, "examples": { "quote-not-found": { "$ref": "#/components/examples/swap-quote-not-found" } } } } }, "409": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Swaps_InsufficientFundsError" }, { "$ref": "#/components/schemas/Swaps_QuoteCancelledError" }, { "$ref": "#/components/schemas/Swaps_QuoteExecutionFailedError" }, { "$ref": "#/components/schemas/Swaps_InsufficientMarginError" }, { "$ref": "#/components/schemas/Swaps_SellOnlyAssetError" }, { "$ref": "#/components/schemas/Swaps_FractionalExtendedHoursError" }, { "$ref": "#/components/schemas/Swaps_IpoAssetError" }, { "$ref": "#/components/schemas/Swaps_OtcRegularHoursOnlyError" }, { "$ref": "#/components/schemas/Swaps_OtcSellOnlyError" }, { "$ref": "#/components/schemas/Swaps_EquityMarketClosedError" }, { "$ref": "#/components/schemas/Swaps_IllegalOrderTypeAfterHoursError" }, { "$ref": "#/components/schemas/Swaps_InsufficientLiquidityError" } ] }, "examples": { "insufficient-funds": { "$ref": "#/components/examples/swap-insufficient-funds" }, "quote-cancelled": { "$ref": "#/components/examples/swap-quote-cancelled" }, "quote-execution-failed": { "$ref": "#/components/examples/swap-quote-execution-failed" }, "insufficient-margin": { "$ref": "#/components/examples/swap-insufficient-margin" }, "sell-only-asset": { "$ref": "#/components/examples/swap-sell-only-asset" }, "fractional-trading-during-extended-hours": { "$ref": "#/components/examples/swap-fractional-extended-hours" }, "ipo-asset": { "$ref": "#/components/examples/swap-ipo-asset" }, "otc-regular-hours-only": { "$ref": "#/components/examples/swap-otc-regular-hours-only" }, "otc-sell-only": { "$ref": "#/components/examples/swap-otc-sell-only" }, "equity-market-closed": { "$ref": "#/components/examples/swap-equity-market-closed" }, "illegal-order-type-after-hours": { "$ref": "#/components/examples/swap-illegal-order-type-after-hours" }, "insufficient-liquidity": { "$ref": "#/components/examples/swap-quote-insufficient-liquidity" } } } } }, "410": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swaps_QuoteExpiredError" }, "examples": { "quote-expired": { "$ref": "#/components/examples/swap-quote-expired" } } } } }, "429": { "$ref": "#/components/responses/SwapQuoteResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapQuoteInternalResponse" }, "503": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/swap-quote-service-unavailable" } } } } }, "504": { "$ref": "#/components/responses/SwapQuoteDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/onchain-quotes": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "operationId": "createOnchainQuote", "tags": [ "Onchain quotes" ], "summary": "Create onchain quote", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Creates a wallet-funded quote and returns onchain execution details.\n\nSet `amount` on exactly one of `from` or `to`; the other side is calculated when the quote is created. The source `from.wallet` is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "$ref": "#/components/schemas/OnchainQuotes_CreateOnchainQuoteFrom" }, "to": { "$ref": "#/components/schemas/OnchainQuotes_CreateOnchainQuoteTo" } } }, "examples": { "buy-xstocks-with-usdc-onchain": { "summary": "Buy xStocks with USDC onchain", "value": { "from": { "symbol": "USDC", "type": "stablecoin", "wallet": { "address": "0x8888888888888888888888888888888888888888", "network": "ethereum" } }, "to": { "symbol": "TSLAx", "type": "xstock", "amount": "10" } } } } } } }, "responses": { "201": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OnchainQuotes_OnchainQuote" } } }, "examples": { "onchain-quote-ready-to-execute": { "summary": "Onchain quote ready to execute", "value": { "data": { "id": "XQAAAAAAAAAAA1", "status": "offered", "expires_at": "2026-04-24T12:34:09Z", "from": { "symbol": "USDC", "type": "stablecoin", "amount": "1853.4" }, "to": { "symbol": "TSLAx", "type": "xstock", "amount": "10" }, "execution_details": { "chain_id": "1", "proxy_address": "0x1111111111111111111111111111111111111111", "proxy_swap_message": { "atomic_message": { "quote_id": "0x3333333333333333333333333333333333333333333333333333333333333333", "expiration": 1777034103, "incoming_transfer": { "from": "0x1111111111111111111111111111111111111111", "to": "0x4444444444444444444444444444444444444444", "token": "0x5555555555555555555555555555555555555555", "amount": "1853400000" }, "outgoing_transfer": { "from": "0x4444444444444444444444444444444444444444", "to": "0x1111111111111111111111111111111111111111", "token": "0x6666666666666666666666666666666666666666", "amount": "10000000000000000000" } }, "atomic_signature": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "signature": "0x43ab90a8d9f4208395877c0a602bcd95574e4d39a0a416632861b09487c6f6a234f6e638ef714d6f6847882d557fe1d605587679081e81991f653d15007639741b", "client_address": "0x8888888888888888888888888888888888888888", "authorization_deadline": 1777034103 } } } } } } } } }, "400": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "onchain-quote-request-validation-failed": { "$ref": "#/components/examples/swap-onchain-quote-validation" } } } } }, "401": { "$ref": "#/components/responses/SwapOnchainQuoteUnauthenticatedResponse" }, "403": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ForbiddenError" }, { "$ref": "#/components/schemas/OnchainQuotes_TradeLockedError" } ] }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/swap-onchain-quote-forbidden" }, "trade-is-locked": { "$ref": "#/components/examples/swap-onchain-trade-locked" } } } } }, "429": { "$ref": "#/components/responses/SwapOnchainQuoteResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapOnchainQuoteInternalResponse" }, "503": { "$ref": "#/components/responses/SwapOnchainQuoteUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapOnchainQuoteDeadlineExceededResponse" } } }, "get": { "operationId": "listOnchainQuotes", "tags": [ "Onchain quotes" ], "summary": "List onchain quotes", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns onchain quotes for the account. Use `page_size` and `page_token` to page through results.", "parameters": [ { "$ref": "#/components/parameters/PageToken" }, { "$ref": "#/components/parameters/OnchainQuotes_PageSize" } ], "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OnchainQuotes_OnchainQuote" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "examples": { "page-of-onchain-quotes": { "summary": "Page of onchain quotes", "value": { "data": [ { "id": "XQAAAAAAAAAAA1", "status": "offered", "expires_at": "2026-04-24T12:34:09Z", "from": { "symbol": "USDC", "type": "stablecoin", "amount": "1853.4" }, "to": { "symbol": "TSLAx", "type": "xstock", "amount": "10" } } ], "next_page_token": "AAZUbz9WQAAAAAAAACrUqPGCRjzHZvqDr8PUyYwbx41j4AuH" } } } } } }, "400": { "$ref": "#/components/responses/SwapOnchainQuoteBadRequestResponse" }, "401": { "$ref": "#/components/responses/SwapOnchainQuoteUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/SwapOnchainQuoteForbiddenResponse" }, "429": { "$ref": "#/components/responses/SwapOnchainQuoteResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapOnchainQuoteInternalResponse" }, "503": { "$ref": "#/components/responses/SwapOnchainQuoteUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapOnchainQuoteDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/onchain-quotes/soft": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "operationId": "getSoftQuote", "tags": [ "Onchain quotes" ], "summary": "Get soft quote", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns a short-lived indicative price for a wallet-funded onchain swap.\n\nA soft quote carries no execution details and cannot be executed or retrieved later; nothing is persisted. Use **Create onchain quote** (`POST /v1/accounts/{account_id}/onchain-quotes`) to obtain an executable quote.\n\nSet `amount` on exactly one of `from` or `to`; the other side is calculated when the soft quote is priced.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "network" ], "properties": { "from": { "$ref": "#/components/schemas/OnchainQuotes_GetSoftQuoteFrom" }, "to": { "$ref": "#/components/schemas/OnchainQuotes_GetSoftQuoteTo" }, "network": { "description": "Network for which the indicative price is quoted.", "$ref": "#/components/schemas/OnchainQuotes_WalletNetwork" } } }, "examples": { "indicative-price-for-buying-xstocks-with-usdc": { "summary": "Indicative price for buying xStocks with USDC", "value": { "from": { "symbol": "USDC", "type": "stablecoin" }, "to": { "symbol": "TSLAx", "type": "xstock", "amount": "10" }, "network": "ethereum" } } } } } }, "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OnchainQuotes_SoftQuote" } } }, "examples": { "indicative-soft-quote": { "summary": "Indicative soft quote", "value": { "data": { "from": { "symbol": "USDC", "type": "stablecoin", "amount": "1853.4" }, "to": { "symbol": "TSLAx", "type": "xstock", "amount": "10" }, "rate": { "base": { "symbol": "TSLAx", "type": "xstock" }, "quote": { "symbol": "USDC", "type": "stablecoin" }, "price": "185.34" } } } } } } } }, "400": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "soft-quote-request-validation-failed": { "$ref": "#/components/examples/swap-onchain-quote-validation" } } } } }, "401": { "$ref": "#/components/responses/SwapOnchainQuoteUnauthenticatedResponse" }, "403": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Forbidden", "$ref": "#/components/schemas/ForbiddenError" }, { "title": "Trade Locked", "$ref": "#/components/schemas/OnchainQuotes_TradeLockedError" } ] }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/swap-onchain-quote-forbidden" }, "trade-is-locked": { "$ref": "#/components/examples/swap-onchain-trade-locked" } } } } }, "429": { "$ref": "#/components/responses/SwapOnchainQuoteResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapOnchainQuoteInternalResponse" }, "503": { "$ref": "#/components/responses/SwapOnchainQuoteUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapOnchainQuoteDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/onchain-quotes/{quote_id}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/OnchainQuotes_QuoteId" } ], "get": { "operationId": "getOnchainQuote", "tags": [ "Onchain quotes" ], "summary": "Get onchain quote", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns an onchain quote by ID, including execution details when available.", "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OnchainQuotes_OnchainQuote" } } }, "examples": { "onchain-quote-without-execution-details": { "summary": "Onchain quote without execution details", "value": { "data": { "id": "XQAAAAAAAAAAA1", "status": "offered", "expires_at": "2026-04-24T12:34:09Z", "from": { "symbol": "USDC", "type": "stablecoin", "amount": "1853.4" }, "to": { "symbol": "TSLAx", "type": "xstock", "amount": "10" } } } } } } } }, "400": { "$ref": "#/components/responses/SwapOnchainQuoteBadRequestResponse" }, "401": { "$ref": "#/components/responses/SwapOnchainQuoteUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/SwapOnchainQuoteForbiddenResponse" }, "404": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnchainQuotes_QuoteNotFoundError" }, "examples": { "onchain-quote-not-found": { "$ref": "#/components/examples/swap-onchain-quote-not-found" } } } } }, "429": { "$ref": "#/components/responses/SwapOnchainQuoteResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapOnchainQuoteInternalResponse" }, "503": { "$ref": "#/components/responses/SwapOnchainQuoteUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapOnchainQuoteDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/price-trigger-swaps": { "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "post": { "operationId": "createPriceTriggerSwap", "tags": [ "Price trigger swaps" ], "summary": "Create price-triggered swap", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Creates a swap that submits a trade when its price condition is met.\n\nThe swap stays `active` until it completes, fails, or is canceled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trade", "when" ], "properties": { "trade": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapTradeInput" }, "when": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerConditionInput" }, "client_order_id": { "description": "A client order identifier which uniquely identifies a price trigger swap. Echoed back on the price-triggered swap.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x20-\\x7E]+$" } } }, "examples": { "buy-crypto-when-the-price-rises": { "summary": "Buy crypto when the price rises", "value": { "trade": { "from": { "symbol": "USD", "type": "fiat", "amount": "100.00" }, "to": { "symbol": "BTC", "type": "crypto" }, "fee": { "bps": 150 } }, "when": { "base": { "symbol": "BTC", "type": "crypto" }, "quote": { "symbol": "USD", "type": "fiat" }, "rises_to": "50000" } } } } } } }, "responses": { "201": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwap" } } }, "examples": { "active-price-triggered-swap": { "summary": "Active price-triggered swap", "value": { "data": { "id": "ALCCIA-CUT6P-XCW6K7", "status": "active", "trade": { "from": { "symbol": "USD", "type": "fiat", "amount": "100.00" }, "to": { "symbol": "BTC", "type": "crypto" }, "fee": { "bps": "150" } }, "when": { "base": { "symbol": "BTC", "type": "crypto" }, "quote": { "symbol": "USD", "type": "fiat" }, "rises_to": "50000" }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } } } } } } }, "400": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "price-triggered-swap-request-validation-failed": { "$ref": "#/components/examples/swap-price-trigger-swap-validation" } } } } }, "401": { "$ref": "#/components/responses/SwapPriceTriggerSwapUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/SwapPriceTriggerSwapForbiddenResponse" }, "409": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapClientOrderIdDuplicateError" }, "examples": { "price-triggered-swap-client-order-id-duplicate": { "$ref": "#/components/examples/swap-price-trigger-swap-client-order-id-duplicate" } } } } }, "412": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapTargetPriceAlreadyAvailableError" }, "examples": { "price-triggered-swap-target-price-already-available": { "$ref": "#/components/examples/swap-price-trigger-swap-target-price-already-available" } } } } }, "429": { "$ref": "#/components/responses/SwapPriceTriggerSwapResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapPriceTriggerSwapInternalResponse" }, "503": { "$ref": "#/components/responses/SwapPriceTriggerSwapUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapPriceTriggerSwapDeadlineExceededResponse" } } }, "get": { "operationId": "listPriceTriggerSwaps", "tags": [ "Price trigger swaps" ], "summary": "List price-triggered swaps", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns price-triggered swaps for the account. Use `page_size` and `page_token` to page through results.", "parameters": [ { "$ref": "#/components/parameters/PriceTriggerSwaps_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwap" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "examples": { "page-of-active-price-triggered-swaps": { "summary": "Page of active price-triggered swaps", "value": { "data": [ { "id": "ALCCIA-CUT6P-XCW6K7", "status": "active", "trade": { "from": { "symbol": "USD", "type": "fiat", "amount": "100.00" }, "to": { "symbol": "BTC", "type": "crypto" }, "fee": { "bps": "150" } }, "when": { "base": { "symbol": "BTC", "type": "crypto" }, "quote": { "symbol": "USD", "type": "fiat" }, "rises_to": "50000" }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ], "next_page_token": "ALCCIA-CUT6P-XCW6K7" } } } } } }, "400": { "$ref": "#/components/responses/SwapPriceTriggerSwapBadRequestResponse" }, "401": { "$ref": "#/components/responses/SwapPriceTriggerSwapUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/SwapPriceTriggerSwapForbiddenResponse" }, "429": { "$ref": "#/components/responses/SwapPriceTriggerSwapResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapPriceTriggerSwapInternalResponse" }, "503": { "$ref": "#/components/responses/SwapPriceTriggerSwapUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapPriceTriggerSwapDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/price-trigger-swaps/{price_trigger_swap_id}": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/PriceTriggerSwaps_PriceTriggerSwapId" } ], "get": { "operationId": "getPriceTriggerSwap", "tags": [ "Price trigger swaps" ], "summary": "Get price-triggered swap", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Returns a price-triggered swap by ID. Use this to check status and inspect the requested or executed trade.", "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwap" } } }, "examples": { "active-price-triggered-swap": { "summary": "Active price-triggered swap", "value": { "data": { "id": "ALCCIA-CUT6P-XCW6K7", "status": "active", "trade": { "from": { "symbol": "USD", "type": "fiat", "amount": "100.00" }, "to": { "symbol": "BTC", "type": "crypto" }, "fee": { "bps": "150" } }, "when": { "base": { "symbol": "BTC", "type": "crypto" }, "quote": { "symbol": "USD", "type": "fiat" }, "rises_to": "50000" }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } } } } } } }, "400": { "$ref": "#/components/responses/SwapPriceTriggerSwapBadRequestResponse" }, "401": { "$ref": "#/components/responses/SwapPriceTriggerSwapUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/SwapPriceTriggerSwapForbiddenResponse" }, "404": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapNotFoundError" }, "examples": { "price-triggered-swap-not-found": { "$ref": "#/components/examples/swap-price-trigger-swap-not-found" } } } } }, "429": { "$ref": "#/components/responses/SwapPriceTriggerSwapResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapPriceTriggerSwapInternalResponse" }, "503": { "$ref": "#/components/responses/SwapPriceTriggerSwapUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapPriceTriggerSwapDeadlineExceededResponse" } } } }, "/v1/accounts/{account_id}/price-trigger-swaps/{price_trigger_swap_id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/PriceTriggerSwaps_PriceTriggerSwapId" } ], "post": { "operationId": "cancelPriceTriggerSwap", "tags": [ "Price trigger swaps" ], "summary": "Cancel price-triggered swap", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Cancels a price-triggered swap that is still `active`. Swaps in any other status return `409 Conflict`.", "responses": { "204": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/SwapPriceTriggerSwapBadRequestResponse" }, "401": { "$ref": "#/components/responses/SwapPriceTriggerSwapUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/SwapPriceTriggerSwapForbiddenResponse" }, "404": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapNotFoundError" }, "examples": { "price-triggered-swap-not-found": { "$ref": "#/components/examples/swap-price-trigger-swap-not-found" } } } } }, "409": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapNotCancellableError" }, "examples": { "price-triggered-swap-not-cancellable": { "$ref": "#/components/examples/swap-price-trigger-swap-not-cancellable" } } } } }, "429": { "$ref": "#/components/responses/SwapPriceTriggerSwapResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/SwapPriceTriggerSwapInternalResponse" }, "503": { "$ref": "#/components/responses/SwapPriceTriggerSwapUnavailableResponse" }, "504": { "$ref": "#/components/responses/SwapPriceTriggerSwapDeadlineExceededResponse" } } } }, "/v1/users/{user_id}/travel-rule/verifications": { "parameters": [ { "$ref": "#/components/parameters/UserId" } ], "post": { "operationId": "createTravelRuleVerification", "tags": [ "Travel Rule verifications" ], "summary": "Create Travel Rule verification", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Creates a Travel Rule verification case for a known wallet address.\n\nUse this endpoint when the wallet address is known before a specific product flow needs to continue.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleVerifications_CreateTravelRuleVerificationBody" }, "examples": { "hosted-wallet": { "summary": "Hosted wallet verification", "value": { "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72", "method": "hosted_declaration" } }, "self-hosted-wallet": { "summary": "Self-hosted wallet verification", "value": { "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72", "method": "self_attestation", "evidence": { "ownership_confirmed": true, "two_factor_completed": true, "two_factor_method": "otp", "attestation_text": "In accordance with Payward's Terms of Service, I, customer {userID}, confirm that the wallet address {wallet-address} is a self-hosted wallet owned and controlled solely by me. I make this declaration on {date}, and it applies to all deposits and withdrawals between this wallet and my account.", "user_confirmed_at": "2026-06-23T10:00:00Z" } } } } } } }, "responses": { "201": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleVerifications_CreateTravelRuleVerificationEnvelope" }, "examples": { "hosted-wallet-verified": { "summary": "Hosted wallet verified", "value": { "data": { "verification_id": "ver_0195e4d2-a4d0-7b12-8f4a-123456789abc", "wallet_type": "hosted", "method": "hosted_declaration", "status": "verified" } } }, "self-hosted-wallet-verified": { "summary": "Self-hosted wallet verified", "value": { "data": { "verification_id": "ver_0195e4d2-a4d0-7b12-8f4a-123456789abc", "wallet_type": "self_hosted", "method": "self_attestation", "status": "verified" } } } } } } }, "400": { "$ref": "#/components/responses/TravelRuleBadRequestResponse" }, "401": { "$ref": "#/components/responses/TravelRuleUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/TravelRuleForbiddenResponse" }, "409": { "$ref": "#/components/responses/TravelRuleVerificationConflictResponse" }, "429": { "$ref": "#/components/responses/TravelRuleResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/TravelRuleInternalResponse" }, "503": { "$ref": "#/components/responses/TravelRuleUnavailableResponse" }, "504": { "$ref": "#/components/responses/TravelRuleDeadlineExceededResponse" } } } }, "/v1/users/{user_id}/travel-rule/verifications/{verification_id}": { "parameters": [ { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/TravelRuleVerifications_VerificationId" } ], "get": { "operationId": "getTravelRuleVerification", "tags": [ "Travel Rule verifications" ], "summary": "Get Travel Rule verification", "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "description": "Gets a previously returned proactive Travel Rule verification case.", "responses": { "200": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleVerifications_GetTravelRuleVerificationEnvelope" }, "examples": { "self-hosted-wallet-verified": { "summary": "Self-hosted wallet verified", "value": { "data": { "verification_id": "ver_0195e4d2-a4d0-7b12-8f4a-123456789abc", "wallet_type": "self_hosted", "method": "self_attestation", "status": "verified", "created_at": "2026-06-23T10:00:00Z", "updated_at": "2026-06-23T10:00:00Z" } } } } } } }, "400": { "$ref": "#/components/responses/TravelRuleBadRequestResponse" }, "401": { "$ref": "#/components/responses/TravelRuleUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/TravelRuleForbiddenResponse" }, "404": { "$ref": "#/components/responses/TravelRuleVerificationNotFoundResponse" }, "429": { "$ref": "#/components/responses/TravelRuleResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/TravelRuleInternalResponse" }, "503": { "$ref": "#/components/responses/TravelRuleUnavailableResponse" }, "504": { "$ref": "#/components/responses/TravelRuleDeadlineExceededResponse" } } } }, "/v1/users": { "post": { "tags": [ "Users" ], "description": "Create a new account-owned user in the Payward system.\n\nCheck the user's verification requirements with `GET /v1/users/{user_id}/verifications/requirements`. When verification is required, call `POST /v1/users/{user_id}/verifications/hosted` to obtain the available hosted verification methods.\n\nWhen retrying user creation, send the same `external_reference` for the same partner user. Payward uses this value to avoid creating duplicate users. Retry responses are generated from the latest available user state, not replayed from the original request.\n\nReturns the created `id` and the `accounts` associated with the user.", "operationId": "createUser", "requestBody": { "content": { "application/json": { "schema": { "description": "Request to create a new user.", "type": "object", "additionalProperties": false, "properties": { "email": { "description": "The email associated with the user, when available at create time.", "type": "string", "maxLength": 254, "format": "email" }, "external_reference": { "description": "Stable partner-supplied reference for this user. Must be unique within your partner account. Reuse the same value only for the same user, including create retries.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "external_reference" ] }, "examples": { "create-bare-user": { "summary": "Create a bare user", "value": { "external_reference": "partner-customer-9001" } }, "create-user-with-email": { "summary": "Create a user with an email", "value": { "email": "alex.morgan@example.com", "external_reference": "partner-customer-9001" } } } } }, "required": true }, "responses": { "201": { "description": "Created", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Created user payload.", "title": "CreateUserData", "type": "object", "properties": { "id": { "description": "User ID of the newly created user, also used as its canonical identifier.", "type": "string", "minLength": 14, "maxLength": 42 }, "accounts": { "description": "Accounts associated with the created user.", "type": "array", "items": { "description": "Account associated with a user.", "title": "UserAccount", "type": "object", "properties": { "id": { "description": "Public account identifier.", "type": "string", "minLength": 1, "maxLength": 42 }, "name": { "description": "Account display name.", "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "description": "Longer description of what the account is for. Absent when the account has none.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "name" ] } } }, "required": [ "id" ] } }, "required": [ "data" ] }, "examples": { "created-user": { "summary": "Created user and accounts", "value": { "data": { "id": "AA45N8G4MLDYWAR7", "accounts": [ { "id": "WX6VJUKWKKPBQE36", "name": "main" }, { "id": "WC9RDEFHPSGLXRVX", "name": "secondary" } ] } } } } } } }, "400": { "$ref": "#/components/responses/UsersBadRequestResponse" }, "401": { "$ref": "#/components/responses/UsersUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/UsersForbiddenResponse" }, "429": { "$ref": "#/components/responses/UsersResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/UsersInternalResponse" }, "503": { "$ref": "#/components/responses/UsersUnavailableResponse" }, "504": { "$ref": "#/components/responses/UsersDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Create user", "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X POST \"https://api.sandbox.services.payward.com/v1/users\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"alex.morgan@example.com\",\n \"external_reference\": \"partner-customer-9001\"\n }'" } ] } }, "/v1/users/{user_id}": { "get": { "tags": [ "Users" ], "description": "Retrieve a previously created user by their user ID.\n\nReturns the user's core resource, including its canonical `id`, the partner-supplied `external_reference`, the `created_at` timestamp, and the `accounts` associated with the user.\n\nCommon use cases:\n- Confirm a user exists and retrieve its account IDs before issuing account-scoped calls.\n- Read the partner-supplied reference associated with a user.\n\nTo retrieve onboarding state and pending actions, use **Get Verification Requirements**.", "operationId": "getUser", "parameters": [ { "$ref": "#/components/parameters/UserId" } ], "responses": { "200": { "description": "Response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Retrieved user resource.", "$ref": "#/components/schemas/Users_User" } }, "required": [ "data" ] }, "examples": { "active-user": { "summary": "Active user with no pending actions", "value": { "data": { "id": "AA45N8G4MLDYWAR7", "external_reference": "partner-customer-12345", "created_at": "2025-08-12T14:08:00Z", "accounts": [ { "id": "WX6VJUKWKKPBQE36", "name": "main" } ] } } } } } } }, "400": { "$ref": "#/components/responses/UsersBadRequestResponse" }, "401": { "$ref": "#/components/responses/UsersUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/UsersForbiddenResponse" }, "404": { "description": "User not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Users_UserNotFoundError" }, "examples": { "user-not-found": { "summary": "User not found", "value": { "error": { "type": "users_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "user_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/UsersResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/UsersInternalResponse" }, "503": { "$ref": "#/components/responses/UsersUnavailableResponse" }, "504": { "$ref": "#/components/responses/UsersDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get user", "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X GET \"https://api.sandbox.services.payward.com/v1/users/AA45N8G4MLDYWAR7\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\"" } ] } }, "/v1/users/{user_id}/accounts": { "post": { "tags": [ "Users" ], "description": "Create an additional account for an existing user.\n\nEvery user is created with one account, returned in the `accounts` array of the create-user response. Use this endpoint to add another one, for example, to separate a user's funds by purpose.\n\nReturns the created account `id`. Account names are not required to be unique within a user.", "operationId": "createUserAccount", "parameters": [ { "$ref": "#/components/parameters/UserId" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to create an additional account for a user.", "type": "object", "properties": { "name": { "description": "Account display name. Accepts ASCII letters, digits, spaces, underscores, and hyphens.", "type": "string", "minLength": 4, "maxLength": 64 }, "description": { "description": "Longer description of what the account is for.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "name" ] }, "examples": { "savings-account": { "summary": "Create a named account", "value": { "name": "Savings" } } } } }, "required": true }, "responses": { "201": { "description": "Created", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Created account payload.", "title": "CreateUserAccountData", "type": "object", "properties": { "id": { "description": "Public account identifier.", "type": "string", "minLength": 1, "maxLength": 42 } }, "required": [ "id" ] } }, "required": [ "data" ] }, "examples": { "created-account": { "summary": "Created account", "value": { "data": { "id": "WC9RDEFHPSGLXRVX" } } } } } } }, "400": { "$ref": "#/components/responses/UsersBadRequestResponse" }, "401": { "$ref": "#/components/responses/UsersUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/UsersForbiddenResponse" }, "429": { "$ref": "#/components/responses/UsersResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/UsersInternalResponse" }, "503": { "$ref": "#/components/responses/UsersUnavailableResponse" }, "504": { "$ref": "#/components/responses/UsersDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Create user account", "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X POST \"https://api.sandbox.services.payward.com/v1/users/AA45N8G4MLDYWAR7/accounts\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Savings\"}'" } ] } }, "/v1/users/{user_id}/verifications/{verification_id}": { "get": { "operationId": "getVerification", "summary": "Get verification", "tags": [ "Verifications" ], "description": "Get a verification summary for the given user and verification ID.", "parameters": [ { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/Verifications_VerificationIdPath" } ], "responses": { "200": { "description": "Verification returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Verifications_VerificationSummary" } }, "required": [ "data" ] }, "examples": { "verification": { "summary": "Verification summary", "value": { "data": { "verification_id": "PVABCDE-FGHIJ-KLMNOP", "types": [ "proof_of_liveness" ], "method": "url", "status": "pending", "created_at": "2026-05-20T14:30:00Z", "updated_at": "2026-05-20T14:45:00Z" } } } } } }, "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/VerificationsBadRequestResponse" }, "401": { "$ref": "#/components/responses/VerificationsUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/VerificationsForbiddenResponse" }, "429": { "$ref": "#/components/responses/VerificationsResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/VerificationsInternalResponse" }, "501": { "$ref": "#/components/responses/VerificationsUnimplementedResponse" }, "503": { "$ref": "#/components/responses/VerificationsUnavailableResponse" }, "504": { "$ref": "#/components/responses/VerificationsDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X GET \"https://api.sandbox.services.payward.com/v1/users/AA45N8G4MLDYWAR7/verifications/PVABCDE-FGHIJ-KLMNOP\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\"" } ], "x-speakeasy-mcp": { "readOnlyHint": true, "idempotentHint": true, "destructiveHint": false } } }, "/v1/users/{user_id}/verifications": { "get": { "operationId": "listVerifications", "summary": "List verifications", "tags": [ "Verifications" ], "description": "List verification summaries for the given user.", "parameters": [ { "$ref": "#/components/parameters/UserId" } ], "responses": { "200": { "description": "Verifications returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Verifications_ListVerificationsData" } }, "required": [ "data" ] }, "examples": { "verifications-page": { "summary": "Verification summaries", "value": { "data": { "verifications": [ { "verification_id": "PVABCDE-FGHIJ-KLMNOP", "types": [ "proof_of_identity" ], "method": "url", "status": "completed", "created_at": "2026-05-20T14:30:00Z", "updated_at": "2026-05-20T14:45:00Z" }, { "verification_id": "PV12345-ABCDE-6789XY", "types": [ "proof_of_address" ], "method": "url", "status": "pending", "created_at": "2026-05-20T14:30:00Z", "updated_at": "2026-05-20T14:45:00Z" }, { "verification_id": "PVABCDE-12345-KLMNOP", "types": [ "proof_of_liveness" ], "method": "url", "status": "pending", "created_at": "2026-05-20T14:30:00Z", "updated_at": "2026-05-20T14:45:00Z" }, { "verification_id": "PV67890-FGHIJ-KLMNOP", "types": [ "proof_of_identity", "proof_of_address", "proof_of_liveness" ], "method": "hosted", "status": "pending", "created_at": "2026-05-20T14:30:00Z", "updated_at": "2026-05-20T14:45:00Z" } ] } } } } } }, "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/VerificationsBadRequestResponse" }, "401": { "$ref": "#/components/responses/VerificationsUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/VerificationsForbiddenResponse" }, "429": { "$ref": "#/components/responses/VerificationsResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/VerificationsInternalResponse" }, "501": { "$ref": "#/components/responses/VerificationsUnimplementedResponse" }, "503": { "$ref": "#/components/responses/VerificationsUnavailableResponse" }, "504": { "$ref": "#/components/responses/VerificationsDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X GET \"https://api.sandbox.services.payward.com/v1/users/AA45N8G4MLDYWAR7/verifications\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\"" } ], "x-speakeasy-mcp": { "readOnlyHint": true, "idempotentHint": true, "destructiveHint": false } } }, "/v1/users/{user_id}/verifications/requirements": { "get": { "operationId": "getVerificationRequirements", "summary": "Get verification requirements", "tags": [ "Verifications" ], "description": "Get the user's verification state and ordered required actions. The `user_action_required` field is true only when the user or partner can complete an action now. A `wait` action is non-actionable.", "parameters": [ { "$ref": "#/components/parameters/UserId" } ], "responses": { "200": { "description": "Verification requirements returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/Verifications_VerificationStatusOk" }, { "$ref": "#/components/schemas/Verifications_VerificationStatusDisabled" }, { "$ref": "#/components/schemas/Verifications_VerificationStatusClosed" } ], "discriminator": { "propertyName": "state", "mapping": { "ok": "#/components/schemas/Verifications_VerificationStatusOk", "disabled": "#/components/schemas/Verifications_VerificationStatusDisabled", "closed": "#/components/schemas/Verifications_VerificationStatusClosed" } } } }, "required": [ "data" ] }, "examples": { "verification-required": { "summary": "User action is required", "value": { "data": { "state": "disabled", "user_action_required": true, "required_actions": [ { "action_type": "verification", "verification_type": "identity", "reasons": [ "initial_onboarding" ] } ] } } } } } }, "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/VerificationsBadRequestResponse" }, "401": { "$ref": "#/components/responses/VerificationsUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/VerificationsForbiddenResponse" }, "404": { "$ref": "#/components/responses/VerificationsVerificationRequirementsNotFoundResponse" }, "429": { "$ref": "#/components/responses/VerificationsResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/VerificationsInternalResponse" }, "503": { "$ref": "#/components/responses/VerificationsUnavailableResponse" }, "504": { "$ref": "#/components/responses/VerificationsDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X GET \"https://api.sandbox.services.payward.com/v1/users/AA45N8G4MLDYWAR7/verifications/requirements\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\"" } ], "x-speakeasy-mcp": { "readOnlyHint": true, "idempotentHint": true, "destructiveHint": false } } }, "/v1/users/{user_id}/verifications/hosted": { "post": { "operationId": "createHostedVerification", "summary": "Create hosted verification", "tags": [ "Verifications" ], "description": "Create or reuse the hosted verification required for the user.\n\nPWS derives the provider, level, and verification type from the current KYC requirement. The result contains the public verification ID and one or more hosted methods, or `not_required` when the user has no actionable requirement.", "parameters": [ { "$ref": "#/components/parameters/UserId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verifications_HostedVerificationRequest" }, "examples": { "hosted-verification": { "summary": "Start or reuse the required hosted verification", "value": {} } } } } }, "responses": { "200": { "description": "Verification ID and hosted methods returned, or no hosted verification required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verifications_HostedVerificationResponseBody" }, "examples": { "methods": { "summary": "Web and embedded methods are available", "value": { "data": { "verification_id": "PVABCDE-FGHIJ-KLMNOP", "methods": { "web": { "url": "https://in.sumsub.com/websdk/pws-example", "expires_at": "2026-07-29T18:00:00Z" }, "embedded": { "sumsub": { "access_token": "", "user_id": "AA45N8G4MLDYWAR7", "expires_at": "2026-07-29T18:00:00Z" } } } } } }, "not-required": { "summary": "No user-actionable verification is required", "value": { "data": { "not_required": {} } } } } } }, "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/VerificationsBadRequestResponse" }, "401": { "$ref": "#/components/responses/VerificationsUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/VerificationsForbiddenResponse" }, "429": { "$ref": "#/components/responses/VerificationsResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/VerificationsInternalResponse" }, "501": { "$ref": "#/components/responses/VerificationsUnimplementedResponse" }, "503": { "$ref": "#/components/responses/VerificationsUnavailableResponse" }, "504": { "$ref": "#/components/responses/VerificationsDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiTimestamp": [], "ApiSign": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "curl", "source": "curl -X POST \"https://api.sandbox.services.payward.com/v1/users/AA45N8G4MLDYWAR7/verifications/hosted\" \\\n -H \"API-Key: $PWS_API_KEY\" \\\n -H \"API-Timestamp: $PWS_API_TIMESTAMP\" \\\n -H \"API-Sign: $PWS_API_SIGN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" } ], "x-speakeasy-mcp": { "readOnlyHint": false, "idempotentHint": true, "destructiveHint": false } } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "description": "Lists the webhooks registered for the specified account.", "operationId": "listWebhooks", "parameters": [ { "$ref": "#/components/parameters/Webhooks_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Webhooks for the requested page. Always present; serialized as an empty array when the caller has no registered webhooks.", "type": "array", "items": { "description": "A registered webhook destination.", "title": "Webhook", "type": "object", "properties": { "id": { "description": "Stable identifier assigned at creation time. Use this in subsequent Get/Update/Delete calls.", "type": "string" }, "url": { "description": "HTTPS destination URL that the webhook payload will be POSTed to.", "type": "string" }, "description": { "description": "Free-form partner-supplied label. Empty when no description was set.", "type": "string" }, "disabled": { "description": "When true, the webhook is registered but no events are being delivered. Flip to false via UpdateWebhook to resume deliveries.", "type": "boolean" }, "created_at": { "description": "Time at which the webhook was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the webhook was last updated.", "$ref": "#/components/schemas/DateTime" }, "events": { "description": "Events the webhook is subscribed to. Only these events are delivered to the destination URL.", "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Webhooks_WebhookEventType" } } }, "required": [ "id", "url", "description", "disabled", "events" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "list-webhooks-response": { "summary": "List webhooks response", "value": { "data": [ { "id": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5", "url": "https://partner.example.com/hooks/quote", "description": "primary delivery", "disabled": false, "created_at": "2026-05-25T11:30:00Z", "updated_at": "2026-05-25T11:30:00Z", "events": [ "quote.executed", "quote.cancelled" ] } ] } } } } } }, "400": { "$ref": "#/components/responses/WebhooksBadRequestResponse" }, "401": { "$ref": "#/components/responses/WebhooksUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/WebhooksForbiddenResponse" }, "429": { "$ref": "#/components/responses/WebhooksResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/WebhooksInternalResponse" }, "503": { "$ref": "#/components/responses/WebhooksUnavailableResponse" }, "504": { "$ref": "#/components/responses/WebhooksDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List webhooks" }, "post": { "tags": [ "Webhooks" ], "description": "Registers a new webhook destination for the specified account.\n\nThe response carries the signing secret in plaintext. Partners must store it and use it to verify the signature on inbound webhook deliveries. The secret is shown only here at creation time; if it is later lost or compromised, mint a replacement with RotateWebhookSecret (which returns the new secret, also only once).", "operationId": "createWebhook", "requestBody": { "content": { "application/json": { "schema": { "description": "Request to register a new webhook destination.\n\nThe owning tenant is derived from the authenticated caller. There is no account identifier in the request.", "type": "object", "properties": { "url": { "description": "HTTPS destination URL. Must be reachable from the webhooks service and serve a valid TLS certificate.", "type": "string", "minLength": 8, "maxLength": 2048 }, "description": { "description": "Optional free-form label, shown in the operator portal. Max 500 chars.", "type": "string", "maxLength": 500 }, "events": { "description": "Events the webhook should be subscribed to. Required and must be non-empty: partners must opt in explicitly to avoid silent fan-out when new event types are added.", "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Webhooks_WebhookEventType" } }, "disabled": { "description": "Create the webhook in a disabled state. Omit (or pass false) to start delivering immediately; pass true to register the endpoint without delivering any events until it is re-enabled via UpdateWebhook.", "type": "boolean" } }, "required": [ "url", "events" ] }, "examples": { "create-webhook-request": { "summary": "Create webhook request", "value": { "url": "https://partner.example.com/hooks/quote", "description": "primary delivery", "events": [ "quote.executed", "quote.cancelled" ] } } } } }, "required": true }, "responses": { "201": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "description": "Response from CreateWebhook.\n\nThe signing secret is returned in plaintext exactly once. Partners must persist it before discarding the response; it cannot be re-read later.", "type": "object", "properties": { "data": { "description": "Data envelope returned exactly once after a successful CreateWebhook. Mirrors the webhook representation field-for-field and adds the one-time signing secret as a peer field.", "type": "object", "properties": { "id": { "description": "Stable identifier assigned at creation time. Use this in subsequent Get/Update/Delete calls.", "type": "string" }, "url": { "description": "HTTPS destination URL that the webhook payload will be POSTed to.", "type": "string" }, "description": { "description": "Free-form partner-supplied label. Empty when no description was set.", "type": "string" }, "disabled": { "description": "When true, the webhook is registered but no events are being delivered. Flip to false via UpdateWebhook to resume deliveries.", "type": "boolean" }, "created_at": { "description": "Time at which the webhook was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the webhook was last updated.", "$ref": "#/components/schemas/DateTime" }, "signing_secret": { "description": "HMAC-SHA256 signing secret. Partners use this to verify the signature header on every inbound webhook delivery.", "type": "string", "format": "password" }, "events": { "description": "Events the webhook is subscribed to. Mirrors the request's `events` field after server-side normalization.", "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Webhooks_WebhookEventType" } } }, "required": [ "id", "url", "description", "disabled", "signing_secret", "events" ] } }, "required": [ "data" ] }, "examples": { "create-webhook-response": { "summary": "Create webhook response", "value": { "data": { "id": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5", "url": "https://partner.example.com/hooks/quote", "description": "primary delivery", "disabled": false, "created_at": "2026-05-25T11:30:00Z", "updated_at": "2026-05-25T11:30:00Z", "signing_secret": "whsec_7nM1q4bV2jKbMZhYa3sAehO9W8r7QZD2", "events": [ "quote.executed", "quote.cancelled" ] } } } } } } }, "400": { "$ref": "#/components/responses/WebhooksBadRequestResponse" }, "401": { "$ref": "#/components/responses/WebhooksUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/WebhooksForbiddenResponse" }, "429": { "$ref": "#/components/responses/WebhooksResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/WebhooksInternalResponse" }, "503": { "$ref": "#/components/responses/WebhooksUnavailableResponse" }, "504": { "$ref": "#/components/responses/WebhooksDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Create webhook" } }, "/v1/webhooks/{webhook_id}": { "get": { "tags": [ "Webhooks" ], "description": "Retrieves a webhook by id.", "operationId": "getWebhook", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "description": "Identifier returned by CreateWebhook.", "type": "string", "minLength": 1, "maxLength": 64 }, "style": "simple", "example": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A registered webhook destination.", "title": "Webhook", "type": "object", "properties": { "id": { "description": "Stable identifier assigned at creation time. Use this in subsequent Get/Update/Delete calls.", "type": "string" }, "url": { "description": "HTTPS destination URL that the webhook payload will be POSTed to.", "type": "string" }, "description": { "description": "Free-form partner-supplied label. Empty when no description was set.", "type": "string" }, "disabled": { "description": "When true, the webhook is registered but no events are being delivered. Flip to false via UpdateWebhook to resume deliveries.", "type": "boolean" }, "created_at": { "description": "Time at which the webhook was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the webhook was last updated.", "$ref": "#/components/schemas/DateTime" }, "events": { "description": "Events the webhook is subscribed to. Only these events are delivered to the destination URL.", "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Webhooks_WebhookEventType" } } }, "required": [ "id", "url", "description", "disabled", "events" ] } }, "required": [ "data" ] }, "examples": { "get-webhook-response": { "summary": "Get webhook response", "value": { "data": { "id": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5", "url": "https://partner.example.com/hooks/quote", "description": "primary delivery", "disabled": false, "created_at": "2026-05-25T11:30:00Z", "updated_at": "2026-05-25T11:30:00Z", "events": [ "quote.executed", "quote.cancelled" ] } } } } } } }, "400": { "$ref": "#/components/responses/WebhooksBadRequestResponse" }, "401": { "$ref": "#/components/responses/WebhooksUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/WebhooksForbiddenResponse" }, "404": { "description": "Webhook not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_WebhookNotFoundError" }, "examples": { "webhook-not-found": { "summary": "Webhook not found", "value": { "error": { "type": "webhooks_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "webhook_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/WebhooksResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/WebhooksInternalResponse" }, "503": { "$ref": "#/components/responses/WebhooksUnavailableResponse" }, "504": { "$ref": "#/components/responses/WebhooksDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Get webhook" }, "delete": { "tags": [ "Webhooks" ], "description": "Hard-deletes a webhook. The endpoint is removed entirely; future events will not be delivered to its URL and historical delivery attempts are no longer retrievable. To stop deliveries while keeping the audit trail, use UpdateWebhook with `disabled = true`.", "operationId": "deleteWebhook", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "description": "Identifier returned by CreateWebhook.", "type": "string", "minLength": 1, "maxLength": 64 }, "style": "simple", "example": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5" } ], "responses": { "204": { "description": "No Content", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } } }, "400": { "$ref": "#/components/responses/WebhooksBadRequestResponse" }, "401": { "$ref": "#/components/responses/WebhooksUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/WebhooksForbiddenResponse" }, "404": { "description": "Webhook not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_WebhookNotFoundError" }, "examples": { "webhook-not-found": { "summary": "Webhook not found", "value": { "error": { "type": "webhooks_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "webhook_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/WebhooksResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/WebhooksInternalResponse" }, "503": { "$ref": "#/components/responses/WebhooksUnavailableResponse" }, "504": { "$ref": "#/components/responses/WebhooksDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Delete webhook" }, "patch": { "tags": [ "Webhooks" ], "description": "Updates a webhook's mutable fields. Stripe-style partial PATCH: any field omitted from the request body is left unchanged. Use `disabled = true` to soft-disable an endpoint without deleting its delivery history.", "operationId": "updateWebhook", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "description": "Identifier returned by CreateWebhook.", "type": "string", "minLength": 1, "maxLength": 64 }, "style": "simple", "example": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to update a webhook. Stripe-style partial PATCH: omitted fields are left unchanged.\n\nThe owning tenant is derived from the authenticated caller. Only the webhook id and the fields to mutate are supplied.", "type": "object", "properties": { "url": { "description": "New destination URL. Omit to leave unchanged.", "type": "string", "minLength": 8, "maxLength": 2048 }, "description": { "description": "New description. Omit to leave unchanged; pass empty string to clear.", "type": "string", "maxLength": 500 }, "disabled": { "description": "Disable (true) or re-enable (false) deliveries. Omit to leave unchanged.", "type": "boolean" }, "events": { "description": "Replacement set of events the webhook should be subscribed to. Omit to leave unchanged. Empty arrays are treated as omitted; clearing the list is not supported (a webhook with no events cannot receive any deliveries).", "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Webhooks_WebhookEventType" } } } }, "examples": { "update-webhook-request": { "summary": "Update webhook request", "value": { "disabled": true, "events": [ "quote.executed" ] } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "A registered webhook destination.", "title": "Webhook", "type": "object", "properties": { "id": { "description": "Stable identifier assigned at creation time. Use this in subsequent Get/Update/Delete calls.", "type": "string" }, "url": { "description": "HTTPS destination URL that the webhook payload will be POSTed to.", "type": "string" }, "description": { "description": "Free-form partner-supplied label. Empty when no description was set.", "type": "string" }, "disabled": { "description": "When true, the webhook is registered but no events are being delivered. Flip to false via UpdateWebhook to resume deliveries.", "type": "boolean" }, "created_at": { "description": "Time at which the webhook was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the webhook was last updated.", "$ref": "#/components/schemas/DateTime" }, "events": { "description": "Events the webhook is subscribed to. Only these events are delivered to the destination URL.", "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Webhooks_WebhookEventType" } } }, "required": [ "id", "url", "description", "disabled", "events" ] } }, "required": [ "data" ] }, "examples": { "update-webhook-response": { "summary": "Update webhook response", "value": { "data": { "id": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5", "url": "https://partner.example.com/hooks/quote", "description": "primary delivery", "disabled": false, "created_at": "2026-05-25T11:30:00Z", "updated_at": "2026-05-25T11:30:00Z", "events": [ "quote.executed", "quote.cancelled" ] } } } } } } }, "400": { "$ref": "#/components/responses/WebhooksBadRequestResponse" }, "401": { "$ref": "#/components/responses/WebhooksUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/WebhooksForbiddenResponse" }, "404": { "description": "Webhook not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_WebhookNotFoundError" }, "examples": { "webhook-not-found": { "summary": "Webhook not found", "value": { "error": { "type": "webhooks_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "webhook_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/WebhooksResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/WebhooksInternalResponse" }, "503": { "$ref": "#/components/responses/WebhooksUnavailableResponse" }, "504": { "$ref": "#/components/responses/WebhooksDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Update webhook" } }, "/v1/webhooks/{webhook_id}/attempts": { "get": { "tags": [ "Webhooks" ], "description": "Lists delivery attempts made to this webhook, most recent first.\n\nA delivery attempt is one HTTP POST to the webhook's destination URL. Because deliveries are retried on failure, a single emitted event can produce several attempts against the same webhook: the first is `scheduled`, and each subsequent retry is another `scheduled` attempt until the event is delivered or the retry schedule is exhausted; a partner-initiated resend produces a `manual` attempt. Every attempt is listed, so a successful delivery and the failed tries that preceded it all appear as separate entries sharing the same `message_id`.", "operationId": "listWebhookAttempts", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "description": "Identifier returned by CreateWebhook.", "type": "string", "minLength": 1, "maxLength": 64 }, "style": "simple", "example": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5" }, { "$ref": "#/components/parameters/Webhooks_PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Delivery attempts for the requested page, most recent first. Always present; serialized as an empty array when the webhook has no recorded attempts.", "type": "array", "items": { "description": "A single HTTP delivery attempt of one event to one webhook.", "title": "WebhookDeliveryAttempt", "type": "object", "properties": { "id": { "description": "Stable identifier of this attempt.", "type": "string" }, "webhook_id": { "description": "Identifier of the webhook the attempt was delivered to. Matches the `webhook_id` in the request path.", "type": "string" }, "message_id": { "description": "Identifier of the emitted message this attempt tried to deliver. All attempts for the same event (the first delivery and any retries) share this value.", "type": "string" }, "url": { "description": "Destination URL the attempt was POSTed to. Reflects the webhook's URL at the time of the attempt.", "type": "string" }, "status": { "description": "Outcome of the attempt.", "title": "WebhookDeliveryStatus", "type": "string", "enum": [ "success", "pending", "failed", "sending", "canceled" ] }, "response_status_code": { "description": "HTTP status code returned by the destination. `0` when no HTTP response was received (e.g., a timeout or connection error).", "type": "integer", "format": "int32" }, "response_duration_ms": { "description": "Round-trip time of the attempt in milliseconds.", "type": "integer", "format": "int32" }, "trigger_type": { "description": "What caused the attempt (a scheduled delivery/retry or a manual resend).", "title": "WebhookDeliveryTriggerType", "type": "string", "enum": [ "scheduled", "manual" ] }, "timestamp": { "description": "Time at which this delivery attempt occurred.", "$ref": "#/components/schemas/DateTime" }, "event_type": { "description": "Event type of the message this attempt tried to deliver. All attempts for the same `message_id` share it. Absent when the recorded event type is not one of the values below (e.g., an event type retired after the attempt was made).", "$ref": "#/components/schemas/Webhooks_WebhookEventType" } }, "required": [ "id", "webhook_id", "message_id", "url", "status", "response_status_code", "response_duration_ms", "trigger_type" ] } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "data" ] }, "examples": { "list-webhook-attempts-response": { "summary": "List webhook attempts response", "value": { "data": [ { "id": "atmpt_2Z1Tb9zs6F8XUjWk7p7uA9KNdL5", "webhook_id": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5", "message_id": "msg_2YvQ8oP1n5qkqf3mC2vQ7rTxY", "url": "https://partner.example.com/hooks/quote", "status": "success", "response_status_code": 200, "response_duration_ms": 142, "trigger_type": "scheduled", "timestamp": "2026-05-25T11:30:05Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/WebhooksBadRequestResponse" }, "401": { "$ref": "#/components/responses/WebhooksUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/WebhooksForbiddenResponse" }, "404": { "description": "Webhook not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_WebhookNotFoundError" }, "examples": { "webhook-not-found": { "summary": "Webhook not found", "value": { "error": { "type": "webhooks_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "webhook_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/WebhooksResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/WebhooksInternalResponse" }, "503": { "$ref": "#/components/responses/WebhooksUnavailableResponse" }, "504": { "$ref": "#/components/responses/WebhooksDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "List webhook attempts" } }, "/v1/webhooks/{webhook_id}/secret/rotate": { "post": { "tags": [ "Webhooks" ], "description": "Rotates the webhook's signing secret and returns the new value.\n\nThe new secret replaces the previous secret. Deliveries also include a signature made with the old secret during a short grace period so partners can roll the new value out without dropped deliveries. The new signing secret is returned in plaintext exactly once. Partners must persist it and use it to verify the signature on inbound webhook deliveries.", "operationId": "rotateWebhookSecret", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "description": "Identifier returned by CreateWebhook.", "type": "string", "minLength": 1, "maxLength": 64 }, "style": "simple", "example": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "description": "Response from RotateWebhookSecret.\n\nThe new signing secret is returned in plaintext exactly once. Partners must persist it before discarding the response; it cannot be re-read later.", "type": "object", "properties": { "data": { "description": "Data envelope returned exactly once after a successful RotateWebhookSecret.", "type": "object", "properties": { "id": { "description": "Identifier of the webhook whose secret was rotated.", "type": "string" }, "signing_secret": { "description": "The new HMAC-SHA256 signing secret. Partners use this to verify the signature header on every inbound webhook delivery.", "type": "string", "format": "password" } }, "required": [ "id", "signing_secret" ] } }, "required": [ "data" ] }, "examples": { "rotate-webhook-secret-response": { "summary": "Rotate webhook secret response", "value": { "data": { "id": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5", "signing_secret": "whsec_MfJhd2pQ0sZ8nB4vK1xLrT6yWcEa5Ug" } } } } } } }, "400": { "$ref": "#/components/responses/WebhooksBadRequestResponse" }, "401": { "$ref": "#/components/responses/WebhooksUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/WebhooksForbiddenResponse" }, "404": { "description": "Webhook not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_WebhookNotFoundError" }, "examples": { "webhook-not-found": { "summary": "Webhook not found", "value": { "error": { "type": "webhooks_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "webhook_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/WebhooksResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/WebhooksInternalResponse" }, "503": { "$ref": "#/components/responses/WebhooksUnavailableResponse" }, "504": { "$ref": "#/components/responses/WebhooksDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Rotate webhook secret" } }, "/v1/webhooks/{webhook_id}/test": { "post": { "tags": [ "Webhooks" ], "description": "Sends a test event to the webhook.\n\nDelivers an example message of the requested event type to this webhook's destination URL, and only to this webhook, regardless of which other webhooks are subscribed to the same event type. The payload carries representative placeholder values in the exact shape of a real delivery (including the `type` discriminator), and the request is signed with the webhook's signing secret like any other delivery, so partners can exercise their receiving endpoint and signature verification end to end before going live.\n\nThe webhook must be subscribed to `event` (it must appear in the webhook's `events` list); requesting a test for an event the webhook does not subscribe to fails with `400 Bad Request` rather than delivering nothing.", "operationId": "sendWebhookTestEvent", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "description": "Identifier returned by CreateWebhook.", "type": "string", "minLength": 1, "maxLength": 64 }, "style": "simple", "example": "ep_2YuTbBzs6F8XUjWk7p7uA9KNdL5" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Request to send a test event to a webhook.\n\nThe owning tenant is derived from the authenticated caller. Only the webhook id and the event type are supplied.", "type": "object", "properties": { "event": { "description": "Event type to send an example of. The test delivery's payload uses representative placeholder values in the shape of a real event of this type. The `funds.deposit_*`, `funds.withdrawal_held`, `funds.withdrawal_complete`, and `funds.withdrawal_failed` test events include example `amount` and `fee` objects with `asset` and decimal-string `value` fields; the example fee is included when it is zero. In live deliveries, `amount` is included when resolvable and `fee` is included only when fee data is available and resolvable.", "$ref": "#/components/schemas/Webhooks_WebhookEventType" } }, "required": [ "event" ] }, "examples": { "send-webhook-test-event-request": { "summary": "Send webhook test event request", "value": { "event": "quote.executed" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "description": "Response from SendWebhookTestEvent.\n\nA successful response means the test message was accepted for delivery, not that the destination URL has already received it; delivery happens asynchronously with the usual retry schedule.", "type": "object", "properties": { "data": { "description": "Data envelope returned after a successful SendWebhookTestEvent.", "type": "object", "properties": { "message_id": { "description": "Identifier of the test message that was dispatched. Useful when contacting support about a test delivery.", "type": "string" }, "event": { "description": "Event type of the test message. Echoes the request's `event`.", "$ref": "#/components/schemas/Webhooks_WebhookEventType" } }, "required": [ "message_id", "event" ] } }, "required": [ "data" ] }, "examples": { "send-webhook-test-event-response": { "summary": "Send webhook test event response", "value": { "data": { "message_id": "msg_2eZwQqkM3xT5J8vY1bDnA7CfWp0", "event": "quote.executed" } } } } } } }, "400": { "$ref": "#/components/responses/WebhooksBadRequestResponse" }, "401": { "$ref": "#/components/responses/WebhooksUnauthenticatedResponse" }, "403": { "$ref": "#/components/responses/WebhooksForbiddenResponse" }, "404": { "description": "Webhook not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_WebhookNotFoundError" }, "examples": { "webhook-not-found": { "summary": "Webhook not found", "value": { "error": { "type": "webhooks_error", "status": 404, "instance": "req_01H00000000000000000000000", "code": "webhook_not_found" } } } } } } }, "429": { "$ref": "#/components/responses/WebhooksResourceExhaustedResponse" }, "500": { "$ref": "#/components/responses/WebhooksInternalResponse" }, "503": { "$ref": "#/components/responses/WebhooksUnavailableResponse" }, "504": { "$ref": "#/components/responses/WebhooksDeadlineExceededResponse" } }, "security": [ { "ApiKey": [], "ApiSign": [], "ApiTimestamp": [] } ], "summary": "Send webhook test event" } } }, "webhooks": { "quote.executed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookQuoteExecuted", "summary": "Quote executed", "description": "Quote successfully executed against the partner account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_QuoteExecutedPayload" }, "examples": { "canonical": { "summary": "Canonical quote executed payload", "value": { "type": "quote.executed", "quote_id": "BQEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "executed_at": "2025-01-01T00:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "quote.cancelled": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookQuoteCancelled", "summary": "Quote canceled", "description": "Quote canceled before execution.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_QuoteCancelledPayload" }, "examples": { "canonical": { "summary": "Canonical quote canceled payload", "value": { "type": "quote.cancelled", "quote_id": "BQEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "quote.execution_failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookQuoteExecutionFailed", "summary": "Quote execution failed", "description": "Quote execution attempted but failed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_QuoteExecutionFailedPayload" }, "examples": { "canonical": { "summary": "Canonical quote execution failed payload", "value": { "type": "quote.execution_failed", "quote_id": "BQEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "user.closed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookUserClosed", "summary": "User closed", "description": "The user's account was closed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_UserClosedPayload" }, "examples": { "canonical": { "summary": "Canonical user closed payload", "value": { "type": "user.closed", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "user.disabled": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookUserDisabled", "summary": "User disabled", "description": "The user's account became disabled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_UserDisabledPayload" }, "examples": { "canonical": { "summary": "Canonical user disabled payload", "value": { "type": "user.disabled", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "conversion.deposit_completed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookConversionDepositCompleted", "summary": "Conversion deposit completed", "description": "Inbound funds were credited for a conversion transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_ConversionDepositCompletedPayload" }, "examples": { "canonical": { "summary": "Canonical conversion deposit completed payload", "value": { "type": "conversion.deposit_completed", "transaction_id": "87654321-4321-4321-4321-210987654321", "conversion_id": "12345678-1234-1234-1234-123456789012", "user_id": "AA55 N84G QOIR A67A", "status": "converting", "observed_at": "2025-01-01T00:00:01+00:00", "chain_references": { "deposit_txid": "deposit-123" }, "deposit_reference": "IVY-REF-12345", "deposit_amount": "1000.00", "deposit_currency": "USD", "network": "Polygon" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "conversion.deposit_failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookConversionDepositFailed", "summary": "Conversion deposit failed", "description": "The inbound funding leg failed for a conversion transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_ConversionDepositFailedPayload" }, "examples": { "canonical": { "summary": "Canonical conversion deposit failed payload", "value": { "type": "conversion.deposit_failed", "transaction_id": "87654321-4321-4321-4321-210987654321", "conversion_id": "12345678-1234-1234-1234-123456789012", "user_id": "AA55 N84G QOIR A67A", "status": "failed", "observed_at": "2025-01-01T00:00:01+00:00", "chain_references": { "deposit_txid": "deposit-123" }, "error_code": "amount_too_small", "deposit_amount": "10.00", "deposit_currency": "USD" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "conversion.deposit_held": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookConversionDepositHeld", "summary": "Conversion deposit held", "description": "The inbound funding leg is held pending review for a conversion transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_ConversionDepositHeldPayload" }, "examples": { "canonical": { "summary": "Canonical conversion deposit held payload", "value": { "type": "conversion.deposit_held", "transaction_id": "87654321-4321-4321-4321-210987654321", "conversion_id": "12345678-1234-1234-1234-123456789012", "user_id": "AA55 N84G QOIR A67A", "status": "held", "observed_at": "2025-01-01T00:00:01+00:00", "chain_references": { "deposit_txid": "deposit-123" }, "deposit_amount": "1000.00", "deposit_currency": "USD" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "conversion.withdrawal_completed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookConversionWithdrawalCompleted", "summary": "Conversion withdrawal completed", "description": "Outbound settlement completed for a conversion transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_ConversionWithdrawalCompletedPayload" }, "examples": { "canonical": { "summary": "Canonical conversion withdrawal completed payload", "value": { "type": "conversion.withdrawal_completed", "transaction_id": "87654321-4321-4321-4321-210987654321", "conversion_id": "12345678-1234-1234-1234-123456789012", "user_id": "AA55 N84G QOIR A67A", "status": "completed", "observed_at": "2025-01-01T00:00:01+00:00", "chain_references": { "deposit_txid": "deposit-123", "withdraw_txid": "withdraw-456", "blockchain_transaction_id": "0xabc123" }, "withdrawal_amount": "998.50", "withdrawal_currency": "USDC", "network": "Polygon", "destination_address": "0x1234567890abcdef" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "conversion.withdrawal_failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookConversionWithdrawalFailed", "summary": "Conversion withdrawal failed", "description": "The outbound settlement leg failed for a conversion transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_ConversionWithdrawalFailedPayload" }, "examples": { "canonical": { "summary": "Canonical conversion withdrawal failed payload", "value": { "type": "conversion.withdrawal_failed", "transaction_id": "87654321-4321-4321-4321-210987654321", "conversion_id": "12345678-1234-1234-1234-123456789012", "user_id": "AA55 N84G QOIR A67A", "status": "failed", "observed_at": "2025-01-01T00:00:01+00:00", "chain_references": { "deposit_txid": "deposit-123", "withdraw_txid": "withdraw-456" }, "error_code": "wallet_not_whitelisted", "withdrawal_amount": "998.50", "withdrawal_currency": "USDC", "destination_address": "0x1234567890abcdef" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "conversion.quote_execution_failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookConversionQuoteExecutionFailed", "summary": "Conversion quote execution failed", "description": "Quote creation or execution failed for a pre-quote conversion transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_ConversionQuoteExecutionFailedPayload" }, "examples": { "canonical": { "summary": "Canonical conversion quote execution failed payload", "value": { "type": "conversion.quote_execution_failed", "transaction_id": "87654321-4321-4321-4321-210987654321", "conversion_id": "12345678-1234-1234-1234-123456789012", "user_id": "AA55 N84G QOIR A67A", "status": "failed", "observed_at": "2025-01-01T00:00:01+00:00", "chain_references": { "deposit_txid": "deposit-123" }, "error_code": "quote_expired", "source_amount": "1000.00", "source_currency": "USD", "destination_currency": "USDC" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "conversion.travel_rule_blocked": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookConversionTravelRuleBlocked", "summary": "Conversion blocked by Travel Rule", "description": "A pre-trade Travel Rule check blocked the conversion before any quote execution.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_ConversionTravelRuleBlockedPayload" }, "examples": { "canonical": { "summary": "Canonical conversion blocked by travel rule payload", "value": { "type": "conversion.travel_rule_blocked", "transaction_id": "87654321-4321-4321-4321-210987654321", "conversion_id": "12345678-1234-1234-1234-123456789012", "user_id": "AA55 N84G QOIR A67A", "status": "failed", "observed_at": "2025-01-01T00:00:01+00:00", "chain_references": { "deposit_txid": "deposit-123" }, "error_code": "travel_rule_data_missing", "source_amount": "1000.00", "source_currency": "USD", "destination_currency": "USDC" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "conversion.quote_executed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookConversionQuoteExecuted", "summary": "Conversion quote executed", "description": "Quote execution completed for a conversion transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_ConversionQuoteExecutedPayload" }, "examples": { "canonical": { "summary": "Canonical conversion quote executed payload", "value": { "type": "conversion.quote_executed", "transaction_id": "87654321-4321-4321-4321-210987654321", "conversion_id": "12345678-1234-1234-1234-123456789012", "user_id": "AA55 N84G QOIR A67A", "status": "converting", "observed_at": "2025-01-01T00:00:01+00:00", "chain_references": { "deposit_txid": "deposit-123" }, "source_amount": "1000.00", "source_currency": "USD", "destination_amount": "998.50", "destination_currency": "USDC", "quote_id": "BQEXAMPLE1234567", "executed_at": "2025-01-01T00:00:01+00:00", "rate": "0.99850000", "fee": { "amount": "1.50", "currency": "USD", "fee_bps": 15 } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "transaction.swap": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookTransactionSwap", "summary": "Swap transaction changed", "description": "A swap portfolio transaction was created or updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_TransactionSwapPayload" }, "examples": { "canonical": { "summary": "Canonical swap transaction changed payload", "value": { "type": "transaction.swap", "transaction_id": "TXEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "timestamp": "2025-01-01T00:00:01+00:00", "status": "successful", "spend": { "symbol": "USD", "amount": "-10.00" }, "receive": { "symbol": "BTC", "amount": "0.00015" }, "details": { "quote_id": "BQEXAMPLE1234567", "trade_type": "convert" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "transaction.price_trigger_swap": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookTransactionPriceTriggerSwap", "summary": "Price-trigger swap transaction changed", "description": "A price-trigger swap portfolio transaction was created or updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_TransactionPriceTriggerSwapPayload" }, "examples": { "canonical": { "summary": "Canonical price-trigger swap transaction changed payload", "value": { "type": "transaction.price_trigger_swap", "transaction_id": "TXEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "timestamp": "2025-01-01T00:00:01+00:00", "status": "successful", "spend": { "symbol": "USD", "amount": "-10.00" }, "receive": { "symbol": "BTC", "amount": "0.00015" }, "details": { "quote_id": "BQEXAMPLE1234567", "trade_type": "convert" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "transaction.earn_reward": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookTransactionEarnReward", "summary": "Earn reward transaction changed", "description": "An earn-reward portfolio transaction was created or updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_TransactionEarnRewardPayload" }, "examples": { "canonical": { "summary": "Canonical earn reward transaction changed payload", "value": { "type": "transaction.earn_reward", "transaction_id": "TXEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "timestamp": "2025-01-01T00:00:01+00:00", "status": "successful", "receive": { "symbol": "ETH", "amount": "0.00125" }, "details": { "strategy_id": "STRATEGY-EXAMPLE", "reward_id": "REWARD-EXAMPLE" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "transaction.deposit": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookTransactionDeposit", "summary": "Deposit transaction changed", "description": "A deposit portfolio transaction was created or updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_TransactionDepositPayload" }, "examples": { "canonical": { "summary": "Canonical deposit transaction changed payload", "value": { "type": "transaction.deposit", "transaction_id": "TXEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "timestamp": "2025-01-01T00:00:01+00:00", "status": "successful", "receive": { "symbol": "ETH", "amount": "0.0100" }, "reference": { "kind": "funding", "id": "FTEXAMPLE1234567" }, "details": { "crypto_transaction_id": "0xabc123" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "transaction.withdrawal": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookTransactionWithdrawal", "summary": "Withdrawal transaction changed", "description": "A withdrawal portfolio transaction was created or updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_TransactionWithdrawalPayload" }, "examples": { "canonical": { "summary": "Canonical withdrawal transaction changed payload", "value": { "type": "transaction.withdrawal", "transaction_id": "TXEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "timestamp": "2025-01-01T00:00:01+00:00", "status": "in_progress", "spend": { "symbol": "ETH", "amount": "-0.0001" }, "reference": { "kind": "funding", "id": "FTEXAMPLE1234567" }, "details": { "crypto_transaction_id": "0xabc123" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "transaction.transfer": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookTransactionTransfer", "summary": "Transfer transaction changed", "description": "A transfer portfolio transaction was created or updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_TransactionTransferPayload" }, "examples": { "canonical": { "summary": "Canonical transfer transaction changed payload", "value": { "type": "transaction.transfer", "transaction_id": "TXEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "timestamp": "2025-01-01T00:00:01+00:00", "status": "in_progress", "spend": { "symbol": "USD", "amount": "-0.01" }, "reference": { "kind": "transfer", "id": "TFEXAMPLE1234567" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "transaction.recurring_swap": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookTransactionRecurringSwap", "summary": "Recurring swap transaction changed", "description": "A recurring swap portfolio transaction was created or updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_TransactionRecurringSwapPayload" }, "examples": { "canonical": { "summary": "Canonical recurring swap transaction changed payload", "value": { "type": "transaction.recurring_swap", "transaction_id": "TXEXAMPLE1234567", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "timestamp": "2025-01-01T00:00:01+00:00", "status": "successful", "spend": { "symbol": "USD", "amount": "-10.00" }, "receive": { "symbol": "BTC", "amount": "0.00015" }, "details": { "quote_id": "BQEXAMPLE1234567", "trade_type": "convert" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "funds.deposit_received": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookFundsDepositReceived", "summary": "Deposit received", "description": "A deposit was received and is awaiting confirmations or checks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_FundsDepositReceivedPayload" }, "examples": { "canonical": { "summary": "Canonical deposit received payload", "value": { "type": "funds.deposit_received", "transaction_id": "FRABCDEF123456", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "amount": { "asset": "USD", "value": "100.00" }, "fee": { "asset": "USD", "value": "0" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "funds.deposit_held": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookFundsDepositHeld", "summary": "Deposit held", "description": "A deposit is held pending review or additional checks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_FundsDepositHeldPayload" }, "examples": { "canonical": { "summary": "Canonical deposit held payload", "value": { "type": "funds.deposit_held", "transaction_id": "FRABCDEF123456", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "amount": { "asset": "USD", "value": "100.00" }, "fee": { "asset": "USD", "value": "0" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "funds.deposit_credited": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookFundsDepositCredited", "summary": "Deposit credited", "description": "A deposit was credited and can now be used.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_FundsDepositCreditedPayload" }, "examples": { "canonical": { "summary": "Canonical deposit credited payload", "value": { "type": "funds.deposit_credited", "transaction_id": "FRABCDEF123456", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "amount": { "asset": "USD", "value": "100.00" }, "fee": { "asset": "USD", "value": "0" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "funds.deposit_returned": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookFundsDepositReturned", "summary": "Deposit returned", "description": "A deposit was returned to its source.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_FundsDepositReturnedPayload" }, "examples": { "canonical": { "summary": "Canonical deposit returned payload", "value": { "type": "funds.deposit_returned", "transaction_id": "FRABCDEF123456", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "amount": { "asset": "USD", "value": "100.00" }, "fee": { "asset": "USD", "value": "0" }, "reason": "account_details_mismatch" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "funds.deposit_failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookFundsDepositFailed", "summary": "Deposit failed", "description": "A deposit failed and will not be credited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_FundsDepositFailedPayload" }, "examples": { "canonical": { "summary": "Canonical deposit failed payload", "value": { "type": "funds.deposit_failed", "transaction_id": "FRABCDEF123456", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "amount": { "asset": "USD", "value": "100.00" }, "fee": { "asset": "USD", "value": "0" }, "reason": "duplicate" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "funds.withdrawal_held": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookFundsWithdrawalHeld", "summary": "Withdrawal held", "description": "A withdrawal is held pending review or additional checks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_FundsWithdrawalHeldPayload" }, "examples": { "canonical": { "summary": "Canonical withdrawal held payload", "value": { "type": "funds.withdrawal_held", "transaction_id": "FWABCDEF123456", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "amount": { "asset": "USD", "value": "100.00" }, "fee": { "asset": "USD", "value": "0" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "funds.withdrawal_complete": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookFundsWithdrawalComplete", "summary": "Withdrawal complete", "description": "A withdrawal completed successfully.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_FundsWithdrawalCompletePayload" }, "examples": { "canonical": { "summary": "Canonical withdrawal complete payload", "value": { "type": "funds.withdrawal_complete", "transaction_id": "FWABCDEF123456", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "amount": { "asset": "USD", "value": "100.00" }, "fee": { "asset": "USD", "value": "0" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "funds.withdrawal_failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookFundsWithdrawalFailed", "summary": "Withdrawal failed", "description": "A withdrawal failed and will not be completed. Canceled withdrawals are excluded.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_FundsWithdrawalFailedPayload" }, "examples": { "canonical": { "summary": "Canonical withdrawal failed payload", "value": { "type": "funds.withdrawal_failed", "transaction_id": "FWABCDEF123456", "user_id": "AA55 N84G QOIR A67A", "account_id": "WCQY T95Y CUL2 A7NX", "amount": { "asset": "USD", "value": "100.00" }, "fee": { "asset": "USD", "value": "0" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "verification.requirements_updated": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookVerificationRequirementsUpdated", "summary": "Verification requirements updated", "description": "The user's verification requirements changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_VerificationRequirementsUpdatedPayload" }, "examples": { "canonical": { "summary": "Canonical verification requirements updated payload", "value": { "type": "verification.requirements_updated", "user_id": "AA55 N84G QOIR A67A" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "verification.updated": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookVerificationUpdated", "summary": "Verification updated", "description": "A verification's status changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_VerificationUpdatedPayload" }, "examples": { "canonical": { "summary": "Canonical verification updated payload", "value": { "type": "verification.updated", "user_id": "AA55 N84G QOIR A67A", "verification_id": "PVB4JCW-JPFXQ-AGNISI" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "price_trigger_swap.executed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookPriceTriggerSwapExecuted", "summary": "Price-trigger swap executed", "description": "A price-trigger swap executed successfully after its price condition was met.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapExecutedPayload" }, "examples": { "canonical": { "summary": "Canonical price-trigger swap executed payload", "value": { "type": "price_trigger_swap.executed", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00", "requested": { "trade": { "from": { "symbol": "USD", "amount": "100.00" }, "to": { "symbol": "BTC" } }, "when": { "base": { "symbol": "BTC" }, "quote": { "symbol": "USD" }, "drops_to": "50000.00" } }, "executed": { "quote_id": "BQEXAMPLE1234567", "from": { "symbol": "USD", "amount": "100.00" }, "to": { "symbol": "BTC", "amount": "0.002" }, "fee": { "symbol": "USD", "amount": "1.50" }, "rate": { "symbol": "USD", "amount": "50000.00" }, "executed_at": "2025-01-01T00:00:01+00:00" } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "price_trigger_swap.execution_failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookPriceTriggerSwapExecutionFailed", "summary": "Price-trigger swap execution failed", "description": "A price-trigger swap execution was attempted but failed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapExecutionFailedPayload" }, "examples": { "canonical": { "summary": "Canonical price-trigger swap execution failed payload", "value": { "type": "price_trigger_swap.execution_failed", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00", "failure_reason": "insufficient_funds" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "price_trigger_swap.cancelled": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookPriceTriggerSwapCancelled", "summary": "Price-trigger swap canceled", "description": "A price-trigger swap was canceled before or during execution.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapCancelledPayload" }, "examples": { "canonical": { "summary": "Canonical price-trigger swap canceled payload", "value": { "type": "price_trigger_swap.cancelled", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "price_trigger_swap.created": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookPriceTriggerSwapCreated", "summary": "Price-trigger swap created", "description": "A price-trigger swap was created and is waiting for its price condition.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapCreatedPayload" }, "examples": { "canonical": { "summary": "Canonical price-trigger swap created payload", "value": { "type": "price_trigger_swap.created", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00", "requested": { "trade": { "from": { "symbol": "USD", "amount": "100.00" }, "to": { "symbol": "BTC" } }, "when": { "base": { "symbol": "BTC" }, "quote": { "symbol": "USD" }, "drops_to": "50000.00" } } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "price_trigger_swap.failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookPriceTriggerSwapFailed", "summary": "Price-trigger swap failed", "description": "A price-trigger swap reached a terminal failure state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapFailedPayload" }, "examples": { "canonical": { "summary": "Canonical price-trigger swap failed payload", "value": { "type": "price_trigger_swap.failed", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00", "failure_reason": "other" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "recurring_swap.created": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookRecurringSwapCreated", "summary": "Recurring swap created", "description": "A recurring swap was created and will submit trades on its requested schedule.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_RecurringSwapCreatedPayload" }, "examples": { "canonical": { "summary": "Canonical recurring swap created payload", "value": { "type": "recurring_swap.created", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00", "trade": { "from": { "symbol": "USD", "amount": "100.00" }, "to": { "symbol": "BTC" } }, "schedule": { "interval": "week", "starts_at": "2025-01-01T00:00:00+00:00", "timezone_offset_minutes": 0 } } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "recurring_swap.executed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookRecurringSwapExecuted", "summary": "Recurring swap executed", "description": "An occurrence of a recurring swap executed successfully. The schedule remains active for subsequent occurrences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_RecurringSwapExecutedPayload" }, "examples": { "canonical": { "summary": "Canonical recurring swap executed payload", "value": { "type": "recurring_swap.executed", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00", "trade": { "from": { "symbol": "USD", "amount": "100.00" }, "to": { "symbol": "BTC" } }, "schedule": { "interval": "week", "starts_at": "2025-01-01T00:00:00+00:00", "timezone_offset_minutes": 0 }, "executed": { "quote_id": "BQEXAMPLE1234567", "from": { "symbol": "USD", "amount": "100.00" }, "to": { "symbol": "BTC", "amount": "0.002" }, "fee": { "symbol": "USD", "amount": "1.50" }, "rate": { "symbol": "USD", "amount": "50000.00" }, "executed_at": "2025-01-01T00:00:01+00:00" }, "occurrence_id": "OCCURRENCE-EXAMPLE-1" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "recurring_swap.execution_failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookRecurringSwapExecutionFailed", "summary": "Recurring swap execution failed", "description": "An occurrence of a recurring swap failed. This event does not mean the schedule has stopped; a terminal failure is reported separately by recurring_swap.failed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_RecurringSwapExecutionFailedPayload" }, "examples": { "canonical": { "summary": "Canonical recurring swap execution failed payload", "value": { "type": "recurring_swap.execution_failed", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00", "failure_reason": "insufficient_funds", "occurrence_id": "OCCURRENCE-EXAMPLE-1" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "recurring_swap.cancelled": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookRecurringSwapCancelled", "summary": "Recurring swap canceled", "description": "A recurring swap was canceled at the user’s request and will submit no further occurrences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_RecurringSwapCancelledPayload" }, "examples": { "canonical": { "summary": "Canonical recurring swap canceled payload", "value": { "type": "recurring_swap.cancelled", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "recurring_swap.failed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookRecurringSwapFailed", "summary": "Recurring swap failed", "description": "A recurring swap stopped permanently after a failure and will submit no further occurrences.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_RecurringSwapFailedPayload" }, "examples": { "canonical": { "summary": "Canonical recurring swap failed payload", "value": { "type": "recurring_swap.failed", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00", "failure_reason": "other" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "recurring_swap.paused": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookRecurringSwapPaused", "summary": "Recurring swap paused", "description": "A recurring swap was paused. Its schedule is retained, but occurrences will not run until it is resumed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_RecurringSwapPausedPayload" }, "examples": { "canonical": { "summary": "Canonical recurring swap paused payload", "value": { "type": "recurring_swap.paused", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } }, "recurring_swap.resumed": { "post": { "security": [], "tags": [ "Webhooks" ], "operationId": "webhookRecurringSwapResumed", "summary": "Recurring swap resumed", "description": "A recurring swap was resumed and will submit trades on its schedule again.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks_RecurringSwapResumedPayload" }, "examples": { "canonical": { "summary": "Canonical recurring swap resumed payload", "value": { "type": "recurring_swap.resumed", "id": "A3QBMX-O6RLF-UTVGNA", "client_order_id": "CLIENT-ORDER-EXAMPLE", "user_id": "AA55 N84G QOIR A67A", "timestamp": "2025-01-01T00:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Delivery endpoint accepted the webhook." } } } } }, "components": { "examples": { "assets-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "country", "message": "must be a valid ISO 3166-1 alpha-2 country code" } ] } } }, "assets-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 401, "code": "unauthenticated" } } }, "assets-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "assets-not-found": { "summary": "Resource not found", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "not_found" } } }, "assets-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 429, "code": "resource_exhausted" } } }, "assets-internal": { "summary": "Internal server error", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 500, "code": "internal" } } }, "assets-unimplemented": { "summary": "Operation is not implemented", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 501, "code": "unimplemented" } } }, "assets-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 503, "code": "unavailable" } } }, "assets-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "assets_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 504, "code": "deadline_exceeded" } } }, "conversions-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "account_id", "message": "must be a valid account identifier" } ] } } }, "conversions-invalid-withdrawal-address": { "summary": "Invalid withdrawal address", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "conversion_invalid_withdrawal_address", "causes": [ { "field": "to.bank_account.bic", "message": "is required for SEPA withdrawals" } ] } } }, "conversions-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 401, "code": "unauthenticated" } } }, "conversions-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "conversions-not-found": { "summary": "Conversion resource not found", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "not_found" } } }, "conversions-idempotency-key-already-used": { "summary": "Idempotency key already used", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "idempotency_key_already_used" }, "conversion_id": "00000000-0000-0000-0000-000000000001" } }, "conversions-insufficient-funds": { "summary": "Insufficient funds", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "conversion_insufficient_funds" } } }, "conversions-address-ownership-verification-required": { "summary": "Address ownership verification required", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "conversion_address_ownership_verification_required" } } }, "conversions-withdrawal-method-unavailable": { "summary": "Withdrawal method unavailable", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "conversion_withdrawal_method_unavailable" } } }, "conversions-on-demand-already-executed": { "summary": "Already executed", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "conversion_already_executed" } } }, "conversions-on-demand-canceled": { "summary": "Conversion canceled", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 410, "code": "conversion_canceled" } } }, "conversions-on-demand-prepare-limit-reached": { "summary": "Prepare limit reached", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "conversion_prepare_limit_reached" } } }, "conversions-conversion-limit-reached": { "summary": "Conversion limit reached", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "conversion_limit_reached" } } }, "conversions-rule-already-deleted": { "summary": "Conversion rule already deleted", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "rule_already_deleted" } } }, "conversions-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 429, "code": "resource_exhausted" } } }, "conversions-internal": { "summary": "Internal server error", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 500, "code": "internal" } } }, "conversions-unimplemented": { "summary": "Operation not implemented", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 501, "code": "unimplemented" } } }, "conversions-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 503, "code": "unavailable" } } }, "conversions-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "conversions_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 504, "code": "deadline_exceeded" } } }, "earn-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 400, "code": "bad_request", "causes": [ { "field": "account_id", "message": "must be a valid account identifier" } ] } } }, "earn-not-eligible": { "summary": "Account not eligible", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 403, "code": "not_eligible", "causes": [ { "field": "yield_source", "message": "Account is not eligible for auto earn yield source: Staking" } ] } } }, "earn-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 401, "code": "unauthenticated" } } }, "earn-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 403, "code": "forbidden" } } }, "earn-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 429, "code": "resource_exhausted" } } }, "earn-internal": { "summary": "Internal error", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 500, "code": "internal" } } }, "earn-service-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 503, "code": "unavailable" } } }, "earn-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 504, "code": "deadline_exceeded" } } }, "bonded-earn-not-found": { "summary": "Strategy or request not found", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 404, "code": "not_found" } } }, "bonded-earn-not-enabled": { "summary": "Bonded Earn not enabled", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 404, "code": "not_found" } } }, "bonded-earn-insufficient-balance": { "summary": "Balance does not cover the amount", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 400, "code": "insufficient_balance", "causes": [ { "field": "amount", "message": "Not enough funds to deallocate" } ] } } }, "bonded-earn-amount-too-high": { "summary": "Amount too large to represent", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 400, "code": "amount_too_high", "causes": [ { "field": "amount", "message": "The amount is outside the range that can be processed" } ] } } }, "bonded-earn-strategy-not-found": { "summary": "Strategy not found", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 404, "code": "strategy_not_found" } } }, "bonded-earn-idempotency-key-reused": { "summary": "Idempotency key reused for a different request", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 409, "code": "idempotency_key_reused", "causes": [ { "field": "idempotency_key", "message": "Idempotency key already used for a different request" } ] } } }, "bonded-earn-allocation-in-progress": { "summary": "Another request is running on the strategy", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 409, "code": "allocation_in_progress", "causes": [ { "field": "request", "message": "Another allocation is already running on this strategy" } ] } } }, "bonded-earn-request-conflict": { "summary": "Request conflicts with an existing request", "value": { "error": { "type": "earn_error", "instance": "req_01H00000000000000000000000", "status": 409, "code": "request_conflict" } } }, "funding-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "asset_symbol", "message": "must contain between 1 and 16 characters" } ] } } }, "funding-create-address-invalid-scope": { "summary": "Invalid funding address scope", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "scope", "message": "must name exactly one method or network" } ] } } }, "funding-create-address-invalid-details": { "summary": "Invalid funding address details", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "address_details", "message": "must contain exactly one fiat or crypto address" } ] } } }, "funding-create-address-invalid-name": { "summary": "Invalid funding address name", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "name", "message": "must not be empty or contain only whitespace" } ] } } }, "funding-update-address-invalid-name": { "summary": "Invalid funding address name", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "name", "message": "must not be empty or contain only whitespace" } ] } } }, "funding-update-address-account-settings": { "summary": "Account settings prevent address changes", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request" } } }, "funding-deposit-activation-invalid-method-id": { "summary": "Invalid deposit method identifier", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "method_id", "message": "must be a valid deposit funding method identifier" } ] } } }, "funding-deposit-activation-insufficient-documentation": { "summary": "Account documentation is insufficient", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "account_id", "message": "Account documentation is insufficient to activate this deposit method (missing requirement: address)" } ] } } }, "funding-invalid-transfer": { "summary": "Transfer request cannot be processed", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "transfer", "message": "Transfer request cannot be processed" } ] } } }, "funding-stale-conversion-rate": { "summary": "Transfer conversion rate is stale", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "stale_conversion_rate" } } }, "funding-self-transfer": { "summary": "Source and recipient are the same account", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "to", "message": "Transfers from and to the same account are not supported" } ] } } }, "funding-unsupported-asset": { "summary": "Unsupported asset", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "asset", "message": "Unsupported asset" } ] } } }, "funding-insufficient-balance": { "summary": "Insufficient balance", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "Insufficient balance" } ] } } }, "funding-derivative-transfer-unsupported-asset": { "summary": "Unsupported derivatives transfer asset", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a1e-2c3f4a5b6c7d", "status": 400, "code": "bad_request", "causes": [ { "field": "asset", "message": "is not supported for futures transfers" } ] } } }, "funding-derivative-transfer-insufficient-balance": { "summary": "Insufficient spot balance", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a2e-3c4f5a6b7c8d", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "exceeds the available balance" } ] } } }, "funding-derivative-transfer-insufficient-futures-balance": { "summary": "Insufficient futures balance available for transfer", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a2f-3c4f5a6b7c8d", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "exceeds the futures balance available for transfer" } ] } } }, "funding-derivative-transfer-futures-unavailable": { "summary": "No eligible futures destination balance", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a30-3c4f5a6b7c8d", "status": 400, "code": "bad_request", "causes": [ { "field": "to", "message": "is unavailable because the account owner has no eligible futures balance" } ] } } }, "funding-derivative-transfer-rejected": { "summary": "Futures transfer rejected", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a2f-3c4f5a6b7c8d", "status": 400, "code": "bad_request", "causes": [ { "field": "transfer", "message": "cannot be completed for the selected futures balance" } ] } } }, "funding-derivative-transfer-invalid-direction": { "summary": "Source and destination select the same balance", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a2f-3c4f5a6b7c8d", "status": 400, "code": "bad_request", "causes": [ { "field": "from", "message": "must form either the `spot` to `futures` or `futures` to `spot` route" } ] } } }, "funding-derivative-transfer-amount-too-small": { "summary": "Amount below the derivatives transfer minimum", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a3e-4d5e6f7a8b9c", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "is below the minimum for this transfer method" } ] } } }, "funding-derivative-transfer-account-not-found": { "summary": "Derivatives transfer account not found", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a4e-5f6a7b8c9d0e", "status": 404, "code": "not_found" } } }, "funding-lightning-amount-too-small": { "summary": "Amount below the Lightning deposit minimum", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "Amount is below the minimum for Lightning deposits" } ] } } }, "funding-lightning-amount-too-large": { "summary": "Amount above the Lightning deposit maximum", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "Amount is above the maximum for Lightning deposits" } ] } } }, "funding-lightning-unsupported-asset": { "summary": "Asset not supported for Lightning deposits", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "asset_symbol", "message": "Asset is not supported for Lightning deposits" } ] } } }, "funding-withdrawal-invalid-amount": { "summary": "Invalid request", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "must be a positive decimal amount" } ] } } }, "funding-withdrawal-insufficient-funds": { "summary": "Insufficient balance", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "exceeds the available balance" } ] } } }, "funding-withdrawal-amount-too-small": { "summary": "Amount below the withdrawal minimum", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "is below the minimum for this method" } ] } } }, "funding-withdrawal-incompatible-address": { "summary": "Address is not compatible with the method", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "destination", "message": "must identify a destination compatible with the withdrawal method" } ] } } }, "funding-withdrawal-unsupported-asset": { "summary": "Unsupported withdrawal asset", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "symbol", "message": "is not supported for withdrawals" } ] } } }, "funding-withdrawal-fee-quote-invalid-method": { "summary": "Invalid funding method identifier", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "method_id", "message": "must identify a funding method that supports fee quotes" } ] } } }, "funding-withdrawal-fee-quote-invalid-amount": { "summary": "Invalid quote amount", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "must be a positive decimal amount" } ] } } }, "funding-withdrawal-invalid-fee-token": { "summary": "Invalid withdrawal fee token", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "fee_token", "message": "must be a valid withdrawal fee quote token" } ] } } }, "funding-withdrawal-fee-token-network-scope": { "summary": "Fee token used with network scope", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "scope", "message": "must use method_id when fee_token is supplied" } ] } } }, "funding-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 401, "code": "unauthenticated" } } }, "funding-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "funding-update-address-read-only": { "summary": "Funding address cannot be changed", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "funding-not-found": { "summary": "Funding address not found", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "not_found" } } }, "funding-method-not-found": { "summary": "Funding method not found", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "not_found" } } }, "funding-idempotency-conflict": { "summary": "Idempotency key conflict", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "idempotency_conflict" } } }, "funding-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 429, "code": "resource_exhausted" } } }, "funding-internal": { "summary": "Internal server error", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 500, "code": "internal" } } }, "funding-unimplemented": { "summary": "Operation not implemented", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 501, "code": "unimplemented" } } }, "funding-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 503, "code": "unavailable" } } }, "funding-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "funding_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 504, "code": "deadline_exceeded" } } }, "portfolio-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "portfolio_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "account_id", "message": "must be a valid account identifier" } ] } } }, "portfolio-invalid-reference": { "summary": "Invalid transaction reference", "value": { "error": { "type": "portfolio_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "references[0].id", "message": "Must be a valid reference identifier for the selected kind" } ] } } }, "portfolio-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "portfolio_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 401, "code": "unauthenticated" } } }, "portfolio-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "portfolio_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "portfolio-not-found": { "summary": "Resource not found", "value": { "error": { "type": "portfolio_error", "status": 404, "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "code": "not_found" } } }, "portfolio-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "portfolio_error", "status": 429, "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "code": "resource_exhausted" } } }, "portfolio-internal": { "summary": "Internal server error", "value": { "error": { "type": "portfolio_error", "status": 500, "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "code": "internal" } } }, "portfolio-unimplemented": { "summary": "Operation is not implemented", "value": { "error": { "type": "portfolio_error", "status": 501, "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "code": "unimplemented" } } }, "portfolio-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "portfolio_error", "status": 503, "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "code": "unavailable" } } }, "portfolio-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "portfolio_error", "status": 504, "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "code": "deadline_exceeded" } } }, "reports-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "reports_error", "instance": "req_01H00000000000000000000000", "status": 400, "code": "bad_request", "causes": [ { "field": "page_size", "message": "must be between 1 and 25" } ] } } }, "reports-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "reports_error", "instance": "req_01H00000000000000000000000", "status": 401, "code": "unauthenticated" } } }, "reports-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "reports_error", "instance": "req_01H00000000000000000000000", "status": 403, "code": "forbidden" } } }, "reports-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "reports_error", "instance": "req_01H00000000000000000000000", "status": 429, "code": "resource_exhausted" } } }, "reports-internal": { "summary": "Internal error", "value": { "error": { "type": "reports_error", "instance": "req_01H00000000000000000000000", "status": 500, "code": "internal" } } }, "reports-unimplemented": { "summary": "Operation is not implemented", "value": { "error": { "type": "reports_error", "instance": "req_01H00000000000000000000000", "status": 501, "code": "unimplemented" } } }, "reports-service-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "reports_error", "instance": "req_01H00000000000000000000000", "status": 503, "code": "unavailable" } } }, "reports-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "reports_error", "instance": "req_01H00000000000000000000000", "status": 504, "code": "deadline_exceeded" } } }, "swap-quote-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "account_id", "message": "must be a valid account identifier" } ] } } }, "swap-onchain-quote-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "account_id", "message": "must be a valid account identifier" } ] } } }, "swap-price-trigger-swap-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "account_id", "message": "must be a valid account identifier" } ] } } }, "swap-quote-validation": { "summary": "Quote request validation failed", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "Exactly one of from.amount or to.amount must be set, but both were provided" } ] } } }, "swap-quote-amount-too-small": { "summary": "Quote amount is below the minimum", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "quote_amount_too_small", "causes": [ { "field": "amount", "message": "Requested amount is below the supported minimum.", "symbol": "USD", "minimum": "10.00" } ] } } }, "swap-quote-amount-too-large": { "summary": "Quote amount exceeds the maximum", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "quote_amount_too_large", "causes": [ { "field": "amount", "message": "Requested amount exceeds the supported maximum.", "symbol": "USD", "maximum": "100000.00" } ] } } }, "swap-quote-amount-precision-too-high": { "summary": "Quote amount has too many decimal places", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "quote_amount_precision_too_high", "causes": [ { "field": "amount", "message": "Requested amount precision exceeds the supported maximum.", "precision": 4, "maximum_precision": 2 } ] } } }, "swap-total-margin-too-low": { "summary": "Requested margin is below the minimum", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "total_margin_too_low", "causes": [ { "field": "fee", "message": "Requested total margin is below the supported minimum.", "requested_margin_bps": "50", "minimum_margin_bps": "100" } ] } } }, "swap-total-margin-too-high": { "summary": "Requested margin exceeds the maximum", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "total_margin_too_high", "causes": [ { "field": "fee", "message": "Requested total margin exceeds the supported maximum.", "requested_margin_bps": "2549", "maximum_margin_bps": "1000" } ] } } }, "swap-onchain-quote-validation": { "summary": "Onchain quote request validation failed", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "to.amount", "message": "must match pattern \"^[0-9]+(\\.[0-9]+)?$\"" } ] } } }, "swap-price-trigger-swap-validation": { "summary": "Price-triggered swap request validation failed", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "amount", "message": "Exactly one of from.amount or to.amount must be set, but neither was provided" } ] } } }, "swap-quote-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 401, "code": "unauthenticated" } } }, "swap-onchain-quote-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 401, "code": "unauthenticated" } } }, "swap-price-trigger-swap-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 401, "code": "unauthenticated" } } }, "swap-quote-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "swap-onchain-quote-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "swap-price-trigger-swap-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "swap-quote-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 429, "code": "resource_exhausted" } } }, "swap-onchain-quote-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 429, "code": "resource_exhausted" } } }, "swap-price-trigger-swap-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 429, "code": "resource_exhausted" } } }, "swap-quote-internal": { "summary": "Internal error", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 500, "code": "internal" } } }, "swap-onchain-quote-internal": { "summary": "Internal error", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 500, "code": "internal" } } }, "swap-price-trigger-swap-internal": { "summary": "Internal error", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 500, "code": "internal" } } }, "swap-quote-service-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 503, "code": "unavailable" } } }, "swap-onchain-quote-service-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 503, "code": "unavailable" } } }, "swap-price-trigger-swap-service-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 503, "code": "unavailable" } } }, "swap-quote-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 504, "code": "deadline_exceeded" } } }, "swap-onchain-quote-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 504, "code": "deadline_exceeded" } } }, "swap-price-trigger-swap-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 504, "code": "deadline_exceeded" } } }, "swap-quote-insufficient-liquidity": { "summary": "Insufficient liquidity", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "insufficient_liquidity" } } }, "swap-quote-not-found": { "summary": "Quote not found", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "quote_not_found" } } }, "swap-onchain-quote-not-found": { "summary": "Onchain quote not found", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "quote_not_found" } } }, "swap-price-trigger-swap-not-found": { "summary": "Price-triggered swap not found", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "price_trigger_swap_not_found" } } }, "swap-insufficient-funds": { "summary": "Insufficient funds", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "insufficient_funds" } } }, "swap-quote-cancelled": { "summary": "Quote was canceled", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "quote_cancelled", "causes": [ { "field": "quote_id", "message": "The quote was cancelled.", "reason": "market_moved" } ] } } }, "swap-quote-execution-failed": { "summary": "Quote execution failed", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "quote_execution_failed" } } }, "swap-insufficient-margin": { "summary": "Insufficient margin", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "insufficient_margin" } } }, "swap-acquisition-limit-exceeded": { "summary": "Acquisition limit exceeded", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "acquisition_limit_exceeded" } } }, "swap-suitability-limit-exceeded": { "summary": "Suitability limit exceeded", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "suitability_limit_exceeded" } } }, "swap-pattern-day-trading-protection": { "summary": "Pattern day trading protection applied", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "pattern_day_trading_protection" } } }, "swap-potential-wash-trade": { "summary": "Potential wash trade detected", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "potential_wash_trade" } } }, "swap-sell-only-asset": { "summary": "Asset is sell-only", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "sell_only_asset", "causes": [ { "field": "symbol", "message": "The asset is currently sell-only.", "symbol": "TSLAx" } ] } } }, "swap-fractional-extended-hours": { "summary": "Fractional trading is unavailable during extended hours", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "fractional_extended_hours" } } }, "swap-ipo-asset": { "summary": "Asset is in its initial public offering period", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "ipo_asset", "causes": [ { "field": "symbol", "message": "The asset is in its initial public offering period.", "symbol": "TSLAx" } ] } } }, "swap-otc-regular-hours-only": { "summary": "OTC asset can only be traded during regular market hours", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "otc_regular_hours_only" } } }, "swap-otc-sell-only": { "summary": "OTC asset is sell-only", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "otc_sell_only", "causes": [ { "field": "symbol", "message": "The OTC asset is currently sell-only.", "symbol": "ABC" } ] } } }, "swap-equity-market-closed": { "summary": "Equity market is closed", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "equity_market_closed" } } }, "swap-illegal-order-type-after-hours": { "summary": "Order type is unavailable outside regular market hours", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "illegal_order_type_after_hours" } } }, "swap-price-trigger-swap-not-cancellable": { "summary": "Price-triggered swap not cancelable", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "price_trigger_swap_not_cancellable" } } }, "swap-price-trigger-swap-client-order-id-duplicate": { "summary": "Price-triggered swap client order id already in use", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "price_trigger_swap_client_order_id_duplicate" } } }, "swap-price-trigger-swap-target-price-already-available": { "summary": "Price-triggered swap target price already available", "value": { "error": { "type": "price_trigger_swap_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 412, "code": "price_trigger_swap_target_price_already_available" } } }, "swap-quote-expired": { "summary": "Quote expired", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 410, "code": "quote_expired" } } }, "swap-onchain-execution-unsupported": { "summary": "Onchain quote cannot be executed here", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "onchain_execution_unsupported" } } }, "swap-onchain-trade-locked": { "summary": "Trade is locked", "value": { "error": { "type": "onchain_quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "trade_locked" } } }, "swap-quote-trade-locked": { "summary": "Trade is locked", "value": { "error": { "type": "quote_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "trade_locked" } } }, "travel-rule-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 400, "code": "bad_request", "causes": [ { "field": "address", "message": "must be a valid address for the selected network" } ] } } }, "travel-rule-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 401, "code": "unauthenticated" } } }, "travel-rule-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 403, "code": "forbidden" } } }, "travel-rule-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 429, "code": "resource_exhausted" } } }, "travel-rule-internal": { "summary": "Internal error", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 500, "code": "internal" } } }, "travel-rule-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 503, "code": "unavailable" } } }, "travel-rule-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 504, "code": "deadline_exceeded" } } }, "travel-rule-verification-not-found": { "summary": "Verification not found", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 404, "code": "verification_not_found" } } }, "travel-rule-wallet-type-mismatch": { "summary": "Wallet type conflicts with the existing verification", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "wallet_type_mismatch" } } }, "travel-rule-verification-not-enabled": { "summary": "Verification is not enabled", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "verification_not_enabled" } } }, "travel-rule-satoshi-test-required": { "summary": "A Satoshi test is required", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "satoshi_test_required" } } }, "travel-rule-verification-rejected": { "summary": "Verification was rejected", "value": { "error": { "type": "travel_rule_error", "instance": "5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b", "status": 409, "code": "verification_rejected" } } }, "users-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "users_error", "instance": "req_01H00000000000000000000000", "status": 400, "code": "bad_request", "causes": [ { "field": "email", "message": "Invalid email address" } ] } } }, "users-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "users_error", "instance": "req_01H00000000000000000000000", "status": 401, "code": "unauthenticated" } } }, "users-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "users_error", "instance": "req_01H00000000000000000000000", "status": 403, "code": "forbidden" } } }, "users-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "users_error", "instance": "req_01H00000000000000000000000", "status": 429, "code": "resource_exhausted" } } }, "users-internal": { "summary": "Internal error", "value": { "error": { "type": "users_error", "instance": "req_01H00000000000000000000000", "status": 500, "code": "internal" } } }, "users-service-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "users_error", "instance": "req_01H00000000000000000000000", "status": 503, "code": "unavailable" } } }, "users-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "users_error", "instance": "req_01H00000000000000000000000", "status": 504, "code": "deadline_exceeded" } } }, "webhooks-bad-request": { "summary": "Invalid request", "value": { "error": { "type": "webhooks_error", "instance": "req_01H00000000000000000000000", "status": 400, "code": "bad_request", "causes": [ { "field": "page_size", "message": "must be between 1 and 25" } ] } } }, "webhooks-unauthenticated": { "summary": "Authentication failed", "value": { "error": { "type": "webhooks_error", "instance": "req_01H00000000000000000000000", "status": 401, "code": "unauthenticated" } } }, "webhooks-forbidden": { "summary": "Caller is not allowed", "value": { "error": { "type": "webhooks_error", "instance": "req_01H00000000000000000000000", "status": 403, "code": "forbidden" } } }, "webhooks-resource-exhausted": { "summary": "Rate limit exceeded", "value": { "error": { "type": "webhooks_error", "instance": "req_01H00000000000000000000000", "status": 429, "code": "resource_exhausted" } } }, "webhooks-internal": { "summary": "Internal error", "value": { "error": { "type": "webhooks_error", "instance": "req_01H00000000000000000000000", "status": 500, "code": "internal" } } }, "webhooks-service-unavailable": { "summary": "Service unavailable", "value": { "error": { "type": "webhooks_error", "instance": "req_01H00000000000000000000000", "status": 503, "code": "unavailable" } } }, "webhooks-deadline-exceeded": { "summary": "Request deadline exceeded", "value": { "error": { "type": "webhooks_error", "instance": "req_01H00000000000000000000000", "status": 504, "code": "deadline_exceeded" } } } }, "parameters": { "UserId": { "name": "user_id", "in": "path", "required": true, "example": "AA23N84GGQN4WE6I", "schema": { "$ref": "#/components/schemas/UserId" } }, "Assets_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "default": 20 }, "style": "form", "example": 20 }, "PageToken": { "name": "page_token", "in": "query", "description": "Opaque token returned as `next_page_token` in the previous response. Omit to request the first page.", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "style": "form", "example": "MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4" }, "AccountId": { "name": "account_id", "in": "path", "required": true, "example": "WVSD33HRMGSZUBM7", "schema": { "$ref": "#/components/schemas/AccountId" } }, "RequiredIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "AutoEarn_QuoteSymbol": { "name": "quote_symbol", "in": "query", "description": "Ticker symbol of the quote asset for converted amounts (e.g., \"USD\", \"EUR\").", "required": false, "schema": { "type": "string", "maxLength": 10, "default": "USD" }, "style": "form", "example": "USD" }, "BondedEarn_QuoteSymbol": { "name": "quote_symbol", "in": "query", "description": "Ticker symbol of the quote asset for converted amounts (e.g., \"USD\", \"EUR\").", "required": false, "schema": { "type": "string", "maxLength": 10, "default": "USD" }, "style": "form", "example": "USD" }, "AutoEarn_QuoteType": { "name": "quote_type", "in": "query", "description": "Type of the quote asset. Only \"fiat\" is supported.", "required": false, "schema": { "type": "string", "maxLength": 16, "default": "fiat" }, "style": "form", "example": "fiat" }, "BondedEarn_QuoteType": { "name": "quote_type", "in": "query", "description": "Type of the quote asset. Only \"fiat\" is supported.", "required": false, "schema": { "type": "string", "maxLength": 16, "default": "fiat" }, "style": "form", "example": "fiat" }, "BondedEarn_StrategyAssetTypeFilter": { "name": "type", "in": "query", "description": "Returns only strategies for assets of the selected types.", "required": false, "schema": { "type": "array", "items": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] } }, "style": "form", "example": [ "crypto" ] }, "BondedEarn_StrategyYieldSourceFilter": { "name": "yield_source", "in": "query", "description": "Returns only strategies backed by the selected yield sources.", "required": false, "schema": { "type": "array", "items": { "title": "YieldSource", "description": "Yield source that backs this strategy (e.g., \"staking\").", "type": "string", "enum": [ "staking", "base_rewards", "opt_in_rewards" ] } }, "style": "form", "example": [ "staking" ] }, "BondedEarn_StrategySymbolFilter": { "name": "symbol", "in": "query", "description": "Returns only strategies for the selected asset ticker symbols. Matching ignores case.", "required": false, "schema": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "style": "form", "example": [ "ETH" ] }, "AutoEarn_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 }, "BondedEarn_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 }, "BondedEarn_BondedStrategyId": { "name": "strategy_id", "in": "path", "description": "Identifier of the bonded earn strategy to allocate to or deallocate from.", "required": true, "example": "ESQEFMZ-JPPIY-3KXFJ2", "schema": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyId" } }, "BondedEarn_BondedRequestId": { "name": "request_id", "in": "path", "description": "Identifier of an allocate or deallocate request, as returned when the request was submitted or listed.", "required": true, "example": "EBARERNY-PXH3CV-XQJL2O", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "Funding_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 }, "Portfolio_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 }, "Reports_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 }, "OnchainQuotes_QuoteId": { "name": "quote_id", "in": "path", "description": "Unique identifier of the quote.", "required": true, "example": "BQ5U74K-XV6GP-TTQ567", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, "Swaps_QuoteId": { "name": "quote_id", "in": "path", "description": "Unique identifier of the quote.", "required": true, "example": "BQ5U74K-XV6GP-TTQ567", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, "PriceTriggerSwaps_PriceTriggerSwapId": { "name": "price_trigger_swap_id", "in": "path", "description": "Unique identifier of the price-triggered swap.", "required": true, "example": "ALCCIA-CUT6P-XCW6K7", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, "OnchainQuotes_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "example": 20, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form" }, "PriceTriggerSwaps_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "example": 20, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form" }, "TravelRuleVerifications_VerificationId": { "name": "verification_id", "in": "path", "description": "Stable PWS identifier for the Travel Rule verification case.", "required": true, "example": "ver_0195e4d2-a4d0-7b12-8f4a-123456789abc", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, "Verifications_VerificationIdPath": { "in": "path", "name": "verification_id", "required": true, "description": "Public PV-prefixed verification ID.", "schema": { "type": "string", "description": "Public identifier for a Payward-managed verification.", "pattern": "^PV[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{6}$", "minLength": 20, "maxLength": 20, "example": "PVABCDE-FGHIJ-KLMNOP" }, "example": "PVABCDE-FGHIJ-KLMNOP" }, "Webhooks_PageSize": { "name": "page_size", "in": "query", "description": "Maximum number of results to return. Ignored when `page_token` is present.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 25, "default": 20 }, "style": "form", "example": 20 } }, "headers": { "TraceId": { "description": "Trace identifier for the request. Include it when contacting support.", "schema": { "type": "string", "example": "4bf92f3577b34da6a3ce929d0e0e4736" } }, "StrictTransportSecurity": { "description": "Enforces HTTPS for the duration specified by `max-age`.", "schema": { "type": "string", "example": "max-age=31536000; includeSubDomains; preload" } }, "CacheControl": { "description": "Prevents caching of sensitive financial data. Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } } }, "schemas": { "Price": { "description": "Price of one unit of an asset or instrument in the applicable quote units.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "AssetSymbol": { "description": "Symbol identifying an asset within its asset category.", "type": "string", "minLength": 1, "maxLength": 16 }, "UserId": { "description": "Globally unique public identifier for a user.", "type": "string", "minLength": 14, "maxLength": 42 }, "DateTime": { "description": "RFC 3339 timestamp.", "type": "string", "format": "date-time" }, "Assets_SortField": { "description": "Field to sort the results by. Use sort_direction to control ascending vs descending.", "type": "string", "enum": [ "trending_rank", "market_cap_rank", "market_cap", "price", "volume_last_24h", "price_change_percent_last_1h", "price_change_percent_last_24h", "price_change_percent_last_7d", "price_change_percent_last_30d", "price_change_percent_last_1y", "symbol", "name", "listing_date" ], "default": "market_cap_rank" }, "Assets_Interval": { "description": "Sampling interval.", "type": "string", "enum": [ "PT1M", "PT5M", "PT15M", "PT30M", "PT60M", "PT4H", "P1D", "P7D", "P15D" ], "default": "PT15M" }, "Assets_AssetType": { "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "Assets_CatalogAssetType": { "description": "Classification of an asset available in the catalog.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "Assets_QuoteAssetType": { "description": "Classification of the fiat asset used to quote valuations.", "type": "string", "enum": [ "fiat" ] }, "Assets_AssetReference": { "description": "An asset reference without an amount.", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"BTC\", \"USD\", \"TSLAx\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/Assets_AssetType" } }, "required": [ "symbol", "type" ] }, "Assets_SwapTradingStatus": { "description": "Eligibility for swap trading.", "type": "object", "properties": { "enabled": { "description": "Whether the asset is currently enabled for swap trading.", "type": "boolean" }, "disabled_against": { "description": "Assets that cannot be paired with this one in a swap. Empty when the asset can be paired with any other tradable asset.", "type": "array", "items": { "$ref": "#/components/schemas/Assets_AssetReference" } } }, "required": [ "enabled", "disabled_against" ] }, "Assets_FundingStatus": { "description": "Eligibility for funding operations.", "type": "object", "properties": { "enabled": { "description": "Whether the asset is currently enabled.", "type": "boolean" } }, "required": [ "enabled" ] }, "Assets_AssetStatus": { "description": "Per-action availability for this asset.", "type": "object", "properties": { "swap_trading": { "description": "Eligibility for swap trading.", "$ref": "#/components/schemas/Assets_SwapTradingStatus" }, "withdraw": { "description": "Eligibility for withdrawals.", "$ref": "#/components/schemas/Assets_FundingStatus" }, "deposit": { "description": "Eligibility for deposits.", "$ref": "#/components/schemas/Assets_FundingStatus" } }, "required": [ "swap_trading", "withdraw", "deposit" ] }, "Assets_AssetLogo": { "description": "Logo image.", "type": "object", "properties": { "width": { "description": "Width of the image in pixels.", "type": "integer", "format": "int32" }, "height": { "description": "Height of the image in pixels.", "type": "integer", "format": "int32" }, "href": { "description": "URI of the logo image.", "type": "string" }, "type": { "description": "MIME type of the image (e.g., \"image/webp\").", "type": "string" } }, "required": [ "width", "height", "href" ] }, "Assets_AssetDecimals": { "description": "Decimal precision for the asset across funding and swap operations.", "type": "object", "properties": { "funding": { "description": "Number of decimals supported when funding (depositing/withdrawing) this asset on its native protocol.", "type": "integer", "format": "int32" }, "swap": { "description": "Number of decimals supported when trading this asset via swap.", "type": "integer", "format": "int32" } }, "required": [ "funding", "swap" ] }, "Assets_AssetVolume": { "description": "Trading volume over recent windows, denominated in the requested quote asset.", "type": "object", "properties": { "last_24h": { "description": "The 24-hour trading volume for the asset, in the requested quote asset.", "type": "string" } } }, "Assets_AssetSupplyInQuote": { "description": "Same supply figures valued at the current market price, denominated in the requested quote asset.", "type": "object", "properties": { "circulating": { "description": "Number of tokens currently in circulation.", "type": "string" }, "total": { "description": "The total number of tokens that currently exist.", "type": "string" }, "max": { "description": "The maximum number of tokens that can ever exist.", "type": "string" } } }, "Assets_AssetSupply": { "description": "Token supply figures. Absent for assets where supply is not applicable (e.g., fiat).", "type": "object", "properties": { "circulating": { "description": "Number of tokens currently in circulation.", "type": "string" }, "total": { "description": "The total number of tokens that currently exist.", "type": "string" }, "max": { "description": "The maximum number of tokens that can ever exist.", "type": "string" }, "in_quote": { "description": "Same supply figures valued at the current market price, denominated in the requested quote asset.", "$ref": "#/components/schemas/Assets_AssetSupplyInQuote" } } }, "Assets_PriceChangePercent": { "description": "Percentage change in the asset price over each rolling time window.", "type": "object", "properties": { "last_1h": { "description": "The price change percentage over the last 1 hour.", "type": "string" }, "last_24h": { "description": "The price change percentage over the last 24 hours.", "type": "string" }, "last_7d": { "description": "The price change percentage over the last 7 days.", "type": "string" }, "last_30d": { "description": "The price change percentage over the last 30 days.", "type": "string" }, "last_1y": { "description": "The price change percentage over the last 1 year.", "type": "string" } } }, "Assets_PriceRange": { "description": "Highest and lowest price over recent windows, in the requested quote asset. Each bound is included when it is known.", "type": "object", "properties": { "high_24h": { "description": "Highest market trade price over the last 24 hours, in the requested quote asset.", "type": "string" }, "low_24h": { "description": "Lowest market trade price over the last 24 hours, in the requested quote asset.", "type": "string" }, "high_1y": { "description": "Highest market trade price over the last year, in the requested quote asset.", "type": "string" }, "low_1y": { "description": "Lowest market trade price over the last year, in the requested quote asset.", "type": "string" } } }, "Assets_AssetAth": { "description": "All-time-high price for the asset, with the timestamp it was reached.", "type": "object", "properties": { "value": { "description": "The all-time high price of the asset.", "type": "string" }, "timestamp": { "description": "Timestamp when the asset reached its all-time high price.", "type": "string" } }, "required": [ "value", "timestamp" ] }, "Assets_Asset": { "description": "A tradable asset.", "type": "object", "properties": { "symbol": { "description": "Ticker symbol (e.g., \"BTC\", \"ETH\", \"USD\").", "type": "string" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/Assets_CatalogAssetType" }, "name": { "description": "Human-readable English name of the asset.", "type": "string" }, "website": { "description": "Official project website URL. Absent when unknown.", "type": "string", "format": "uri", "minLength": 1 }, "docs": { "description": "Official project documentation URL. Absent when unknown.", "type": "string", "format": "uri", "minLength": 1 }, "description": { "description": "English-language project description. Absent when unknown.", "type": "string", "minLength": 1 }, "listing_date": { "description": "The date the asset was first listed on Payward.", "type": "string" }, "price": { "description": "The latest price of the asset, in the requested quote asset. Omitted when unavailable.", "$ref": "#/components/schemas/Price" }, "market_cap": { "description": "The current market capitalization of the asset, in the requested quote asset.", "type": "string" }, "market_cap_rank": { "description": "The rank of the asset based on the total market capitalization.", "type": "integer", "format": "int32" }, "trending_rank": { "description": "The trending rank of the asset compared to all other trending assets.", "type": "integer", "format": "int32" }, "volume": { "description": "Trading volume over recent windows, denominated in the requested quote asset.", "$ref": "#/components/schemas/Assets_AssetVolume" }, "supply": { "description": "Token supply figures. Absent for assets where supply is not applicable (e.g., fiat).", "$ref": "#/components/schemas/Assets_AssetSupply" }, "price_range": { "description": "Highest and lowest traded price over recent windows, in the requested quote asset.", "$ref": "#/components/schemas/Assets_PriceRange" }, "price_change_percent": { "description": "Percentage change in the asset price over each rolling time window.", "$ref": "#/components/schemas/Assets_PriceChangePercent" }, "ath": { "description": "All-time-high price for the asset, with the timestamp it was reached.", "$ref": "#/components/schemas/Assets_AssetAth" }, "buy_rate": { "description": "Share of recent successful swaps in which users received this asset, as a percentage from 0 to 100. Omitted when unavailable.", "type": "string", "minLength": 1 }, "market_dominance": { "description": "Market share of this asset as a percentage of global cryptocurrency market capitalization, from 0 to 100. Omitted when unavailable.", "type": "string", "minLength": 1 }, "status": { "description": "Per-action availability for this asset.", "$ref": "#/components/schemas/Assets_AssetStatus" }, "logo": { "description": "Logo image.", "$ref": "#/components/schemas/Assets_AssetLogo" }, "decimals": { "description": "Decimal precision for the asset across funding and swap operations.", "$ref": "#/components/schemas/Assets_AssetDecimals" } }, "required": [ "symbol", "type", "name", "status", "logo", "decimals" ] }, "Assets_HistoricalRate": { "description": "Price and volume summary for one interval, with prices in the quote asset and volume in the requested asset.", "type": "object", "properties": { "timestamp": { "description": "Start of the candle interval.", "$ref": "#/components/schemas/DateTime" }, "open": { "description": "Opening price for the interval, in units of the quote asset per unit of the requested asset.", "type": "string" }, "high": { "description": "Highest price or derived upper price bound during the interval, in the quote asset.", "type": "string" }, "low": { "description": "Lowest price or derived lower price bound during the interval, in the quote asset.", "type": "string" }, "close": { "description": "Closing price for the interval in the quote asset. Use this value to plot a price chart.", "type": "string" }, "volume": { "description": "Volume during the interval, in units of the requested asset. For derived rates, this comes from the underlying market used to price the requested asset, which may use a different quote asset.", "type": "string" } }, "required": [ "timestamp", "open", "high", "low", "close", "volume" ] }, "PwsErrorBase": { "description": "Common fields present on every PWS API error object.", "type": "object", "required": [ "type", "status", "instance", "code" ], "properties": { "type": { "description": "Machine-readable error class.", "type": "string" }, "status": { "description": "HTTP status code returned for this error.", "type": "integer", "format": "int32" }, "instance": { "description": "Request identifier for this specific error occurrence.", "type": "string" }, "code": { "description": "Stable machine-readable error code.", "type": "string" }, "doc_url": { "description": "Optional link to documentation for this error.", "type": "string", "format": "uri" } } }, "PwsErrorCause": { "description": "A single request validation failure.", "type": "object", "required": [ "field", "message" ], "properties": { "field": { "description": "Dot-notation path to the offending request field.", "type": "string" }, "message": { "description": "Human-readable explanation of the failed validation rule.", "type": "string" } } }, "PwsGeneralError": { "description": "Standard PWS API error object for non-validation failures.", "allOf": [ { "$ref": "#/components/schemas/PwsErrorBase" }, { "type": "object", "properties": { "causes": { "description": "Additional error details, when present.", "type": "array", "items": { "type": "object", "additionalProperties": true } } } } ] }, "PwsGeneralErrorEnvelope": { "description": "Error envelope for operational or domain failures.", "type": "object", "required": [ "error" ], "properties": { "error": { "description": "General error details.", "$ref": "#/components/schemas/PwsGeneralError" } } }, "PwsValidationError": { "description": "Standard PWS API error object for request validation failures.", "type": "object", "required": [ "type", "status", "instance", "code" ], "properties": { "type": { "description": "Machine-readable error class.", "type": "string" }, "status": { "description": "HTTP status code returned for this error.", "type": "integer", "format": "int32" }, "instance": { "description": "Request identifier for this specific error occurrence.", "type": "string" }, "code": { "description": "Stable machine-readable error code.", "type": "string" }, "doc_url": { "description": "Optional link to documentation for this error.", "type": "string", "format": "uri" }, "causes": { "description": "Validation failures that contributed to the error.", "type": "array", "items": { "$ref": "#/components/schemas/PwsErrorCause" } } } }, "PwsValidationErrorEnvelope": { "description": "Error envelope for request validation failures.", "type": "object", "required": [ "error" ], "properties": { "error": { "description": "Validation error details.", "$ref": "#/components/schemas/PwsValidationError" } } }, "BadRequestError": { "title": "Bad Request", "description": "Request validation failed or the request could not be processed.", "oneOf": [ { "title": "Bad Request", "allOf": [ { "$ref": "#/components/schemas/PwsValidationErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsValidationError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "bad_request" ] } } } ] } } } ] }, { "title": "Gateway", "description": "Gateway-level validation failure returned before the request reaches the service.", "allOf": [ { "$ref": "#/components/schemas/PwsValidationErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsValidationError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "type": { "type": "string", "const": "service_error" }, "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "const": "gateway" } } } ] } } } ] } ] }, "UnauthenticatedError": { "title": "Unauthenticated", "description": "Authentication credentials are missing, invalid, or not accepted.", "oneOf": [ { "title": "Unauthenticated", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 401 }, "code": { "type": "string", "enum": [ "unauthenticated" ] } } } ] } } } ] }, { "title": "Gateway", "description": "Authentication failure returned by the API gateway.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "type": { "type": "string", "const": "service_error" }, "status": { "type": "integer", "format": "int32", "const": 401 }, "code": { "type": "string", "const": "gateway" } } } ] } } } ] } ] }, "ForbiddenError": { "title": "Forbidden", "description": "The caller is not allowed to perform this operation.", "oneOf": [ { "title": "Forbidden", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "forbidden" ] } } } ] } } } ] }, { "title": "Gateway", "description": "Authorization failure returned by the API gateway.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "type": { "type": "string", "const": "service_error" }, "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "const": "gateway" } } } ] } } } ] } ] }, "NotFoundError": { "description": "The requested resource was not found.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "not_found" ] } } } ] } } } ] }, "ResourceExhaustedError": { "description": "The request was rate limited or a resource quota was exhausted.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 429 }, "code": { "type": "string", "enum": [ "resource_exhausted" ] } } } ] } } } ] }, "InternalError": { "description": "An unexpected server-side error occurred.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 500 }, "code": { "type": "string", "enum": [ "internal" ] } } } ] } } } ] }, "UnimplementedError": { "description": "The requested operation is not implemented.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 501 }, "code": { "type": "string", "enum": [ "unimplemented" ] } } } ] } } } ] }, "UnavailableError": { "description": "The service is temporarily unavailable.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 503 }, "code": { "type": "string", "enum": [ "unavailable" ] } } } ] } } } ] }, "DeadlineExceededError": { "description": "The request deadline was exceeded before a response could be produced.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 504 }, "code": { "type": "string", "enum": [ "deadline_exceeded" ] } } } ] } } } ] }, "AccountId": { "description": "Globally unique public identifier for an account.", "type": "string", "minLength": 14, "maxLength": 42 }, "IdempotencyKey": { "description": "Client-generated canonical UUIDv4 that uniquely identifies a request for safe retries.", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "550e8400-e29b-41d4-a716-446655440000" }, "Conversions_OnDemandConversionStatus": { "description": "Current lifecycle status of an on-demand conversion. `prepared` means the price and fees are locked and the conversion waits to be executed by the customer. `canceled` means the conversion was canceled before execution. `converting` means the conversion is in progress, including while an RfP conversion is waiting for payer authorization. `settling` means the converted asset is being delivered to the destination. `completed` means the conversion finished successfully. `failed` means the conversion could not be completed.", "type": "string", "enum": [ "converting", "settling", "failed", "completed", "prepared", "canceled" ] }, "Conversions_OnDemandConversionCancellationReason": { "description": "Why the on-demand conversion was canceled. New reasons can be added, so accept an unknown reason.\n- `expired`: `expires_at` passed before execution.\n- `market_moved`: the market moved too far from the locked price.\n- `price_unavailable`: the locked price could no longer be honored.", "type": "string", "enum": [ "expired", "market_moved", "price_unavailable" ] }, "Conversions_OnDemandConversionSideType": { "description": "Where funds come from or go to. `balance` is the account balance, `bank` is a bank account, and `wallet` is a crypto address.", "type": "string", "enum": [ "balance", "bank", "wallet" ] }, "Conversions_OnDemandConversionSource": { "description": "Source side of an on-demand conversion.", "discriminator": { "propertyName": "type", "mapping": { "balance": "#/components/schemas/Conversions_OnDemandConversionBalanceSource", "bank": "#/components/schemas/Conversions_OnDemandConversionBankSource" } }, "oneOf": [ { "title": "OnDemandConversionBalanceSource", "$ref": "#/components/schemas/Conversions_OnDemandConversionBalanceSource" }, { "title": "OnDemandConversionBankSource", "$ref": "#/components/schemas/Conversions_OnDemandConversionBankSource" } ] }, "Conversions_OnDemandConversionDestination": { "description": "Destination side of an on-demand conversion.", "discriminator": { "propertyName": "type", "mapping": { "wallet": "#/components/schemas/Conversions_OnDemandConversionWalletDestination", "bank": "#/components/schemas/Conversions_OnDemandConversionBankDestination" } }, "oneOf": [ { "title": "OnDemandConversionWalletDestination", "$ref": "#/components/schemas/Conversions_OnDemandConversionWalletDestination" }, { "title": "OnDemandConversionBankDestination", "$ref": "#/components/schemas/Conversions_OnDemandConversionBankDestination" } ] }, "Conversions_OnDemandConversionBalanceSource": { "description": "Balance source for an on-demand conversion.", "type": "object", "additionalProperties": false, "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset symbol debited from the selected account balance.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "title": "OnDemandConversionBalanceType", "description": "Type of source. Always `balance`.", "type": "string", "enum": [ "balance" ] }, "amount": { "description": "Amount to debit from the selected account balance. Provide this or `to.amount`, but not both.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Conversions_OnDemandConversionBankSource": { "description": "Linked bank account source for an on-demand conversion (bank pay-in).", "type": "object", "additionalProperties": false, "required": [ "symbol", "type", "bank_account" ], "properties": { "symbol": { "description": "Funding currency symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "title": "OnDemandConversionBankSourceType", "description": "Type of source. Always `bank`.", "type": "string", "enum": [ "bank" ] }, "amount": { "description": "Amount fixed by the caller. Bank-funded conversions fix the from side.", "type": "string", "minLength": 1, "maxLength": 64 }, "bank_account": { "$ref": "#/components/schemas/Conversions_OnDemandConversionBankAccountSource" } } }, "Conversions_OnDemandConversionWalletDestination": { "description": "Crypto wallet destination for an on-demand conversion. Some wallet addresses need Travel Rule ownership verification before a conversion can deliver funds to them. Verify such an address with Create Travel Rule verification (`POST /v1/users/{user_id}/travel-rule/verifications`) before you request the conversion.", "type": "object", "additionalProperties": false, "required": [ "symbol", "type", "wallet" ], "properties": { "symbol": { "description": "Asset symbol delivered to the wallet.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "title": "OnDemandConversionWalletDestinationType", "description": "Type of destination. Always `wallet`.", "type": "string", "enum": [ "wallet" ] }, "wallet": { "$ref": "#/components/schemas/Conversions_OnDemandConversionWalletTarget" }, "amount": { "description": "Amount to deliver to the wallet. Provide this or `from.amount`, but not both.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Conversions_OnDemandConversionBankDestination": { "description": "Bank account destination for an on-demand conversion.", "type": "object", "additionalProperties": false, "required": [ "symbol", "type", "bank_account" ], "properties": { "symbol": { "description": "Fiat asset symbol delivered to the bank account.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "title": "OnDemandConversionBankDestinationType", "description": "Type of destination. Always `bank`.", "type": "string", "enum": [ "bank" ] }, "bank_account": { "$ref": "#/components/schemas/Conversions_OnDemandConversionBankAccountTarget" }, "amount": { "description": "Amount to deliver to the bank account. Provide this or `from.amount`, but not both.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Conversions_OnDemandConversionBankAccountTarget": { "description": "Bank payout details. Each rail supports a specific payout currency and requires specific bank details: ACH and RTP support USD and use an Account Link ID; SEPA supports EUR and uses an IBAN, with an optional BIC; FPS supports GBP and uses a sort code and account number. These forms are mutually exclusive.", "discriminator": { "propertyName": "via", "mapping": { "ach": "#/components/schemas/Conversions_OnDemandConversionAchBankAccount", "rtp": "#/components/schemas/Conversions_OnDemandConversionRtpBankAccount", "sepa": "#/components/schemas/Conversions_OnDemandConversionSepaBankAccount", "fps": "#/components/schemas/Conversions_OnDemandConversionFpsBankAccount" } }, "oneOf": [ { "title": "OnDemandConversionAchBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionAchBankAccount" }, { "title": "OnDemandConversionRtpBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionRtpBankAccount" }, { "title": "OnDemandConversionSepaBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionSepaBankAccount" }, { "title": "OnDemandConversionFpsBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionFpsBankAccount" } ] }, "Conversions_OnDemandConversionBankAccountSource": { "description": "Linked bank account that funds an on-demand conversion.", "discriminator": { "propertyName": "via", "mapping": { "ach": "#/components/schemas/Conversions_OnDemandConversionAchBankAccount", "rfp": "#/components/schemas/Conversions_OnDemandConversionRfpBankAccount" } }, "oneOf": [ { "title": "OnDemandConversionAchBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionAchBankAccount" }, { "title": "OnDemandConversionRfpBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionRfpBankAccount" } ] }, "Conversions_OnDemandConversionBankAccount": { "description": "Bank account used by a source or destination conversion side.", "discriminator": { "propertyName": "via", "mapping": { "ach": "#/components/schemas/Conversions_OnDemandConversionAchBankAccount", "rtp": "#/components/schemas/Conversions_OnDemandConversionRtpBankAccount", "sepa": "#/components/schemas/Conversions_OnDemandConversionSepaBankAccount", "fps": "#/components/schemas/Conversions_OnDemandConversionFpsBankAccount", "rfp": "#/components/schemas/Conversions_OnDemandConversionRfpBankAccount" } }, "oneOf": [ { "title": "OnDemandConversionAchBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionAchBankAccount" }, { "title": "OnDemandConversionRtpBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionRtpBankAccount" }, { "title": "OnDemandConversionSepaBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionSepaBankAccount" }, { "title": "OnDemandConversionFpsBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionFpsBankAccount" }, { "title": "OnDemandConversionRfpBankAccount", "$ref": "#/components/schemas/Conversions_OnDemandConversionRfpBankAccount" } ] }, "Conversions_OnDemandConversionAchBankAccount": { "description": "Linked ACH bank account used to fund or receive an on-demand conversion.", "type": "object", "additionalProperties": false, "required": [ "via", "account_link_id" ], "properties": { "via": { "title": "OnDemandConversionLinkedAchVia", "description": "Bank rail. Always `ach`.", "type": "string", "enum": [ "ach" ] }, "account_link_id": { "description": "Public Account Link identifier for the ACH account.", "type": "string", "minLength": 1, "maxLength": 128 } } }, "Conversions_OnDemandConversionRfpBankAccount": { "description": "Linked bank account used to fund an on-demand conversion by Request for Payment.", "type": "object", "additionalProperties": false, "required": [ "via", "account_link_id" ], "properties": { "via": { "title": "OnDemandConversionLinkedRfpVia", "description": "Bank rail. Always `rfp`.", "type": "string", "enum": [ "rfp" ] }, "account_link_id": { "description": "Public Account Link identifier for the RfP account.", "type": "string", "minLength": 1, "maxLength": 128 } } }, "Conversions_OnDemandConversionRtpBankAccount": { "description": "RTP bank account destination.", "type": "object", "additionalProperties": false, "required": [ "via", "account_link_id" ], "properties": { "via": { "title": "OnDemandConversionLinkedRtpVia", "description": "Bank rail. Always `rtp` for this destination.", "type": "string", "enum": [ "rtp" ] }, "account_link_id": { "description": "Public Account Link identifier for the RTP account.", "type": "string", "minLength": 1, "maxLength": 128 } } }, "Conversions_OnDemandConversionSepaBankAccount": { "description": "SEPA bank account destination.", "type": "object", "additionalProperties": false, "required": [ "via", "iban" ], "properties": { "via": { "title": "OnDemandConversionRawSepaVia", "description": "Bank rail. Always `sepa` for this destination.", "type": "string", "enum": [ "sepa" ] }, "iban": { "description": "International Bank Account Number for the SEPA destination.", "type": "string", "minLength": 14, "maxLength": 42 }, "bic": { "description": "Optional Bank Identifier Code for the SEPA destination.", "type": "string", "minLength": 8, "maxLength": 11 } } }, "Conversions_OnDemandConversionFpsBankAccount": { "description": "FPS bank account destination.", "type": "object", "additionalProperties": false, "required": [ "via", "sort_code", "account_number" ], "properties": { "via": { "title": "OnDemandConversionRawFpsVia", "description": "Bank rail. Always `fps` for this destination.", "type": "string", "enum": [ "fps" ] }, "sort_code": { "description": "UK sort code for the FPS destination.", "type": "string", "minLength": 6, "maxLength": 8 }, "account_number": { "description": "Account number for the FPS destination.", "type": "string", "minLength": 1, "maxLength": 34 } } }, "Conversions_OnDemandConversionWalletTarget": { "description": "Destination wallet details for an on-demand conversion.", "type": "object", "additionalProperties": false, "required": [ "via", "address" ], "properties": { "via": { "description": "Network name from the List deposit methods `network` field.", "type": "string", "minLength": 1, "maxLength": 32 }, "address": { "description": "Destination wallet address on the selected network.", "type": "string", "minLength": 1, "maxLength": 256 }, "memo": { "description": "Optional memo required by some destination networks.", "type": "string", "minLength": 1, "maxLength": 64 }, "tag": { "description": "Optional tag required by some destination networks.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Conversions_OnDemandConversion": { "description": "Details of an on-demand conversion. It includes the amount debited from the source, the amount delivered to the destination, the exchange rate, destination details, and fees. Transaction references are included when available. A linked bank source remains pending while funding is in progress. An RfP conversion includes `next_action` while its payer must authorize the payment. A wallet destination may include a saved memo or tag; when present, those fields are returned in every response.", "type": "object", "required": [ "id", "status", "from", "to", "rate", "fees", "created_at", "updated_at" ], "properties": { "id": { "description": "Unique identifier for this on-demand conversion.", "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/Conversions_OnDemandConversionStatus" }, "from": { "$ref": "#/components/schemas/Conversions_OnDemandConversionEndpoint" }, "to": { "$ref": "#/components/schemas/Conversions_OnDemandConversionEndpoint" }, "rate": { "$ref": "#/components/schemas/Conversions_OnDemandConversionRate" }, "fees": { "$ref": "#/components/schemas/Conversions_OnDemandConversionFees" }, "transaction_references": { "$ref": "#/components/schemas/Conversions_OnDemandConversionTransactionReferences" }, "created_at": { "description": "Time at which the on-demand conversion was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the on-demand conversion was last updated.", "$ref": "#/components/schemas/DateTime" }, "next_action": { "$ref": "#/components/schemas/Conversions_OnDemandConversionNextAction" }, "expires_at": { "description": "Time at which the locked price and fees expire. Returned when `status` is `prepared` or `canceled`.", "$ref": "#/components/schemas/DateTime" }, "cancellation_reason": { "description": "Why the on-demand conversion was canceled. Returned when `status` is `canceled`.", "$ref": "#/components/schemas/Conversions_OnDemandConversionCancellationReason" } } }, "Conversions_EstimateOnDemandConversionSide": { "description": "One side of an on-demand conversion to estimate. It has the same fields as the matching side in Prepare on-demand conversion, without the address or account details. Send `bank_account` for a `bank` side and `wallet` for a `wallet` side.", "type": "object", "additionalProperties": false, "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset of this side.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Conversions_OnDemandConversionSideType" }, "amount": { "description": "Amount to debit from the source or to deliver to the destination.", "type": "string", "minLength": 1, "maxLength": 64 }, "bank_account": { "description": "Bank rail of a `bank` side.", "$ref": "#/components/schemas/Conversions_EstimateOnDemandConversionVia" }, "wallet": { "description": "Network of a `wallet` side.", "$ref": "#/components/schemas/Conversions_EstimateOnDemandConversionVia" } }, "allOf": [ { "if": { "properties": { "type": { "enum": [ "bank" ] } } }, "then": { "required": [ "bank_account" ] }, "else": { "not": { "required": [ "bank_account" ] } } }, { "if": { "properties": { "type": { "enum": [ "wallet" ] } } }, "then": { "required": [ "wallet" ] }, "else": { "not": { "required": [ "wallet" ] } } } ] }, "Conversions_EstimateOnDemandConversionVia": { "description": "Rail or network of an estimated side.", "type": "object", "additionalProperties": false, "required": [ "via" ], "properties": { "via": { "description": "Bank rail, such as `rfp` or `sepa`, or network from the List deposit methods `network` field. It has the same values as `via` in Prepare on-demand conversion.", "type": "string", "minLength": 1, "maxLength": 32 } } }, "Conversions_OnDemandConversionEstimate": { "description": "Indicative result of an on-demand conversion. The final amounts can differ.", "type": "object", "additionalProperties": false, "required": [ "from", "to", "rate", "fees" ], "properties": { "from": { "$ref": "#/components/schemas/Conversions_OnDemandConversionEstimateSide" }, "to": { "$ref": "#/components/schemas/Conversions_OnDemandConversionEstimateSide" }, "rate": { "description": "Indicative exchange rate. It is not locked and can change before a conversion.", "$ref": "#/components/schemas/Conversions_OnDemandConversionRate" }, "fees": { "description": "Indicative fees. They are not locked and can change before a conversion.", "$ref": "#/components/schemas/Conversions_OnDemandConversionFees" } } }, "Conversions_OnDemandConversionEstimateSide": { "description": "One side of an estimated on-demand conversion.", "type": "object", "additionalProperties": false, "required": [ "symbol", "type", "amount" ], "properties": { "symbol": { "description": "Asset of this side.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Conversions_OnDemandConversionSideType" }, "amount": { "description": "Amount debited from the source or delivered to the destination.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Conversions_OnDemandConversionNextAction": { "description": "Present while a payer must authorize an RfP payment. Omitted after the payment is authorized, canceled, expired, or failed.", "type": "object", "additionalProperties": false, "required": [ "type", "widget_url", "expires_at" ], "properties": { "type": { "title": "OnDemandConversionNextActionType", "description": "Action the payer must complete. Always `hosted_payment`.", "type": "string", "enum": [ "hosted_payment" ] }, "widget_url": { "description": "Kraken-hosted payment widget URL. It is not a Plaid URL and contains no Plaid Link token.", "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048 }, "expires_at": { "description": "Time when the payer can no longer authorize this payment. This is independent of the conversion quote expiry.", "$ref": "#/components/schemas/DateTime" } } }, "Conversions_OnDemandConversionEndpoint": { "description": "Amount and details returned for one side of an on-demand conversion.", "discriminator": { "propertyName": "type", "mapping": { "balance": "#/components/schemas/Conversions_OnDemandConversionBalanceEndpoint", "wallet": "#/components/schemas/Conversions_OnDemandConversionWalletEndpoint", "bank": "#/components/schemas/Conversions_OnDemandConversionBankEndpoint" } }, "oneOf": [ { "title": "OnDemandConversionBalanceEndpoint", "$ref": "#/components/schemas/Conversions_OnDemandConversionBalanceEndpoint" }, { "title": "OnDemandConversionWalletEndpoint", "$ref": "#/components/schemas/Conversions_OnDemandConversionWalletEndpoint" }, { "title": "OnDemandConversionBankEndpoint", "$ref": "#/components/schemas/Conversions_OnDemandConversionBankEndpoint" } ] }, "Conversions_OnDemandConversionBalanceEndpoint": { "description": "Balance source side of an on-demand conversion and its current settlement status.", "type": "object", "additionalProperties": false, "required": [ "symbol", "type", "amount", "status" ], "properties": { "symbol": { "description": "Asset symbol for this conversion side.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "title": "OnDemandConversionBalanceEndpointType", "description": "Type of source side. Always `balance`.", "type": "string", "enum": [ "balance" ] }, "amount": { "description": "Amount debited from the selected account balance.", "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "title": "OnDemandConversionSettlementStatus", "description": "Current settlement status of this conversion side.", "type": "string", "enum": [ "pending", "held", "settled", "failed" ] } } }, "Conversions_OnDemandConversionWalletEndpoint": { "description": "Wallet destination side of an on-demand conversion and its current settlement status.", "type": "object", "additionalProperties": false, "required": [ "symbol", "type", "wallet", "amount", "status" ], "properties": { "symbol": { "description": "Asset symbol for this conversion side.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "title": "OnDemandConversionWalletEndpointType", "description": "Type of destination side. Always `wallet`.", "type": "string", "enum": [ "wallet" ] }, "wallet": { "$ref": "#/components/schemas/Conversions_OnDemandConversionWalletTarget" }, "amount": { "description": "Amount delivered to the destination wallet.", "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "title": "OnDemandConversionSettlementStatus", "description": "Current settlement status of this conversion side.", "type": "string", "enum": [ "pending", "held", "settled", "failed" ] } } }, "Conversions_OnDemandConversionBankEndpoint": { "description": "Bank source or destination side of an on-demand conversion and its current settlement status.", "type": "object", "additionalProperties": false, "required": [ "symbol", "type", "bank_account", "amount", "status" ], "properties": { "symbol": { "description": "Fiat asset symbol for this conversion side.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "title": "OnDemandConversionBankEndpointType", "description": "Type of conversion side. Always `bank`.", "type": "string", "enum": [ "bank" ] }, "bank_account": { "$ref": "#/components/schemas/Conversions_OnDemandConversionBankAccount" }, "amount": { "description": "Amount debited from or delivered to the bank account.", "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "title": "OnDemandConversionSettlementStatus", "description": "Current settlement status of this conversion side.", "type": "string", "enum": [ "pending", "held", "settled", "failed" ] } } }, "Conversions_OnDemandConversionRate": { "description": "Exchange rate applied to an on-demand conversion.", "type": "object", "required": [ "base", "quote", "price" ], "properties": { "base": { "description": "Base asset of the rate pair.", "$ref": "#/components/schemas/Conversions_OnDemandConversionRateAsset" }, "quote": { "description": "Quote asset of the rate pair.", "$ref": "#/components/schemas/Conversions_OnDemandConversionRateAsset" }, "price": { "description": "Price of one unit of the base asset denominated in the quote asset.", "$ref": "#/components/schemas/Price" } } }, "Conversions_OnDemandConversionRateAsset": { "description": "Asset in an on-demand conversion rate pair.", "type": "object", "required": [ "symbol" ], "properties": { "symbol": { "description": "Asset ticker symbol for the rate pair.", "type": "string" } } }, "Conversions_OnDemandConversionFees": { "description": "Breakdown of all fees charged for an on-demand conversion.", "type": "object", "additionalProperties": false, "required": [ "from", "trade", "to" ], "properties": { "to": { "description": "Withdrawal or payout fee charged on the destination side of the conversion.", "$ref": "#/components/schemas/Conversions_OnDemandConversionFee" }, "from": { "description": "Funding or deposit fee charged on the source side of the conversion.", "$ref": "#/components/schemas/Conversions_OnDemandConversionFee" }, "trade": { "description": "Platform conversion fee charged by the trading leg.", "$ref": "#/components/schemas/Conversions_OnDemandConversionFee" } } }, "Conversions_OnDemandConversionFee": { "description": "A single fee charged for an on-demand conversion.", "type": "object", "additionalProperties": false, "required": [ "symbol", "amount" ], "properties": { "symbol": { "description": "Asset ticker symbol the fee is denominated in.", "$ref": "#/components/schemas/AssetSymbol" }, "amount": { "description": "Fee amount as a decimal string.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Conversions_OnDemandConversionTransactionReferences": { "description": "Transaction references produced by the conversion, when available.", "type": "object", "additionalProperties": false, "properties": { "to": { "description": "Transaction reference for the destination side of the conversion, when available.", "$ref": "#/components/schemas/Conversions_OnDemandConversionTransactionReference" } } }, "Conversions_OnDemandConversionTransactionReference": { "description": "Transaction references for one conversion leg.", "type": "object", "additionalProperties": false, "properties": { "transaction_id": { "description": "Internal transaction identifier.", "type": "string", "minLength": 1, "maxLength": 256 }, "blockchain_transaction_id": { "description": "Blockchain transaction identifier, when available.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Conversions_OnDemandConversionIdempotencyKeyAlreadyUsedError": { "description": "An earlier request already used this `Idempotency-Key`. This request did not start an operation.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error", "conversion_id" ], "properties": { "conversion_id": { "description": "Identifier of the conversion of the earlier request that caused this conflict. To read the result of the first request, call Get on-demand conversion with this identifier.", "type": "string", "format": "uuid" }, "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "const": 409 }, "code": { "type": "string", "enum": [ "idempotency_key_already_used" ] } } } ] } } } ] }, "Conversions_OnDemandConversionPrepareLimitReachedError": { "description": "The account has the maximum number of on-demand conversions in status `prepared`. Execute one or wait for one to expire.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "conversion_prepare_limit_reached" ] } } } ] } } } ] }, "Conversions_OnDemandConversionAlreadyExecutedError": { "description": "The on-demand conversion was already executed.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "conversion_already_executed" ] } } } ] } } } ] }, "Conversions_OnDemandConversionCanceledError": { "description": "The prepared conversion was canceled or its price lock expired. Get the conversion to read `cancellation_reason`, then prepare a new conversion.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 410 }, "code": { "type": "string", "enum": [ "conversion_canceled" ] } } } ] } } } ] }, "Conversions_ConversionLimitReachedErrorResponse": { "description": "The maximum number of conversion rules was reached.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "conversion_limit_reached" ] } } } ] } } } ] }, "Conversions_ConversionInsufficientFundsErrorResponse": { "description": "The account does not have enough available funds for the requested conversion.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "conversion_insufficient_funds" ] } } } ] } } } ] }, "Conversions_ConversionAddressOwnershipVerificationRequiredErrorResponse": { "description": "The destination wallet address needs Travel Rule ownership verification before the conversion can continue. This request does not execute the conversion. Submit the address for the user that owns the account with Create Travel Rule verification (`POST /v1/users/{user_id}/travel-rule/verifications`). If the verification status is `pending`, get the verification again with Get Travel Rule verification (`GET /v1/users/{user_id}/travel-rule/verifications/{verification_id}`) until the status changes. When the status is `verified`, send the request again with a new `Idempotency-Key`. If the status is `failed`, or if you cannot verify the address, contact Support. A prepared conversion can expire during the verification. If it expires, prepare a new conversion.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "conversion_address_ownership_verification_required" ] } } } ] } } } ] }, "Conversions_ConversionWithdrawalMethodUnavailableErrorResponse": { "description": "The account cannot withdraw to the selected destination in its current state. For example, the verification of the user that owns the account is not complete. This request does not execute the conversion. Complete the verification of the user, or select a different destination. Then send the request again with a new `Idempotency-Key`.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "conversion_withdrawal_method_unavailable" ] } } } ] } } } ] }, "Conversions_ConversionsNotFoundErrorResponse": { "description": "The requested resource does not exist.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "not_found" ] } } } ] } } } ] }, "Conversions_RuleAlreadyDeletedErrorResponse": { "description": "The conversion rule was already deleted.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "rule_already_deleted" ] } } } ] } } } ] }, "Conversions_ConversionInvalidWithdrawalAddressErrorResponse": { "description": "The off-ramp destination bank account is missing or has an invalid field for the chosen withdrawal rail (e.g., `bic` is required for SEPA but absent). `causes[]` names each offending field and is non-empty.", "allOf": [ { "$ref": "#/components/schemas/PwsValidationErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsValidationError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "conversion_invalid_withdrawal_address" ] }, "causes": { "description": "One entry per missing or invalid beneficiary bank field.", "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Conversions_ConversionInvalidWithdrawalAddressCause" } } } } ] } } } ] }, "Conversions_ConversionInvalidWithdrawalAddressCause": { "description": "A single contributor to an invalid withdrawal address error. Each cause names one missing or invalid beneficiary bank field.", "type": "object", "required": [ "field", "message" ], "properties": { "field": { "description": "Dot-notation path to the offending request field (e.g., `to.bank_account.bic`).", "type": "string" }, "message": { "description": "Human-readable explanation of why the field is required or invalid for the chosen withdrawal rail.", "type": "string" } } }, "BondedEarn_BondedFeeSchedule": { "description": "The fee taken from a strategy's rewards, by the account's allocated volume. Each tier is the total fee charged.", "type": "object", "properties": { "volume_basis": { "title": "FeeVolumeBasis", "description": "What the volume in each tier counts. `strategy` is the account's allocation in this strategy, in the strategy's asset. `shared_usd` is the account's allocation in USD across every strategy on the same fee schedule, not counting funds in the exit queue or unbonding.", "type": "string", "enum": [ "strategy", "shared_usd" ] }, "tiers": { "description": "Tiers by ascending `min_volume`. The first starts at `\"0\"`.", "type": "array", "items": { "title": "BondedFeeTier", "description": "One tier of a fee schedule.", "type": "object", "properties": { "min_volume": { "description": "Allocation this tier applies from, in the unit `volume_basis` names, as a decimal string.", "type": "string" }, "fee_percentage": { "description": "Share of each reward taken as a fee, in percentage points as a decimal string (e.g., \"15\" means 15 percent).", "type": "string" } }, "required": [ "min_volume", "fee_percentage" ] } } }, "required": [ "volume_basis", "tiers" ] }, "BondedEarn_BondedStrategyPeriod": { "description": "Length of one lock-up phase of a bonded strategy.", "type": "object", "properties": { "type": { "title": "PeriodType", "description": "Whether `seconds` is a guarantee or an estimate.", "type": "string", "enum": [ "fixed", "variable" ] }, "seconds": { "description": "Length of the phase; zero for an instant strategy.", "type": "integer", "format": "int32", "minimum": 0 }, "rewards": { "title": "PeriodRewards", "description": "Whether the funds earn rewards during the phase.", "type": "string", "enum": [ "accruing", "not_accruing" ] } }, "required": [ "type", "seconds", "rewards" ] }, "AutoEarn_SetAutoEarnPreferencesData": { "description": "Response data for updated Auto Earn preferences.", "type": "object", "additionalProperties": false, "properties": {} }, "AutoEarn_AccountNotFoundError": { "description": "The requested account does not exist or is not accessible.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "account_not_found" ] } } } ] } } } ] }, "AutoEarn_NotEligibleError": { "description": "The account is not eligible for the requested Auto Earn preference.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "not_eligible" ] } } } ] } } } ] }, "AutoEarn_AllocationInProgressError": { "description": "Another allocation change is already in progress, so this request cannot be accepted yet.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "allocation_in_progress" ] } } } ] } } } ] }, "BondedEarn_AllocationInProgressError": { "description": "Another allocation change is already in progress, so this request cannot be accepted yet.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "allocation_in_progress" ] } } } ] } } } ] }, "BondedEarn_InsufficientBalanceError": { "description": "The account's earning balance in the strategy does not cover the requested deallocation `amount`.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "insufficient_balance" ] } } } ] } } } ] }, "BondedEarn_AmountTooHighError": { "description": "The requested `amount` is larger than the system can represent.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "amount_too_high" ] } } } ] } } } ] }, "BondedEarn_StrategyNotFoundError": { "description": "The strategy identified in the path does not exist.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "strategy_not_found" ] } } } ] } } } ] }, "BondedEarn_IdempotencyKeyReusedError": { "description": "The `Idempotency-Key` was already used for a request with a different strategy, `amount`, or direction.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "idempotency_key_reused" ] } } } ] } } } ] }, "BondedEarn_RequestConflictError": { "description": "The request conflicts with a request that was already recorded or is still running, for example because the idempotency key was already used for a different strategy or amount.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "request_conflict" ] } } } ] } } } ] }, "BondedEarn_BondedStrategyId": { "description": "Identifier of the bonded earn strategy.", "type": "string", "minLength": 20, "maxLength": 20, "pattern": "^ES[A-Z2-7]{5}-[A-Z2-7]{5}-[A-Z2-7]{6}$", "example": "ESQEFMZ-JPPIY-3KXFJ2" }, "BondedEarn_BondedAmount": { "description": "Amount in the strategy's asset, as a decimal string.", "type": "string", "minLength": 1, "maxLength": 64, "example": "2.0" }, "BondedEarn_BondedRequestAccepted": { "description": "Confirmation that an allocate or deallocate request was accepted.", "type": "object", "additionalProperties": false, "required": [ "request_id" ], "properties": { "request_id": { "description": "Identifier of the submitted request. Use it to look up the request status.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "BondedEarn_BondedRequestFailure": { "description": "Details of why a request failed.", "type": "object", "additionalProperties": false, "required": [ "reason", "message" ], "properties": { "reason": { "description": "Machine-readable failure reason. A deallocation can also return `insufficient_balance` when the request is submitted, with the same string. An allocation reports it only here. Other known values are `above_user_cap`, `not_eligible`, `canceled`, and `internal`. New values may be added, so treat an unknown value as a generic failure.", "type": "string" }, "message": { "description": "Human-readable explanation of the failure, for display and support. Branch on `reason` rather than on this text.", "type": "string" } } }, "BondedEarn_BondedStrategyType": { "description": "Whether the strategy has bonding and unbonding periods (`bonded`) or none (`instant`).", "type": "string", "enum": [ "bonded", "instant" ] }, "BondedEarn_BondedAllocationState": { "description": "Lifecycle state of a bonded allocation.", "type": "string", "enum": [ "bonding", "earning", "exit_queue", "unbonding" ] }, "BondedEarn_BondedAllocationTransitionState": { "description": "Lifecycle state with a pending transition. This excludes `earning`, unlike `BondedAllocationState`.", "type": "string", "enum": [ "bonding", "exit_queue", "unbonding" ] }, "BondedEarn_BondedNextAllocationTransition": { "description": "The next scheduled lifecycle transition for an allocation.", "type": "object", "additionalProperties": false, "required": [ "amount", "amount_in_quote", "state", "transitions_at" ], "properties": { "amount": { "description": "Amount in the strategy's native asset.", "type": "string" }, "amount_in_quote": { "description": "Amount converted to the requested quote asset.", "type": "string" }, "state": { "$ref": "#/components/schemas/BondedEarn_BondedAllocationState" }, "next_state": { "description": "State entered when the current state ends. Absent when the allocation is released after this transition.", "$ref": "#/components/schemas/BondedEarn_BondedAllocationState" }, "transitions_at": { "description": "When the allocation leaves its current state.", "$ref": "#/components/schemas/DateTime" }, "available_at": { "description": "When funds become available. For `exit_queue`, this is an estimate that includes the following unbonding period. Absent while bonding.", "$ref": "#/components/schemas/DateTime" } } }, "BondedEarn_BondedAllocation": { "description": "Current bonded earn allocation totals for one strategy.", "type": "object", "additionalProperties": false, "required": [ "strategy_id", "symbol", "type", "name", "strategy_type", "total", "total_in_quote", "bonding", "bonding_in_quote", "earning", "earning_in_quote", "exit_queue", "exit_queue_in_quote", "unbonding", "unbonding_in_quote" ], "properties": { "strategy_id": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyId" }, "symbol": { "description": "Ticker symbol of the strategy's asset (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name of the strategy's asset (e.g., \"Ethereum\").", "type": "string" }, "strategy_type": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyType" }, "total": { "description": "Total allocation amount in the strategy's native asset.", "type": "string" }, "total_in_quote": { "description": "Total allocation amount converted to the requested quote asset.", "type": "string" }, "bonding": { "description": "Amount currently bonding in the strategy's native asset.", "type": "string" }, "bonding_in_quote": { "description": "Bonding amount converted to the requested quote asset.", "type": "string" }, "earning": { "description": "Amount currently earning in the strategy's native asset.", "type": "string" }, "earning_in_quote": { "description": "Earning amount converted to the requested quote asset.", "type": "string" }, "exit_queue": { "description": "Amount currently in the exit queue in the strategy's native asset.", "type": "string" }, "exit_queue_in_quote": { "description": "Exit-queue amount converted to the requested quote asset.", "type": "string" }, "unbonding": { "description": "Amount currently unbonding in the strategy's native asset.", "type": "string" }, "unbonding_in_quote": { "description": "Unbonding amount converted to the requested quote asset.", "type": "string" }, "next_transition": { "description": "Soonest scheduled lifecycle transition for this strategy. Absent when no allocation is currently bonding, in the exit queue, or unbonding.", "$ref": "#/components/schemas/BondedEarn_BondedNextAllocationTransition" } } }, "BondedEarn_BondedAllocationTransition": { "description": "One pending lifecycle transition for a bonded earn allocation.", "type": "object", "additionalProperties": false, "required": [ "strategy_id", "symbol", "type", "name", "amount", "amount_in_quote", "state", "transitions_at" ], "properties": { "strategy_id": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyId" }, "symbol": { "description": "Ticker symbol of the strategy's asset (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name of the strategy's asset (e.g., \"Ethereum\").", "type": "string" }, "amount": { "description": "Amount in the strategy's native asset.", "type": "string" }, "amount_in_quote": { "description": "Amount converted to the requested quote asset.", "type": "string" }, "state": { "$ref": "#/components/schemas/BondedEarn_BondedAllocationState" }, "next_state": { "description": "State entered when the current state ends. Absent when the allocation is released after this transition.", "$ref": "#/components/schemas/BondedEarn_BondedAllocationState" }, "transitions_at": { "description": "When the allocation leaves its current state.", "$ref": "#/components/schemas/DateTime" }, "available_at": { "description": "When funds become available. For `exit_queue`, this is an estimate that includes the following unbonding period. Absent while bonding.", "$ref": "#/components/schemas/DateTime" } } }, "BondedEarn_BondedRequestStatus": { "description": "State of one allocate or deallocate request.", "type": "object", "additionalProperties": false, "required": [ "id", "idempotency_key", "request_type", "strategy_id", "symbol", "type", "name", "strategy_type", "amount", "status", "created_at" ], "properties": { "id": { "description": "Identifier of the request.", "type": "string" }, "idempotency_key": { "description": "The `Idempotency-Key` sent when the request was submitted, echoed back so clients can reconcile their own request log.", "type": "string" }, "request_type": { "title": "BondedRequestType", "description": "Whether the request allocates funds into the strategy or deallocates funds from it.", "type": "string", "enum": [ "allocate", "deallocate" ] }, "strategy_id": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyId" }, "symbol": { "description": "Ticker symbol of the strategy's asset (e.g., \"ETH\").", "type": "string" }, "type": { "title": "AssetType", "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "name": { "description": "Display name of the strategy's asset (e.g., \"Ethereum\").", "type": "string" }, "strategy_type": { "$ref": "#/components/schemas/BondedEarn_BondedStrategyType" }, "amount": { "description": "Amount the request asked for, in the strategy's asset, exactly as submitted. The settled amount can differ once it is rounded to the asset's own precision.", "type": "string" }, "status": { "title": "BondedRequestProcessingStatus", "description": "Current status of the request. `pending` requests have not been processed yet; `succeeded` and `failed` are final.", "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "created_at": { "description": "When the request was submitted.", "$ref": "#/components/schemas/DateTime" }, "completed_at": { "description": "When the request reached a final status. Absent while the request is pending.", "$ref": "#/components/schemas/DateTime" }, "error": { "description": "Why the request failed. Present only when `status` is `failed`.", "$ref": "#/components/schemas/BondedEarn_BondedRequestFailure" } } }, "Funding_FundingMethodsResult": { "description": "A page of funding method metadata. Repeat the same lookup identifiers and direction when requesting another page.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Metadata for methods matching the lookup. A returned method is not necessarily available for deposits or withdrawals through PWS. Use the account’s deposit-methods or withdrawal-methods discovery endpoint to discover supported methods. Results are refreshed on each request.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_FundingMethodMetadata" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_FundingMethodDirection": { "description": "Whether a funding method receives or sends funds.", "type": "string", "enum": [ "deposit", "withdrawal" ] }, "Funding_FundingMethodMetadata": { "description": "Descriptive information about a funding method.", "type": "object", "required": [ "id", "direction", "asset", "method", "payment_rails", "requirements" ], "properties": { "id": { "description": "Identifier used to reference this funding method.", "type": "string", "format": "uuid" }, "direction": { "description": "Movement of funds represented by this method.", "$ref": "#/components/schemas/Funding_FundingMethodDirection" }, "asset": { "description": "Asset received or sent through this method.", "$ref": "#/components/schemas/Funding_FundingMethodAsset" }, "method": { "description": "Human-readable display name of the method.", "type": "string", "minLength": 1 }, "network": { "description": "Network identity and metadata, when reported for this method.", "$ref": "#/components/schemas/Funding_FundingMethodNetwork" }, "payment_rails": { "description": "Reported payment rails. May be empty for a fiat method, including SEPA, when no recognized rail is reported.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_FundingPaymentRail" } }, "requirements": { "description": "Reported method requirements. Other execution requirements may apply.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_FundingMethodRequirement" } } } }, "Funding_FundingMethodAsset": { "description": "Public identity of the asset supported by a funding method.", "type": "object", "required": [ "symbol", "name", "type" ], "properties": { "symbol": { "description": "Public ticker symbol identifying the asset.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable English asset name.", "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "description": "Public classification of the asset.", "$ref": "#/components/schemas/Funding_AssetType" } } }, "Funding_FundingMethodNetwork": { "description": "Network metadata for this method and asset. Each optional detail is reported independently.", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "description": "Identifier of the network used by this method.", "type": "string", "format": "uuid" }, "name": { "description": "Human-readable network name.", "type": "string", "minLength": 1 }, "explorer": { "description": "Blockchain explorer URL or transaction URL template.", "type": "string", "minLength": 1 }, "confirmations": { "description": "Required confirmation count or network-specific confirmation description.", "type": "string", "minLength": 1 }, "est_confirmation_time": { "description": "Estimated time to reach the required confirmations.", "type": "string", "minLength": 1 }, "contract_address": { "description": "Token contract address on this network, when applicable.", "type": "string", "minLength": 1 }, "on_chain_asset_symbol": { "description": "Symbol used for the asset on this network.", "type": "string", "minLength": 1 } } }, "Funding_FundingPaymentRail": { "description": "Payment rail explicitly reported for a funding method.", "type": "string", "enum": [ "sepa", "swift", "fps", "ach", "rtp" ] }, "Funding_FundingMethodRequirement": { "description": "`bank_link` means a linked bank account is required; it does not indicate whether the account is already linked.", "type": "string", "enum": [ "bank_link" ] }, "Funding_CreateDepositBody": { "description": "A deposit from a supported payment source.", "type": "object", "required": [ "method_id", "asset_symbol", "amount", "source" ], "properties": { "method_id": { "description": "Identifier returned by deposit-method discovery for the selected account and asset.", "type": "string", "format": "uuid" }, "asset_symbol": { "description": "Public symbol of the asset to deposit.", "$ref": "#/components/schemas/AssetSymbol" }, "amount": { "description": "Amount to pull, expressed in the asset's units.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "source": { "description": "Linked bank account to debit for the deposit.", "$ref": "#/components/schemas/Funding_DepositSource" } } }, "Funding_DepositSource": { "description": "Source of funds for the deposit.", "oneOf": [ { "$ref": "#/components/schemas/Funding_AccountLinkDepositSource" } ], "discriminator": { "propertyName": "type", "mapping": { "account_link": "#/components/schemas/Funding_AccountLinkDepositSource" } } }, "Funding_AccountLinkDepositSource": { "title": "Account link", "description": "Linked bank account used as the deposit source.", "type": "object", "required": [ "type", "account_link_id" ], "properties": { "type": { "description": "Source kind.", "type": "string", "enum": [ "account_link" ] }, "account_link_id": { "description": "Identifier of the active linked bank account to debit.", "type": "string", "pattern": "^al_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } }, "Funding_CreateDepositResult": { "description": "Accepted deposit reference.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Initiated deposit.", "$ref": "#/components/schemas/Funding_CreatedDeposit" } } }, "Funding_CreatedDeposit": { "description": "Result of deposit initiation.", "type": "object", "properties": { "reference": { "description": "Opaque reference used to correlate the deposit with its corresponding account transaction. It is distinct from the transaction ID, and its presence confirms initiation rather than settlement. Always returned for bank-link deposits.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_ClaimDepositAddressBody": { "description": "Crypto funding method whose deposit address should be claimed.", "type": "object", "required": [ "method_id" ], "properties": { "method_id": { "description": "Crypto funding method identifier returned by the deposit-methods endpoint.", "type": "string", "format": "uuid" } } }, "Funding_SimulateFundingDepositBody": { "description": "Funding method, amount, and optional reconciliation details for a synthetic successful deposit.", "type": "object", "additionalProperties": false, "required": [ "method_id", "amount" ], "properties": { "method_id": { "description": "Funding method identifier returned by the deposit-methods endpoint for the selected account.", "type": "string", "format": "uuid" }, "amount": { "description": "Positive decimal amount to deposit, represented as a string to preserve precision.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "name": { "description": "Payer name copied into the simulated deposit. When omitted, a fiat deposit uses the account holder's name, so it passes the payer name check.", "type": "string", "minLength": 1, "maxLength": 128 }, "reference": { "description": "Optional payment reference copied into the simulated deposit for test reconciliation.", "type": "string", "minLength": 1, "maxLength": 140 } } }, "Funding_SimulateFundingDepositResult": { "description": "Acknowledgment that the synthetic deposit was accepted.", "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Funding_FundingDepositSimulation" } } }, "Funding_FundingDepositSimulation": { "description": "Result of a funding deposit simulation request.", "type": "object", "additionalProperties": false, "required": [ "simulated" ], "properties": { "simulated": { "description": "Whether the synthetic deposit was accepted for processing.", "type": "boolean" } } }, "Funding_ClaimDepositAddressResult": { "description": "Claimed crypto deposit address for the selected account.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Claimed deposit address.", "$ref": "#/components/schemas/Funding_DepositAddress" } } }, "Funding_ListDepositAddressesResult": { "description": "Available deposit addresses for the selected account and funding method. A page token is valid only with the same account and method.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Deposit destinations valid for the requested method. Static destinations precede claimed destinations, and a destination may be valid for multiple assets or networks. Empty when none can be used with the method.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_ListedDepositAddress" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_ListedDepositAddress": { "description": "Crypto address or fiat account to which a deposit can be sent.", "type": "object", "required": [ "address_details" ], "properties": { "address_details": { "description": "Crypto or fiat destination details to use when sending the deposit.", "$ref": "#/components/schemas/Funding_DepositAddressDetails" }, "expire_time": { "description": "Time after which the claimed address should no longer be used. Omitted when the address does not expire and for other address types.", "type": "string", "format": "date-time" } } }, "Funding_DepositAddressDetails": { "description": "Crypto or fiat deposit destination details. Exactly one variant is present.", "oneOf": [ { "$ref": "#/components/schemas/Funding_CryptoDepositAddressDetails" }, { "$ref": "#/components/schemas/Funding_FiatDepositAddressDetails" } ] }, "Funding_CryptoDepositAddressDetails": { "title": "Crypto", "description": "Crypto deposit destination details.", "type": "object", "required": [ "crypto" ], "properties": { "crypto": { "description": "Crypto deposit destination.", "$ref": "#/components/schemas/Funding_DepositAddressCrypto" } } }, "Funding_FiatDepositAddressDetails": { "title": "Fiat", "description": "Fiat deposit destination details.", "type": "object", "required": [ "fiat" ], "properties": { "fiat": { "description": "Bank-transfer deposit destination.", "$ref": "#/components/schemas/Funding_DepositAddressFiat" } } }, "Funding_DepositAddressCrypto": { "description": "Crypto deposit address and any required network routing information.", "type": "object", "required": [ "address" ], "properties": { "address": { "description": "Address to which the deposit must be sent.", "type": "string", "minLength": 1 }, "tag": { "description": "Destination tag required by the network, when applicable.", "type": "string", "minLength": 1 }, "memo": { "description": "Destination memo required by the network, when applicable.", "type": "string", "minLength": 1 } } }, "Funding_DepositAddressFiat": { "description": "Bank-transfer destination and routing details for a deposit.", "type": "object", "properties": { "account_number": { "description": "Bank account number.", "type": "string", "minLength": 1 }, "account_type": { "description": "Bank account type.", "type": "string", "minLength": 1 }, "address": { "description": "Address associated with the destination account.", "type": "string", "minLength": 1 }, "bank": { "description": "Bank name.", "type": "string", "minLength": 1 }, "bank_code": { "description": "Bank code.", "type": "string", "minLength": 1 }, "bic": { "description": "Bank identifier code (BIC).", "type": "string", "minLength": 1 }, "branch": { "description": "Bank branch.", "type": "string", "minLength": 1 }, "bank_address": { "description": "Bank address.", "type": "string", "minLength": 1 }, "bsb": { "description": "Bank State Branch (BSB) code.", "type": "string", "minLength": 1 }, "iban": { "description": "International Bank Account Number (IBAN).", "type": "string", "minLength": 1 }, "memo": { "description": "Payment memo supplied with the destination, when applicable.", "type": "string", "minLength": 1 }, "name_on_account": { "description": "Account holder name.", "type": "string", "minLength": 1 }, "routing_number": { "description": "Bank routing number.", "type": "string", "minLength": 1 }, "sort_code": { "description": "Bank sort code.", "type": "string", "minLength": 1 }, "swift": { "description": "SWIFT code.", "type": "string", "minLength": 1 }, "tag": { "description": "Destination tag, when applicable.", "type": "string", "minLength": 1 }, "transit": { "description": "Bank transit number.", "type": "string", "minLength": 1 }, "reference": { "description": "Payment reference that must be included with the fiat deposit, when applicable.", "type": "string", "minLength": 1 } } }, "Funding_DepositAddress": { "description": "Crypto deposit address and any network-specific routing information.", "type": "object", "required": [ "address" ], "properties": { "address": { "description": "Address or account identifier to which the deposit must be sent.", "type": "string", "minLength": 1 }, "tag": { "description": "Destination tag required by the network, when applicable.", "type": "string", "minLength": 1 }, "memo": { "description": "Destination memo required by the network, when applicable.", "type": "string", "minLength": 1 }, "expires_at": { "description": "Time after which the address should no longer be used. Omitted when the address does not expire.", "type": "string", "format": "date-time" } } }, "Funding_CreateLightningInvoiceBody": { "description": "Asset and exact amount the Lightning invoice should request.", "type": "object", "required": [ "asset_symbol", "amount" ], "properties": { "asset_symbol": { "description": "Public symbol of the asset to deposit over the Bitcoin Lightning Network.", "$ref": "#/components/schemas/AssetSymbol" }, "amount": { "description": "Exact amount requested by the invoice, denominated in `asset_symbol` and represented as a string to preserve precision.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "Funding_CreateLightningInvoiceResult": { "description": "Lightning invoice created for the selected account.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Created Lightning invoice.", "$ref": "#/components/schemas/Funding_LightningInvoice" } } }, "Funding_LightningInvoice": { "description": "Single-use BOLT11 payment request for a Bitcoin Lightning Network deposit.", "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "description": "BOLT11 payment request to pay in full over the Lightning Network. It encodes the exact amount and can be paid only once.", "type": "string", "minLength": 1 }, "expires_at": { "description": "Time after which the invoice can no longer be paid. Omitted when the invoice does not expire.", "type": "string", "format": "date-time" } } }, "Funding_TransferStatus": { "description": "Transfer creation status.", "type": "string", "enum": [ "pending", "complete", "failed" ] }, "Funding_Transfer": { "description": "Created transfer.", "type": "object", "required": [ "transfer_id", "status" ], "properties": { "transfer_id": { "description": "Opaque transfer identifier. Use it as `reference.id` with `reference.kind=transfer` when listing Portfolio transactions for the account supplied in `from`. The transaction can appear after this response and has its own `TX` identifier and status.", "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "description": "Current transfer-creation status. `pending` means creation is still being processed, `complete` means creation has completed, and `failed` means creation could not be completed. This is separate from the corresponding Portfolio transaction's status.", "$ref": "#/components/schemas/Funding_TransferStatus" } } }, "Funding_CreateTransferEnvelope": { "description": "Response returned after creating a transfer.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Created transfer.", "$ref": "#/components/schemas/Funding_Transfer" } } }, "DerivativeTransfers_DerivativesTransferLocation": { "description": "Balance location.", "type": "string", "enum": [ "spot", "futures" ] }, "DerivativeTransfers_DerivativesTransferStatus": { "description": "Transfer creation status.", "type": "string", "enum": [ "accepted" ] }, "DerivativeTransfers_DerivativesTransfer": { "description": "Derivatives transfer result.", "type": "object", "required": [ "transfer_id", "status" ], "properties": { "transfer_id": { "description": "Identifier used to reconcile the transfer.", "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "description": "The transfer has been accepted for processing. This does not confirm settlement.", "$ref": "#/components/schemas/DerivativeTransfers_DerivativesTransferStatus" } } }, "DerivativeTransfers_CreateDerivativesTransferEnvelope": { "description": "Derivatives transfer response.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Transfer result.", "$ref": "#/components/schemas/DerivativeTransfers_DerivativesTransfer" } } }, "Funding_DepositMethodsResult": { "description": "Deposit methods available for the requested asset.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Deposit methods currently available to the account and asset. Empty when the account has no eligible methods.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_DepositMethod" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_DepositLimitsResult": { "description": "Account-specific deposit limits for the requested asset.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Deposit limits by funding method. Empty when no per-method limits are published for the asset.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_DepositMethodLimits" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_DepositMethodLimits": { "description": "Account-specific deposit limits for one funding method.", "type": "object", "required": [ "method_id", "period_limits" ], "properties": { "method_id": { "description": "Identifier of the deposit method these limits apply to. Use this entry only when its `method_id` appears in the List deposit methods response for the same account and asset.", "type": "string", "format": "uuid" }, "maximum_amount": { "description": "Largest currently permitted amount after applying the account's amount-based limits. Excludes the method's per-transaction cap and count-based limits. Other controls may apply. Zero means no amount remains under the aggregate amount limit. Omitted when no amount-based limit applies.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "period_limits": { "description": "Rolling limits exposed by this API for deposits through the method. This list is informational and may not include every policy that applies. Empty when there are no supported limits to report.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_DepositLimit" } } } }, "Funding_DepositMethod": { "description": "A deposit method available to the selected account.", "type": "object", "required": [ "id", "asset", "method", "requirements" ], "properties": { "id": { "description": "Stable method identifier. Use it to select this method for deposit instructions, activation, or supported deposit creation. Crypto address claims also use this identifier.", "type": "string", "format": "uuid" }, "network": { "description": "Customer-facing blockchain network or deposit-method name.", "type": "string", "minLength": 1 }, "method": { "description": "Customer-facing funding-method display name.", "type": "string", "minLength": 1 }, "network_info": { "description": "Blockchain network metadata.", "$ref": "#/components/schemas/Funding_NetworkInfo" }, "fee": { "description": "Fixed deposit fee in the reported asset. Omitted when unavailable or zero.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "fee_percentage": { "description": "Percentage points charged on the deposit. For example, `1.5` means 1.5 percent. Omitted when no percentage fee applies.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "minimum": { "description": "Minimum amount accepted per deposit transaction. Omitted when the method has no minimum.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "maximum": { "description": "Maximum amount accepted per deposit transaction for this method. Omitted when no method maximum is reported. Account-specific and rolling limits are not included.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "address_setup_fee": { "description": "One-time fee applied to the first creditable deposit received at the address, in the reported asset. It is not charged when the address is claimed. Omitted when unavailable or zero.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "asset": { "description": "Asset supported by this deposit method.", "$ref": "#/components/schemas/Funding_FundingMethodAsset" }, "activation_status": { "description": "Activation state for this account and method. `needed` requires activation before use, `pending` means activation or address assignment is still in progress, `completed` means activation has finished, and `not_needed` means no activation is required. This is separate from deposit-address claim status. Activate only when `needed`; while `pending`, poll the deposit-methods endpoint instead of submitting another activation request. Omitted when no recognized state is available.", "$ref": "#/components/schemas/Funding_FundingMethodActivationStatus" }, "supports_virtual_accounts": { "description": "Whether the method supports dedicated virtual-account instructions. `false` does not identify which alternative instructions are available. Omitted when this capability is not reported.", "type": "boolean" }, "requirements": { "description": "Method-level requirements for initiating a deposit, regardless of whether the user has already satisfied them. Empty when no supported requirements are reported.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_DepositMethodRequirement" } } } }, "Funding_DepositMethodRequirement": { "description": "A requirement for initiating a deposit. `bank_link` means a linked bank account is required; use the bank-link APIs to check or create the link. This does not indicate whether the user already has a linked account.", "type": "string", "enum": [ "bank_link" ] }, "Funding_FundingMethodActivationStatus": { "description": "Activation state of a deposit method for the selected account, separate from deposit-address claim status.", "type": "string", "enum": [ "not_needed", "needed", "pending", "completed" ] }, "Funding_FundingAmount": { "description": "Decimal amount denominated in an asset.", "type": "object", "required": [ "symbol", "type", "amount" ], "properties": { "symbol": { "description": "Asset symbol the amount is denominated in.", "$ref": "#/components/schemas/AssetSymbol" }, "name": { "description": "Human-readable English asset name.", "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "description": "Public asset classification.", "$ref": "#/components/schemas/Funding_AssetType" }, "amount": { "description": "Decimal value denominated in `symbol`, represented as a string to preserve precision.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "Funding_FundingAssetReference": { "description": "Reference to an asset by ticker symbol and classification.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset ticker symbol, such as BTC, USD, or TSLAx.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/Funding_AssetType" } } }, "Funding_AssetType": { "description": "Public classification of an asset used by funding resources.", "type": "string", "enum": [ "fiat", "crypto", "stablecoin", "xstock" ] }, "Funding_NetworkInfo": { "description": "Blockchain network metadata for the funding method.", "type": "object", "required": [ "explorer", "confirmations", "est_confirmation_time" ], "properties": { "explorer": { "description": "Blockchain explorer URL or transaction URL template for the network.", "type": "string", "minLength": 1 }, "confirmations": { "description": "Required confirmation count or network-specific confirmation description.", "type": "string", "minLength": 1 }, "est_confirmation_time": { "description": "Estimated time to reach the required confirmations.", "type": "string", "minLength": 1 }, "contract_address": { "description": "Token contract address on this network, when applicable.", "type": "string", "minLength": 1 } } }, "Funding_DepositLimit": { "description": "One account-specific limit for deposits through a method and rolling time window.", "type": "object", "required": [ "type", "period", "period_seconds", "remaining", "maximum" ], "properties": { "type": { "description": "Unit controlled by the limit.", "$ref": "#/components/schemas/Funding_DepositLimitType" }, "period": { "description": "Human-readable label for the rolling time window.", "$ref": "#/components/schemas/Funding_DepositLimitPeriod" }, "period_seconds": { "description": "Exact rolling-window duration in seconds.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 4294967295 }, "asset": { "description": "Asset in which an `amount` limit is denominated. Present for amount limits and omitted for count-based limits.", "$ref": "#/components/schemas/Funding_FundingAssetReference" }, "remaining": { "description": "Remaining amount or deposit count in this rolling window. A negative value means the limit is already exceeded.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "maximum": { "description": "Maximum amount or deposit count allowed in this rolling window.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "Funding_DepositLimitType": { "description": "Type of deposit limit exposed by this API. Additional deposit controls may apply.", "type": "string", "enum": [ "amount", "deposit_attempts", "successful_deposits" ] }, "Funding_DepositLimitPeriod": { "description": "Human-readable rolling-window label. `daily`, `weekly`, and `monthly` mean rolling 24-hour, 7-day, and 30-day windows; `custom` uses `period_seconds`.", "type": "string", "enum": [ "daily", "weekly", "monthly", "custom" ] }, "Funding_WithdrawalMethodsResult": { "description": "Withdrawal methods available for the requested asset.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Withdrawal methods currently configured for the selected account and asset. Empty when no methods are available.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_WithdrawalMethod" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_WithdrawalLimitsResult": { "description": "Account-specific withdrawal limits for the requested asset.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Withdrawal limits by funding method. Empty when no per-method limits are published for the asset.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_WithdrawalMethodLimits" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_WithdrawalMethodLimits": { "description": "Account-specific withdrawal limits for one funding method.", "type": "object", "required": [ "method_id", "maximum_amount", "maximum_reason", "period_limits" ], "properties": { "method_id": { "description": "Identifier of the withdrawal method these limits apply to. The method must be available to the same account and asset.", "type": "string", "format": "uuid" }, "maximum_amount": { "description": "Maximum amount currently allowed after applying available balance, amount-based limits, and the asset's supported decimal precision. A negative maximum is returned as zero. Count-based limits may still prevent another withdrawal.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "maximum_reason": { "description": "Constraint that determined `maximum_amount`.", "$ref": "#/components/schemas/Funding_WithdrawalMaximumReason" }, "period_limits": { "description": "Rolling limits exposed by this API for withdrawals through the method. This list is informational and may not include every policy that applies. Empty when there are no supported limits to report.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_WithdrawalLimit" } } } }, "Funding_WithdrawalMaximumReason": { "description": "Constraint that determined a method's maximum withdrawal amount. `balance` is the account's available balance, which excludes funds under an active withdrawal hold; list withdrawal holds to see held amounts and when they are scheduled to be released. `limits` is an amount-based funding limit, and `precision` the largest amount the asset's decimal precision can represent.", "type": "string", "enum": [ "balance", "limits", "precision" ] }, "Funding_WithdrawalHoldsResult": { "description": "Active withdrawal holds on the selected account.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Withdrawal holds ordered by scheduled release time, earliest first. Empty when no funds are held.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_WithdrawalHold" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_WithdrawalHold": { "description": "Funds in the selected account that are temporarily unavailable for withdrawal.", "type": "object", "required": [ "asset", "equivalent_amount", "release_at", "type" ], "properties": { "asset": { "description": "Asset whose balance is held.", "$ref": "#/components/schemas/Funding_FundingAssetReference" }, "equivalent_amount": { "description": "Current value of the held funds, expressed in USD.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "release_at": { "description": "Time the withdrawal restriction is scheduled to end. A hold can end earlier, for example when it is lifted or its deposit is returned. Other restrictions may still prevent withdrawal after this hold ends.", "type": "string", "format": "date-time" }, "type": { "description": "Activity the hold was placed for.", "$ref": "#/components/schemas/Funding_WithdrawalHoldType" }, "deposit_transaction_id": { "description": "Identifier of the deposit the hold was placed for, matching the `transaction_id` of that deposit's webhooks. Present only for `deposit` holds.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Funding_WithdrawalHoldType": { "description": "Activity a withdrawal hold was placed for. `deposit` holds recently credited deposit funds, such as a bank transfer that can still be reversed; `other` covers every other kind of hold.", "type": "string", "enum": [ "deposit", "other" ] }, "Funding_WithdrawalMethod": { "description": "A withdrawal method available to the selected account.", "type": "object", "required": [ "id", "asset", "method", "address_fields", "requirements" ], "properties": { "id": { "description": "Stable identifier used to register and list withdrawal addresses.", "type": "string", "format": "uuid" }, "network_id": { "description": "Identifier of the network this method belongs to. Supply it as `network_id` when registering one address that is valid for every method on the network, instead of scoping the address to this method alone. Omitted when the method has no network.", "type": "string", "format": "uuid" }, "network": { "description": "Customer-facing blockchain network or withdrawal-method name.", "type": "string", "minLength": 1 }, "method": { "description": "Customer-facing funding-method display name.", "type": "string", "minLength": 1 }, "network_info": { "description": "Blockchain network metadata.", "$ref": "#/components/schemas/Funding_NetworkInfo" }, "fee": { "description": "Indicative fixed withdrawal fee in the reported asset. Omitted when unavailable or zero; omission does not imply a fee-free withdrawal. Use Calculate funding fees for an amount-specific quote.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "fee_percentage": { "description": "Indicative percentage points charged on the withdrawal. For example, `1.5` means 1.5 percent. Omitted when no percentage fee is reported; omission does not imply a fee-free withdrawal.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "minimum": { "description": "Minimum amount accepted per withdrawal transaction. Omitted when the method has no minimum.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "maximum": { "description": "Maximum amount accepted per withdrawal transaction by this method, independent of account balance and remaining rolling limits. Omitted when the method does not provide a cap; omission does not imply unlimited withdrawals. Use the withdrawal-limits endpoint for account constraints.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "asset": { "description": "Asset supported by this withdrawal method.", "$ref": "#/components/schemas/Funding_FundingMethodAsset" }, "address_fields": { "description": "Address fields a partner must collect to register a withdrawal address for this method. Empty when the method requires no address fields beyond what Payward Services already verifies for the account.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_WithdrawalAddressField" } }, "requirements": { "description": "Method-level requirements, regardless of whether the selected account already satisfies them. `bank_link` means an eligible linked bank account is required but does not indicate whether one is already linked. Empty when no supported requirements are reported.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_WithdrawalMethodRequirement" } } } }, "Funding_WithdrawalMethodRequirement": { "description": "A requirement of the withdrawal method. `bank_link` means an eligible linked bank account is required. It does not indicate whether the selected account already has one.", "type": "string", "enum": [ "bank_link" ] }, "Funding_WithdrawalAddressField": { "description": "One destination field collected when registering a funding address for a method.", "type": "object", "required": [ "key", "required", "allowed_values" ], "properties": { "key": { "description": "Address field to collect.", "$ref": "#/components/schemas/Funding_WithdrawalAddressFieldKey" }, "required": { "description": "Whether this field must be provided when registering the address.", "type": "boolean" }, "allowed_values": { "description": "Choices accepted for this field by the selected method. Use a listed value when choices are provided. An empty list does not make the field optional; method-specific validation still applies.", "type": "array", "items": { "type": "string" } } } }, "Funding_CreateFundingAddressScope": { "description": "What a new user-added funding address is registered against. `method_id` registers it for one withdrawal method. `network_id` registers one address valid for every method on that network.\n\nSupply exactly one identifier. The request is rejected when the selected scope is not supported.", "type": "object", "properties": { "method_id": { "description": "Withdrawal funding method identifier returned by the withdrawal-methods endpoint. Registers the address for that single method.", "type": "string", "format": "uuid" }, "network_id": { "description": "Network identifier returned by the withdrawal-methods endpoint. Registers one address valid for every withdrawal method on the network.", "type": "string", "format": "uuid" } } }, "Funding_FundingAddressScope": { "description": "Scope of the saved funding address. Exactly one identifier is present.", "type": "object", "properties": { "method_id": { "description": "Withdrawal method identifier associated with the address.", "type": "string", "format": "uuid" }, "network_id": { "description": "Network identifier associated with the address.", "type": "string", "format": "uuid" }, "network_group_id": { "description": "Network-group identifier associated with the address.", "type": "string", "format": "uuid" } } }, "Funding_FundingAddressDetails": { "description": "Details for the user-added funding address, as a fiat bank account or a crypto address.\n\nSupply exactly one branch. Its properties are validated for the requested scope.", "type": "object", "properties": { "fiat": { "description": "Bank account used as the withdrawal destination.", "$ref": "#/components/schemas/Funding_FundingFiatAddress" }, "crypto": { "description": "Crypto address used as the withdrawal destination.", "$ref": "#/components/schemas/Funding_FundingCryptoAddress" } } }, "Funding_FundingFiatAddress": { "description": "Bank account details for a fiat withdrawal destination. For a destination owned by the selected account holder, the account-holder name comes from verified account information.", "type": "object", "properties": { "iban": { "description": "IBAN identifying the destination bank account. Required only when the selected scope calls for it.", "type": "string", "minLength": 1, "maxLength": 34 }, "bic": { "description": "Bank identifier code for the destination bank. Required only when the selected scope calls for it.", "type": "string", "minLength": 1, "maxLength": 11 }, "swift": { "description": "SWIFT code for the destination bank. Required only when the selected scope calls for it.", "type": "string", "minLength": 1, "maxLength": 11 }, "sort_code": { "description": "Sort code for the destination bank account. Required only when the selected scope calls for it.", "type": "string", "minLength": 1, "maxLength": 16 }, "routing_number": { "description": "Routing number for the destination bank account. Required only when the selected scope calls for it.", "type": "string", "minLength": 1, "maxLength": 34 }, "bsb": { "description": "Bank-State-Branch code for the destination bank account. Required only when the selected scope calls for it.", "type": "string", "minLength": 1, "maxLength": 16 }, "account_number": { "description": "Destination bank account number. Required only when the selected scope calls for it.", "type": "string", "minLength": 1, "maxLength": 64 }, "address": { "description": "Bank address required by the selected scope, when applicable.", "type": "string", "minLength": 1, "maxLength": 256 }, "tag": { "description": "Destination tag required by the selected scope, when applicable.", "type": "string", "minLength": 1, "maxLength": 64 }, "memo": { "description": "Destination memo required by the selected scope, when applicable.", "type": "string", "minLength": 1, "maxLength": 256 }, "bank": { "description": "Name of the destination bank. Required only when the selected scope calls for it.", "type": "string", "minLength": 1 }, "account_type": { "description": "Type of the destination bank account. Use a choice from the selected method's address-field allowed_values when the list is non-empty. Validated when the address is registered.", "type": "string", "minLength": 1 } } }, "Funding_FundingCryptoAddress": { "description": "Crypto address details for the funding address.", "type": "object", "required": [ "address" ], "properties": { "address": { "description": "Destination crypto address accepted by the selected scope.", "type": "string", "minLength": 1, "maxLength": 256 }, "tag": { "description": "Destination tag required by the selected scope, when applicable.", "type": "string", "minLength": 1, "maxLength": 64 }, "memo": { "description": "Destination memo required by the selected scope, when applicable.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_WithdrawalAddressFieldKey": { "description": "Address field collected when registering a funding address. When `account_or_iban` is required, supply either `account_number` or `iban`.", "type": "string", "enum": [ "iban", "bic", "swift", "sort_code", "routing_number", "bsb", "account_number", "account_or_iban", "address", "tag", "memo", "bank", "account_type" ] }, "Funding_WithdrawalLimit": { "description": "One account-specific limit for withdrawals through a method and rolling time window.", "type": "object", "required": [ "type", "period", "period_seconds", "remaining", "maximum" ], "properties": { "type": { "description": "Unit controlled by the limit.", "$ref": "#/components/schemas/Funding_WithdrawalLimitType" }, "period": { "description": "Human-readable label for the rolling time window.", "$ref": "#/components/schemas/Funding_WithdrawalLimitPeriod" }, "period_seconds": { "description": "Exact rolling-window duration in seconds.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 4294967295 }, "asset": { "description": "Asset in which an `amount` limit is denominated. Present for amount limits and omitted for count-based limits.", "$ref": "#/components/schemas/Funding_FundingAssetReference" }, "remaining": { "description": "Remaining amount or withdrawal count in this rolling window. A negative value means the limit is already exceeded.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "maximum": { "description": "Maximum amount or withdrawal count allowed in this rolling window.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "Funding_WithdrawalLimitType": { "description": "Type of withdrawal limit exposed by this API. Additional withdrawal controls may apply.", "type": "string", "enum": [ "amount", "withdrawal_attempts", "successful_withdrawals" ] }, "Funding_WithdrawalLimitPeriod": { "description": "Human-readable rolling-window label. `daily`, `weekly`, and `monthly` mean rolling 24-hour, 7-day, and 30-day windows; `custom` uses `period_seconds`.", "type": "string", "enum": [ "daily", "weekly", "monthly", "custom" ] }, "Funding_CreateFundingAddressBody": { "description": "Scope, label, and destination details for a user-added funding address.", "type": "object", "required": [ "scope", "name", "address_details" ], "properties": { "scope": { "description": "Address registration scope. Either a single withdrawal method or a whole network.", "$ref": "#/components/schemas/Funding_CreateFundingAddressScope" }, "name": { "description": "Partner-provided label for the funding address. It must be unique across the account owner's withdrawal addresses, regardless of funding method. Surrounding whitespace is removed, and whitespace-only labels are rejected.", "type": "string", "minLength": 1, "maxLength": 64 }, "address_details": { "description": "Destination details for the funding address. Supply exactly one fiat bank account or crypto address.", "$ref": "#/components/schemas/Funding_FundingAddressDetails" } } }, "Funding_UpdateFundingAddressBody": { "description": "Updates to apply to a user-added funding address.", "type": "object", "required": [ "name" ], "properties": { "name": { "description": "New partner-provided label for the funding address. It must be unique across the account owner's withdrawal addresses, regardless of funding method. Surrounding whitespace is removed, and whitespace-only labels are rejected.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Funding_CreateFundingAddressResult": { "description": "Funding address registered for the selected account.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Registered funding address.", "$ref": "#/components/schemas/Funding_FundingAddress" } } }, "Funding_CreateWithdrawalScope": { "description": "Funding method or network to use for the withdrawal. Supply exactly one identifier. Network scope resolves only when exactly one method is available for the asset.", "type": "object", "properties": { "method_id": { "description": "Withdrawal funding method identifier returned by the withdrawal-methods endpoint. Required for Account Link destinations and when supplying `fee_token`; use the method selected for the quote.", "type": "string", "format": "uuid" }, "network_id": { "description": "Funding network identifier returned by the withdrawal-methods endpoint. Supported for funding-address destinations without `fee_token`. Returns `400` if the network does not resolve to exactly one method for the asset; supply `method_id` to select a specific method.", "type": "string", "format": "uuid" } } }, "Funding_CalculateFundingFeesBody": { "description": "Deposit or withdrawal funding method and gross amount for which to create a fee quote.", "type": "object", "required": [ "method_id", "amount" ], "properties": { "method_id": { "description": "Funding method identifier returned as `id` by List deposit methods or List withdrawal methods. The method must support fee quotes.", "type": "string", "format": "uuid" }, "amount": { "description": "Positive gross amount to quote, including the fee, represented as a string to preserve precision.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "Funding_CalculateFundingFeesResult": { "description": "Funding fee quote created for the selected account.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Fee quote for the requested method and gross amount.", "$ref": "#/components/schemas/Funding_WithdrawalFeeQuote" } } }, "Funding_WithdrawalFeeQuote": { "description": "Fee quote for one funding method and gross amount.", "type": "object", "required": [ "fee", "gross_amount", "net_amount" ], "properties": { "fee": { "description": "Fee calculated for `gross_amount`.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "gross_amount": { "description": "Gross amount used for the quote. Equals the submitted `amount` and the sum of `net_amount` and `fee`.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "net_amount": { "description": "Amount remaining after subtracting `fee` from `gross_amount`.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "fee_token": { "description": "Short-lived opaque token returned when the method supports reusing this quote's fee terms with Create withdrawal. May be returned for fiat or crypto methods. Use it only for the same selected account and `method_id`. Network scope is not supported. The withdrawal amount determines the fee, so use `gross_amount.amount` from this quote to reproduce the displayed fee. Request a new quote if the token is rejected. Treat this value as sensitive and do not inspect or modify it.", "type": "string", "minLength": 1, "maxLength": 2000 } } }, "Funding_CreateWithdrawalBody": { "description": "Funding scope, destination, asset symbol, gross amount, and optional fee quote token for a withdrawal.", "type": "object", "additionalProperties": false, "required": [ "scope", "destination", "symbol", "amount" ], "properties": { "scope": { "description": "Method or network scope used for the withdrawal.", "$ref": "#/components/schemas/Funding_CreateWithdrawalScope" }, "destination": { "$ref": "#/components/schemas/Funding_WithdrawalDestination" }, "symbol": { "description": "Public asset symbol to withdraw. Fiat, crypto, and stablecoin assets are supported in this operation.", "$ref": "#/components/schemas/AssetSymbol" }, "amount": { "description": "Gross amount debited from the selected account, including the fee, represented as a string to preserve precision.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "fee_token": { "description": "Fee token from Calculate funding fees whose fee terms this withdrawal should reuse. Requires `scope.method_id` for the quoted method. A different amount changes the fee charged; use the quoted amount to reproduce its fee. Omit to calculate the fee at creation. Treat this value as sensitive and do not inspect or modify it.", "type": "string", "minLength": 1, "maxLength": 2000 } } }, "Funding_WithdrawalDestination": { "description": "Destination selected for the withdrawal.", "oneOf": [ { "$ref": "#/components/schemas/Funding_FundingAddressWithdrawalDestination" }, { "$ref": "#/components/schemas/Funding_AccountLinkWithdrawalDestination" } ], "discriminator": { "propertyName": "type", "mapping": { "funding_address": "#/components/schemas/Funding_FundingAddressWithdrawalDestination", "account_link": "#/components/schemas/Funding_AccountLinkWithdrawalDestination" } } }, "Funding_FundingAddressWithdrawalDestination": { "title": "Funding address", "description": "A registered fiat or cryptocurrency funding address owned by the selected account.", "type": "object", "additionalProperties": false, "required": [ "type", "address_id" ], "properties": { "type": { "description": "Destination kind.", "type": "string", "enum": [ "funding_address" ] }, "address_id": { "description": "Identifier returned when registering the funding address.", "type": "string", "minLength": 20, "maxLength": 20, "pattern": "^AB[A-Za-z0-9]{5}-[A-Za-z0-9]{5}-[A-Za-z0-9]{6}$" } } }, "Funding_AccountLinkWithdrawalDestination": { "title": "Account link", "description": "A linked bank account owned by the selected account and eligible for the selected withdrawal method.", "type": "object", "additionalProperties": false, "required": [ "type", "account_link_id" ], "properties": { "type": { "description": "Destination kind.", "type": "string", "enum": [ "account_link" ] }, "account_link_id": { "description": "Identifier returned by the Bank Link API for the linked bank account. Use with a withdrawal method whose `requirements` include `bank_link`; a method that cannot pay out to a linked bank account is rejected with a `bad_request` error on `scope.method_id`. An expired parent connection is allowed; revoked or deleted connections and removed accounts are rejected. Eligibility is checked on every retry.", "type": "string", "pattern": "^al_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } }, "Funding_CreateWithdrawalResult": { "description": "Withdrawal created for the selected account.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Created withdrawal.", "$ref": "#/components/schemas/Funding_Withdrawal" } } }, "Funding_Withdrawal": { "description": "Created withdrawal, including its account-transaction correlation identifier and execution-time amounts.", "type": "object", "required": [ "withdrawal_id", "net_amount", "gross_amount", "fee" ], "properties": { "withdrawal_id": { "description": "Opaque withdrawal identifier used as `reference.id` with `reference.kind=funding` for the corresponding account transaction.", "type": "string", "minLength": 1, "maxLength": 64 }, "net_amount": { "description": "Amount sent after fees.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "gross_amount": { "description": "Total amount deducted, including fees. Equals the submitted `amount` for same-asset fees.", "$ref": "#/components/schemas/Funding_FundingAmount" }, "fee": { "description": "Fee charged for the withdrawal. A valid `fee_token` applies its quoted terms to the submitted amount. Otherwise, the current fee terms apply.", "$ref": "#/components/schemas/Funding_FundingAmount" } } }, "Funding_FundingAddress": { "description": "User-added funding address registered for the selected account.", "type": "object", "required": [ "address_id" ], "properties": { "address_id": { "description": "Stable identifier for the registered funding address.", "type": "string", "minLength": 1, "maxLength": 64 } } }, "Funding_GetFundingAddressResult": { "description": "User-added funding address retrieved for the selected account.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Registered funding address.", "$ref": "#/components/schemas/Funding_RegisteredFundingAddress" } } }, "Funding_RegisteredFundingAddress": { "description": "User-added funding address registered for the selected account.", "type": "object", "required": [ "address_id", "scope", "address_details" ], "properties": { "address_id": { "description": "Stable identifier for the registered funding address.", "type": "string", "minLength": 20, "maxLength": 20, "pattern": "^AB[A-Za-z0-9]{5}-[A-Za-z0-9]{5}-[A-Za-z0-9]{6}$" }, "scope": { "description": "Scope under which the address was registered. Exactly one identifier is present. Network and network-group scopes can make the address usable with multiple withdrawal methods.", "$ref": "#/components/schemas/Funding_FundingAddressScope" }, "name": { "description": "Partner-provided label for the address, when present.", "type": "string", "minLength": 1, "maxLength": 64 }, "address_details": { "description": "Destination details for the registered fiat bank account or crypto address. Exactly one of `fiat` or `crypto` is present.", "$ref": "#/components/schemas/Funding_FundingAddressDetails" } } }, "Funding_ListFundingAddressesResult": { "description": "A page of user-added withdrawal addresses for the selected account. A page token is valid only with the same account and filter and preserves the original page size.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "User-added withdrawal addresses returned on this page.", "type": "array", "items": { "$ref": "#/components/schemas/Funding_RegisteredFundingAddress" } }, "next_page_token": { "description": "Opaque token for retrieving the next page. Absent when there are no more results.", "type": "string", "minLength": 1, "maxLength": 256 } } }, "Funding_IdempotencyConflictError": { "description": "The validated request reuses an `Idempotency-Key` recorded for different transfer parameters.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "idempotency_conflict" ] } } } ] } } } ] }, "Funding_StaleConversionRateError": { "description": "The transfer was not created because its conversion rate became stale. Submit a new request to use a current rate.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "stale_conversion_rate" ] } } } ] } } } ] }, "Funding_DepositAddressLimitReachedError": { "description": "Deposit address cannot be claimed because the funding method has reached its address limit.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "deposit_address_limit_reached" ] } } } ] } } } ] }, "Funding_WithdrawalAddressLimitReachedError": { "description": "A new funding address cannot be registered because an address limit applying to the selected scope has been reached. Compatible funding methods can share address limits. List and reuse an existing address before registering another.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "withdrawal_address_limit_reached" ] } } } ] } } } ] }, "Funding_FundingMethodActivationRequiredError": { "description": "The funding method requires activation before this operation can complete. This API does not expose a separate withdrawal-method activation operation.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "funding_method_activation_required" ] } } } ] } } } ] }, "Funding_FundingMethodActivationDeniedError": { "description": "Activation of the funding method was denied, so this operation could not complete.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "funding_method_activation_denied" ] } } } ] } } } ] }, "Funding_WithdrawalAddressAlreadyExistsError": { "description": "The funding address cannot be created or renamed because another address with the same name already exists for the account owner.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "withdrawal_address_already_exists" ] } } } ] } } } ] }, "Funding_WithdrawalAddressAccountSettingsLockedError": { "description": "A new funding address cannot be registered because account settings temporarily block security-sensitive changes.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "withdrawal_address_account_settings_locked" ] } } } ] } } } ] }, "Funding_WithdrawalAccountSettingsLockedError": { "description": "Withdrawal cannot be created because account settings temporarily block security-sensitive changes.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "withdrawal_account_settings_locked" ] } } } ] } } } ] }, "Funding_WithdrawalVerificationRequiredError": { "description": "The saved crypto address requires address-ownership verification before it can receive the withdrawal.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error", "verification_methods" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "withdrawal_verification_required" ] } } } ] }, "verification_methods": { "description": "Verification methods that can satisfy the address-ownership requirement. Complete a supported method through the Travel Rule verification API before retrying. Contact Payward Services support if none are supported.", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "description": "Address-ownership verification method that can unblock the withdrawal.", "type": "string", "enum": [ "self_attestation", "satoshi_test", "digital_signature" ] } } } } ] }, "Portfolio_AssetType": { "description": "Asset classification for portfolio resources.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin", "equity" ] }, "Portfolio_QuoteAssetType": { "description": "Quote asset classification. Supports fiat and stablecoin.", "type": "string", "enum": [ "fiat", "stablecoin" ], "default": "fiat" }, "Portfolio_SortDirection": { "description": "Sort order for transaction results by timestamp.", "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "Portfolio_TransactionType": { "description": "Category of portfolio transaction. `swap` and `price_trigger_swap` represent both successful executions and failed execution attempts; use `status` to distinguish them. `deposit` and `withdrawal` represent incoming and outgoing funding transactions, respectively. `transfer` represents both transfers between accounts and movements between an account's spot and futures balances.", "type": "string", "enum": [ "swap", "price_trigger_swap", "earn_reward", "deposit", "withdrawal", "transfer", "recurring_swap" ] }, "Portfolio_TransactionStatus": { "description": "Current processing status of a transaction. `in_progress` means the transaction is visible but not yet in a terminal state. `successful` and `failed` are terminal statuses.", "type": "string", "enum": [ "in_progress", "successful", "failed" ] }, "Portfolio_TransactionStatusFilter": { "description": "Lifecycle statuses available to filter transactions.", "type": "string", "enum": [ "in_progress", "successful", "failed" ] }, "Portfolio_TransactionReferenceKind": { "description": "Namespace of the originating system that issued the reference. Use the kind returned with a transaction when filtering by reference.", "type": "string", "enum": [ "funding", "transfer" ] }, "Portfolio_Portfolio": { "description": "A unified account portfolio snapshot.", "type": "object", "properties": { "as_of": { "description": "Time of the latest index-price update represented by this snapshot.", "$ref": "#/components/schemas/DateTime" }, "quote": { "$ref": "#/components/schemas/Portfolio_PortfolioQuote" }, "total_in_quote": { "description": "Total account value across all holdings in the quote currency.", "type": "string" }, "availability": { "$ref": "#/components/schemas/Portfolio_PortfolioAvailability" }, "pnl": { "$ref": "#/components/schemas/Portfolio_PortfolioPnl" }, "assets": { "description": "Per-asset portfolio breakdown. Always present and empty when there are no assets.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_PortfolioAsset" } } }, "required": [ "as_of", "quote", "total_in_quote", "availability", "assets" ] }, "Portfolio_PortfolioQuote": { "description": "Currency used for monetary values throughout the portfolio snapshot.", "type": "object", "properties": { "symbol": { "description": "Public quote-asset symbol.", "type": "string", "example": "USD" }, "type": { "$ref": "#/components/schemas/Portfolio_QuoteAssetType" }, "usd_index_rate": { "description": "USD value of one unit of this quote asset. Omitted when unavailable.", "type": "string", "example": "1.14" } }, "required": [ "symbol", "type" ] }, "Portfolio_PortfolioAvailability": { "description": "Account-level availability and holds in the portfolio quote.", "type": "object", "properties": { "available_in_quote": { "description": "Funds available for trading or withdrawal after holds.", "type": "string" }, "withheld": { "$ref": "#/components/schemas/Portfolio_PortfolioWithheld" } }, "required": [ "available_in_quote", "withheld" ] }, "Portfolio_PortfolioWithheld": { "description": "Funds unavailable because of orders, earn allocation, or other temporary holds.", "type": "object", "properties": { "total_in_quote": { "description": "Total withheld value.", "type": "string" }, "open_orders_in_quote": { "description": "Total value held for open orders.", "type": "string" }, "earn_in_quote": { "description": "Value withheld for earn products.", "type": "string" }, "other_in_quote": { "description": "Other temporary holds such as card holds, paylinks, or pending movements.", "type": "string" } }, "required": [ "total_in_quote", "open_orders_in_quote", "earn_in_quote", "other_in_quote" ] }, "Portfolio_PortfolioPnl": { "description": "Account-level average-cost-basis PnL in the portfolio quote.", "type": "object", "properties": { "reference_currency": { "$ref": "#/components/schemas/Portfolio_PnlReferenceCurrency" }, "unrealized_in_quote": { "description": "Lots-based unrealized PnL.", "type": "string" }, "realized_in_quote": { "description": "Realized PnL.", "type": "string" }, "cost_basis_in_quote": { "description": "Total cost basis.", "type": "string" }, "status": { "$ref": "#/components/schemas/Portfolio_PnlProcessingStatus" } } }, "Portfolio_PortfolioAsset": { "description": "Portfolio data for one asset.", "type": "object", "properties": { "symbol": { "description": "Public asset symbol.", "type": "string" }, "type": { "$ref": "#/components/schemas/Portfolio_AssetType" }, "index_price_in_quote": { "description": "Price of one unit of the asset in the top-level portfolio quote.", "$ref": "#/components/schemas/Price" }, "balances": { "$ref": "#/components/schemas/Portfolio_PortfolioBalances" }, "held_for_orders": { "$ref": "#/components/schemas/Portfolio_PortfolioHeldForOrders" }, "earn": { "$ref": "#/components/schemas/Portfolio_PortfolioEarn" }, "availability": { "$ref": "#/components/schemas/Portfolio_PortfolioAssetAvailability" }, "credit_line": { "$ref": "#/components/schemas/Portfolio_PortfolioCreditLine" }, "pnl": { "$ref": "#/components/schemas/Portfolio_PortfolioAssetPnl" } }, "required": [ "symbol", "type", "balances" ] }, "Portfolio_PortfolioAmount": { "description": "An amount in the asset's native display units.", "type": "object", "properties": { "amount": { "description": "Balance in the asset's native display units.", "type": "string" } }, "required": [ "amount" ] }, "Portfolio_PortfolioBalances": { "description": "Asset balance and its value in the top-level portfolio quote, with optional breakdowns by account balance source. `main` includes balances used by spot trading and balances received from swaps; it is not a transaction-origin classification. `total` is the native-asset sum of all balance sources, and `total_in_quote` is the quoted value of that same total.", "type": "object", "properties": { "total": { "description": "Total balance across all sources in the asset's native display units.", "type": "string" }, "total_in_quote": { "description": "Value of the total balance in the top-level portfolio quote.", "type": "string" }, "main": { "$ref": "#/components/schemas/Portfolio_PortfolioBalance" }, "custody_pledged_collateral": { "$ref": "#/components/schemas/Portfolio_PortfolioBalance" }, "custody_otc_trading": { "$ref": "#/components/schemas/Portfolio_PortfolioBalance" }, "dual_currency_investment": { "$ref": "#/components/schemas/Portfolio_PortfolioBalance" }, "custody_staking": { "$ref": "#/components/schemas/Portfolio_PortfolioBalance" }, "kraken_launch": { "$ref": "#/components/schemas/Portfolio_PortfolioBalance" } }, "required": [ "total" ] }, "Portfolio_PortfolioBalance": { "description": "Balance held in one account balance source.", "type": "object", "properties": { "total": { "description": "Balance in the asset's native display units.", "type": "string" }, "total_in_quote": { "description": "Value of the balance in the top-level portfolio quote.", "type": "string" } }, "required": [ "total" ] }, "Portfolio_PortfolioHeldForOrders": { "description": "Native asset amounts held for open orders.", "type": "object", "properties": { "main": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "equities": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" } } }, "Portfolio_PortfolioEarn": { "description": "Earn balances grouped by strategy liquidity.", "type": "object", "properties": { "locked": { "$ref": "#/components/schemas/Portfolio_PortfolioEarnBalance" }, "flex": { "$ref": "#/components/schemas/Portfolio_PortfolioEarnBalance" }, "hybrid": { "$ref": "#/components/schemas/Portfolio_PortfolioEarnBalance" } } }, "Portfolio_PortfolioEarnBalance": { "description": "Two views of the same earn total: lifecycle state and yield source. Do not add the lifecycle and yield-source breakdowns together.", "type": "object", "properties": { "total": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "earning": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "bonding": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "unbonding": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "exit_queue": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "by_yield_source": { "$ref": "#/components/schemas/Portfolio_PortfolioEarnYieldSources" } } }, "Portfolio_PortfolioEarnYieldSources": { "description": "Earn total decomposed by yield source.", "type": "object", "properties": { "staking": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "opt_in_rewards": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "base_rewards": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" } } }, "Portfolio_PortfolioAssetAvailability": { "description": "Asset amounts available for specific actions.", "type": "object", "properties": { "trade": { "description": "Amount available for trading, in the asset's native display units.", "type": "string" }, "transfer": { "description": "Amount available for internal transfer, in the asset's native display units.", "type": "string" } } }, "Portfolio_PortfolioCreditLine": { "description": "Credit usage and total limit. Remaining credit is limit minus used.", "type": "object", "properties": { "used": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" }, "limit": { "$ref": "#/components/schemas/Portfolio_PortfolioAmount" } } }, "Portfolio_PortfolioAssetPnl": { "description": "Per-asset average-cost-basis PnL in the top-level portfolio quote.", "type": "object", "properties": { "reference_currency": { "$ref": "#/components/schemas/Portfolio_PnlReferenceCurrency" }, "unrealized_in_quote": { "description": "Lots-based unrealized PnL.", "type": "string" }, "realized_in_quote": { "description": "Realized PnL.", "type": "string" }, "cost_basis_in_quote": { "description": "Total value spent to acquire the current balance.", "type": "string" }, "avg_entry_price_in_quote": { "description": "Volume-weighted average acquisition price.", "$ref": "#/components/schemas/Price" }, "status": { "$ref": "#/components/schemas/Portfolio_PnlProcessingStatus" } } }, "Portfolio_PnlReferenceCurrency": { "description": "Currency Portfolio uses as the PnL calculation basis.", "type": "object", "properties": { "symbol": { "description": "Public symbol of the PnL reference currency.", "type": "string" }, "type": { "$ref": "#/components/schemas/Portfolio_AssetType" } }, "required": [ "symbol", "type" ] }, "Portfolio_PnlProcessingStatus": { "description": "Readiness of average-cost-basis calculations.", "type": "object", "properties": { "avg_entry_price": { "$ref": "#/components/schemas/Portfolio_PnlProcessingState" }, "cost_basis": { "$ref": "#/components/schemas/Portfolio_PnlProcessingState" }, "unrealized": { "$ref": "#/components/schemas/Portfolio_PnlProcessingState" }, "realized": { "$ref": "#/components/schemas/Portfolio_PnlProcessingState" } } }, "Portfolio_PnlProcessingState": { "description": "Processing state for a PnL calculation. `ready` means the value is complete. `in_progress` means calculation is still running, and the corresponding value may be absent or not final.", "type": "string", "enum": [ "ready", "in_progress" ] }, "Portfolio_AssetFilter": { "description": "Asset filter element. Pairs a symbol with its type so callers can disambiguate symbols that exist across categories (e.g., spot vs tokenized vs equity).", "type": "object", "properties": { "symbol": { "description": "Asset symbol (e.g., `XBT`, `TSLAx`, `AAPL`).", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "$ref": "#/components/schemas/Portfolio_AssetType" } }, "required": [ "symbol", "type" ] }, "Portfolio_PortfolioHistoryDataPoint": { "description": "A single daily snapshot of the portfolio.", "type": "object", "properties": { "timestamp": { "description": "Time represented by this daily portfolio snapshot.", "$ref": "#/components/schemas/DateTime" }, "assets": { "description": "Per-asset balances held at this snapshot. Always present; serialized as an empty array when no assets had a balance at this snapshot.", "type": "array", "items": { "$ref": "#/components/schemas/Portfolio_PortfolioHistoryAsset" } }, "value": { "description": "Total portfolio value at this snapshot, in the quote asset. Omitted when a value is unavailable for this date.", "type": "string" }, "total_pnl": { "description": "Total account PnL at this snapshot, in the quote asset.", "type": "string" } }, "required": [ "timestamp", "assets" ] }, "Portfolio_PortfolioHistoryAsset": { "description": "A single asset's balance within a portfolio history data point.", "type": "object", "properties": { "symbol": { "description": "Asset symbol (e.g., `XBT`, `USDT`, `USD`).", "type": "string" }, "type": { "$ref": "#/components/schemas/Portfolio_AssetType" }, "amount": { "description": "Asset balance, in the asset's native units.", "type": "string" } }, "required": [ "symbol", "amount", "type" ] }, "Portfolio_Transaction": { "description": "A single portfolio transaction entry.", "type": "object", "properties": { "id": { "description": "Unique Portfolio transaction identifier in the `TX` namespace. Distinct from the identifier in `reference`.", "type": "string" }, "timestamp": { "description": "Time at which the portfolio transaction was recorded.", "$ref": "#/components/schemas/DateTime" }, "type": { "$ref": "#/components/schemas/Portfolio_TransactionType" }, "status": { "$ref": "#/components/schemas/Portfolio_TransactionStatus" }, "spend": { "$ref": "#/components/schemas/Portfolio_TransactionSide" }, "receive": { "$ref": "#/components/schemas/Portfolio_TransactionSide" }, "reference": { "description": "Identifier assigned by the system from which this transaction originated. Omitted when no public originating reference is available. For a deposit or withdrawal, `kind` is `funding` and `id` is the originating funding identifier. For a transfer, `kind` is `transfer` and `id` is the `transfer_id` returned by `POST /v1/transfers` or an accepted `POST /v1/accounts/{account_id}/transfers/derivatives` request. This identifier is distinct from the Portfolio transaction `id` in the `TX` namespace.", "$ref": "#/components/schemas/Portfolio_TransactionReference" }, "details": { "description": "Type-specific detail for this transaction, tagged by `details.type`. Present only for transaction types with extra detail to report; omitted otherwise. New `type` values may be added over time; treat an unrecognized `details.type` as absent rather than as an error.", "$ref": "#/components/schemas/Portfolio_TransactionDetails" } }, "required": [ "id", "timestamp", "type", "status" ] }, "Portfolio_TransactionDetails": { "description": "Type-specific transaction detail, internally tagged by `type`. Each tag admits only the fields defined for it, so a detail belonging to one transaction type can never carry another type's fields.", "oneOf": [ { "title": "Funding transaction", "$ref": "#/components/schemas/Portfolio_FundingTransactionDetails" }, { "title": "Swap transaction", "$ref": "#/components/schemas/Portfolio_SwapTransactionDetails" }, { "title": "Price-triggered swap transaction", "$ref": "#/components/schemas/Portfolio_PriceTriggerSwapTransactionDetails" }, { "title": "Failed swap transaction", "$ref": "#/components/schemas/Portfolio_FailedSwapTransactionDetails" }, { "title": "Failed price-triggered swap transaction", "$ref": "#/components/schemas/Portfolio_FailedPriceTriggerSwapTransactionDetails" }, { "title": "Recurring swap transaction", "$ref": "#/components/schemas/Portfolio_RecurringSwapTransactionDetails" }, { "title": "Failed recurring swap transaction", "$ref": "#/components/schemas/Portfolio_FailedRecurringSwapTransactionDetails" } ], "discriminator": { "propertyName": "type", "mapping": { "funding": "#/components/schemas/Portfolio_FundingTransactionDetails", "swap": "#/components/schemas/Portfolio_SwapTransactionDetails", "recurring_swap": "#/components/schemas/Portfolio_RecurringSwapTransactionDetails", "price_trigger_swap": "#/components/schemas/Portfolio_PriceTriggerSwapTransactionDetails", "failed_swap": "#/components/schemas/Portfolio_FailedSwapTransactionDetails", "failed_recurring_swap": "#/components/schemas/Portfolio_FailedRecurringSwapTransactionDetails", "failed_price_trigger_swap": "#/components/schemas/Portfolio_FailedPriceTriggerSwapTransactionDetails" } } }, "Portfolio_FundingTransactionDetails": { "description": "Detail for `deposit` and `withdrawal` transactions, which settle through funding.", "type": "object", "properties": { "type": { "description": "Discriminator identifying this as funding detail.", "type": "string", "enum": [ "funding" ] }, "crypto_transaction_id": { "description": "On-chain transaction id or hash for this funding movement, when available. For withdrawals, the hash can remain absent after broadcast or block inclusion until completion is reported. Omitted for fiat funding. Treat this value as opaque; its format varies by network.", "type": "string" }, "vout": { "description": "Output index identifying the credited output within an on-chain transaction.", "type": "integer", "format": "int64", "minimum": 0 }, "vendor_transaction_id": { "description": "Provider-assigned reference used to correlate the funding transaction. For Lightning deposits, this is the payment hash. Treat this value as opaque.", "type": "string", "minLength": 1 } }, "required": [ "type" ] }, "Portfolio_SwapTransactionDetails": { "description": "Detail for a successful `swap` transaction.", "type": "object", "properties": { "type": { "description": "Discriminator identifying this as standard swap detail.", "type": "string", "enum": [ "swap" ] }, "quote_id": { "description": "Identifier of the quote that executed this swap.", "type": "string" } }, "required": [ "type", "quote_id" ] }, "Portfolio_FailedSwapTransactionDetails": { "description": "Detail for a failed `swap` transaction.", "type": "object", "properties": { "type": { "description": "Discriminator identifying this as failed standard swap detail.", "type": "string", "enum": [ "failed_swap" ] }, "failure_reason": { "description": "Reason the swap failed.", "$ref": "#/components/schemas/Portfolio_SwapFailureReason" } }, "required": [ "type", "failure_reason" ] }, "Portfolio_RecurringSwapTransactionDetails": { "description": "Detail for a successful `recurring_swap` execution.", "type": "object", "properties": { "type": { "description": "Discriminator identifying this as recurring swap detail.", "type": "string", "enum": [ "recurring_swap" ] }, "quote_id": { "description": "Identifier of the quote that executed this recurring swap.", "type": "string" } }, "required": [ "type", "quote_id" ] }, "Portfolio_FailedRecurringSwapTransactionDetails": { "description": "Detail for a failed `recurring_swap` execution.", "type": "object", "properties": { "type": { "description": "Discriminator identifying this as failed recurring swap detail.", "type": "string", "enum": [ "failed_recurring_swap" ] }, "failure_reason": { "description": "Reason the recurring swap execution failed.", "$ref": "#/components/schemas/Portfolio_SwapFailureReason" } }, "required": [ "type", "failure_reason" ] }, "Portfolio_PriceTriggerSwapTransactionDetails": { "description": "Detail for a successful `price_trigger_swap` transaction.", "type": "object", "properties": { "type": { "description": "Discriminator identifying this as price-triggered swap detail.", "type": "string", "enum": [ "price_trigger_swap" ] }, "quote_id": { "description": "Identifier of the quote that executed this swap.", "type": "string" } }, "required": [ "type", "quote_id" ] }, "Portfolio_FailedPriceTriggerSwapTransactionDetails": { "description": "Detail for a failed `price_trigger_swap` transaction.", "type": "object", "properties": { "type": { "description": "Discriminator identifying this as failed price-triggered swap detail.", "type": "string", "enum": [ "failed_price_trigger_swap" ] }, "failure_reason": { "description": "Reason the swap failed.", "$ref": "#/components/schemas/Portfolio_SwapFailureReason" } }, "required": [ "type", "failure_reason" ] }, "Portfolio_SwapFailureReason": { "description": "Public category for why a swap transaction failed.", "type": "string", "enum": [ "insufficient_funds", "card_issue", "user_account_issue", "other" ] }, "Portfolio_TransactionReference": { "description": "An identifier assigned by the system from which a transaction originated. For deposits and withdrawals, `kind=funding` identifies the originating funding transaction. For a deposit, this is not a destination or a payment reference from bank-transfer instructions. For a transfer, use `kind=transfer` and the opaque `transfer_id` returned by `POST /v1/transfers` or an accepted `POST /v1/accounts/{account_id}/transfers/derivatives` request. Reference identifiers are distinct from Portfolio transaction identifiers in the `TX` namespace.", "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/Portfolio_TransactionReferenceKind" }, "id": { "description": "Identifier assigned by the originating system. Treat this value as opaque.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "kind", "id" ] }, "Portfolio_TransactionSide": { "description": "Details about one side of a transaction, either spend or receive. Values in sub_total, total, and fee are non-negative magnitudes; direction is indicated by the side on which they appear. Balance retains the signed account value.", "type": "object", "properties": { "sub_total": { "$ref": "#/components/schemas/Portfolio_TransactionAmount" }, "total": { "$ref": "#/components/schemas/Portfolio_TransactionAmount" }, "timestamp": { "description": "Time associated with this side of the transaction, when available.", "$ref": "#/components/schemas/DateTime" }, "fee": { "$ref": "#/components/schemas/Portfolio_TransactionAmount" }, "balance": { "$ref": "#/components/schemas/Portfolio_TransactionAmount" } }, "required": [ "sub_total", "total" ] }, "Portfolio_TransactionAmount": { "description": "Amount of an asset involved in a transaction.", "type": "object", "properties": { "symbol": { "description": "Asset symbol (e.g., \"BTC\", \"USD\", \"TSLAx\").", "type": "string" }, "amount": { "description": "Amount in the asset's native units.", "type": "string" }, "name": { "description": "Human-readable name of the asset (e.g., \"Bitcoin\").", "type": "string" }, "type": { "$ref": "#/components/schemas/Portfolio_AssetType" }, "amount_in_quote": { "description": "Amount expressed in the response `quote_symbol`. Absent when no rate is available at transaction time.", "type": "string" } }, "required": [ "symbol", "amount", "type" ] }, "Ramp_BankLink": { "description": "A provider-neutral linking operation and persistent bank connection.", "type": "object", "properties": { "bank_link_id": { "description": "Opaque public bank-link id.", "type": "string" }, "method_id": { "description": "Funding method this Bank Link was created for.", "type": "string" }, "status": { "description": "Current lifecycle state of the Bank Link.", "type": "string", "enum": [ "pending", "activating", "linked", "expired", "unlinked" ], "title": "BankLinkStatus" }, "next_action": { "description": "How the partner completes the link while it is `pending`.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "hosted_link" ], "title": "NextActionType" }, "widget_url": { "description": "Kraken-hosted widget URL. Not a Plaid URL and carries no Plaid Link token.", "type": "string" }, "expires_at": { "description": "Time at which the hosted-link action expires.", "$ref": "#/components/schemas/DateTime" } }, "title": "NextAction", "required": [ "type", "widget_url" ] }, "institution": { "description": "Display-safe institution details. Provider account and item references are never exposed.", "type": "object", "properties": { "name": { "description": "Institution display name.", "type": "string", "minLength": 1, "maxLength": 256 } }, "title": "Institution", "required": [ "name" ] }, "account_links": { "description": "Account Links owned by this Bank Link.", "type": "array", "items": { "description": "A provider-neutral account linked under one Bank Link.", "type": "object", "properties": { "account_link_id": { "description": "Opaque public account-link id.", "type": "string" }, "account_last4": { "description": "The account's last four digits, safe to display.", "type": "string" }, "status": { "type": "string", "enum": [ "active", "removed" ], "title": "AccountLinkStatus" }, "eligible_rails": { "description": "Rails this account can currently use. Values are provider-neutral method identifiers such as `ach`, `rtp`, or `rfp`.", "type": "array", "items": { "type": "string" } }, "ineligibility_reasons": { "description": "Safe reasons why no rail is eligible. Empty when at least one rail is eligible or eligibility has not yet been evaluated.", "type": "array", "items": { "type": "string" } }, "eligibility_status": { "description": "Whether this account can move money, from its own ownership validation and rail capability. Always present, and consistent with this account's `eligible_rails` and `ineligibility_reasons`.", "$ref": "#/components/schemas/Ramp_AccountEligibilityStatus" }, "rail_limits": { "description": "Published limits for individual rails on this account.", "$ref": "#/components/schemas/Ramp_RailLimits" } }, "title": "AccountLink", "required": [ "account_link_id", "account_last4", "status", "eligibility_status" ] } }, "accounts_eligibility_status": { "description": "Whether any Account Link under this Bank Link can move money: the fold of the accounts' own `eligibility_status`. Always present. `eligible` means at least one account is eligible. `ineligible` means every account is conclusively ruled out, as a link that finished linking without a single account vacuously is. `unknown` means no account is confirmed eligible while at least one is still inconclusive, because its ownership or its rails were not evaluated. A `pending` link has no accounts to evaluate yet, so it reports `unknown` rather than the denial `ineligible` would be.", "type": "string", "enum": [ "eligible", "ineligible", "unknown" ], "title": "AccountsEligibilityStatus" }, "not_linked_accounts": { "description": "Accounts the user selected at the provider that could not be linked under this Bank Link. They hold no `account_link_id`, are excluded from `account_links` and from `accounts_eligibility_status`, and can never move money. Surfaced so a partner can tell the user that an account they picked was left out. Absent or empty when every selected account linked.", "type": "array", "items": { "description": "An account selected at the provider that could not be linked.", "type": "object", "properties": { "account_last4": { "description": "The account's last four digits, safe to display. May be empty when the provider reported none.", "type": "string" }, "reason": { "description": "Safe reason the account could not be linked. Known values are `missing_identity` means the provider could not verify the account holder's identity for this account. `missing_balance` means the provider could not read the account's balance; `unknown` is also possible. New reasons may be introduced over time; treat any unrecognized value as `unknown`.", "type": "string" } }, "title": "NotLinkedAccount", "required": [ "account_last4", "reason" ] } }, "linked_at": { "description": "When the connection became active. Absent until the link finishes linking.", "$ref": "#/components/schemas/DateTime" }, "expires_at": { "description": "When the connection is due to expire, if the provider has reported an expiry.", "$ref": "#/components/schemas/DateTime" } }, "title": "BankLink", "required": [ "bank_link_id", "method_id", "status", "accounts_eligibility_status" ] }, "Ramp_BankLinkActivationRestartRequiredError": { "description": "The Bank Link must be created again before activation can continue.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "bank_link_activation_restart_required" ] } } } ] } } } ] }, "Ramp_BankLinkProviderRejectedError": { "description": "The provider rejected the requested operation on this bank connection. Not retryable until the underlying condition changes.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "bank_link_provider_rejected" ] } } } ] } } } ] }, "Ramp_BankLinkMethodNotLinkableError": { "description": "The funding method does not support bank linking. Not retryable.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "bank_link_method_not_linkable" ] } } } ] } } } ] }, "Ramp_BankLinkNotFoundError": { "description": "BankLinkNotFound error.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "bank_link_not_found" ] } } } ] } } } ] }, "Ramp_AccountEligibilityStatus": { "description": "Whether one Account Link can move money, from the two checks it is subject to. `eligible` means its owner is validated and at least one rail is known. `ineligible` means a check ruled it out, or the account is no longer linked. `unknown` means a check could not answer or has not run.", "type": "string", "enum": [ "eligible", "ineligible", "unknown" ] }, "Ramp_RailLimit": { "description": "A provider-published limit for one transfer rail.", "type": "object", "properties": { "max_daily_amount": { "description": "Provider-published total daily ceiling in USD. This is not the account's remaining daily headroom and does not guarantee that a transfer up to this amount will be accepted.", "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "minLength": 1, "maxLength": 64 } }, "required": [ "max_daily_amount" ] }, "Ramp_RailLimits": { "description": "Published limits keyed by their provider-neutral rail identifier.", "type": "object", "properties": { "rfp": { "description": "Request for Payment limit. Absent when no valid published ceiling is available.", "$ref": "#/components/schemas/Ramp_RailLimit" } } }, "Ramp_LimitAssetType": { "description": "Asset classification used by Ramp limit amounts.", "type": "string", "enum": [ "fiat", "crypto", "stablecoin" ], "default": "fiat" }, "Ramp_SourceAssetType": { "description": "Source asset classification accepted by Ramp on-ramp flows.", "type": "string", "enum": [ "fiat" ], "default": "fiat" }, "Ramp_DestinationAssetType": { "description": "Destination asset classification accepted by Ramp on-ramp flows.", "type": "string", "enum": [ "crypto", "stablecoin" ], "default": "crypto" }, "Ramp_AssetRef": { "description": "The asset for this breakdown (e.g., USD on the from side, BTC on the to side).", "type": "object", "properties": { "symbol": { "description": "Asset ticker symbol (e.g., \"BTC\", \"USD\", \"TSLAx\").", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the asset.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ], "title": "AssetType" }, "name": { "description": "Human-readable English name of the asset (e.g., \"Bitcoin\", \"Tether\").", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "symbol", "type", "name" ] }, "Reports_SettlementReportType": { "description": "The category of a settlement report.", "type": "string", "enum": [ "swaps", "price_trigger_swaps", "earn_rewards" ] }, "Reports_SettlementReport": { "description": "Settlement report metadata.", "type": "object", "properties": { "id": { "description": "A unique identifier assigned to each settlement report.", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "format": "uuid" }, "date": { "description": "The date covered by the report, spanning from 00:00:00 UTC to 23:59:59 UTC.", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date" }, "type": { "$ref": "#/components/schemas/Reports_SettlementReportType" }, "size": { "description": "The file size of the report, in bytes.", "type": "string", "pattern": "^[0-9]+$" }, "name": { "description": "A descriptive, human-readable name for the report.", "type": "string" } }, "required": [ "date", "id", "name", "size", "type" ] }, "Reports_SettlementReportDownload": { "description": "The settlement report details and secure download URL.", "type": "object", "properties": { "id": { "description": "A unique identifier assigned to each settlement report.", "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "format": "uuid" }, "date": { "description": "The date covered by the report, spanning from 00:00:00 UTC to 23:59:59 UTC.", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date" }, "type": { "$ref": "#/components/schemas/Reports_SettlementReportType" }, "size": { "description": "The file size of the report, in bytes.", "type": "string", "pattern": "^[0-9]+$" }, "name": { "description": "A descriptive, human-readable name for the report.", "type": "string" }, "download_url": { "description": "A secure URL to download the settlement report document. The URL is valid until the `expires_at` timestamp and can be used directly in HTTP requests or browser downloads without additional authentication headers.", "type": "string", "minLength": 1, "maxLength": 4096 }, "expires_at": { "description": "When the download URL expires. The URL becomes invalid after this timestamp. Clients should request a new URL if they need to download the report after this time.", "type": "string", "format": "date-time" } }, "required": [ "id", "date", "type", "size", "name", "download_url", "expires_at" ] }, "Reports_SettlementReportNotFoundError": { "description": "The requested settlement report does not exist or is not accessible.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "settlement_report_not_found" ] } } } ] } } } ] }, "OnchainQuotes_AssetType": { "description": "Asset classifications currently supported by Swap trading endpoints.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "PriceTriggerSwaps_AssetType": { "description": "Asset classifications currently supported by Swap trading endpoints.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "Swaps_AssetType": { "description": "Asset classifications currently supported by Swap trading endpoints.", "type": "string", "enum": [ "fiat", "crypto", "xstock", "stablecoin" ] }, "OnchainQuotes_AssetRef": { "description": "Reference to an asset by ticker symbol and classification.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset ticker symbol, such as BTC, USD, or TSLAx.", "type": "string" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/OnchainQuotes_AssetType" } } }, "PriceTriggerSwaps_AssetRef": { "description": "Reference to an asset by ticker symbol and classification.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset ticker symbol, such as BTC, USD, or TSLAx.", "type": "string" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetType" } } }, "Swaps_AssetRef": { "description": "Reference to an asset by ticker symbol and classification.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset ticker symbol, such as BTC, USD, or TSLAx.", "type": "string" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/Swaps_AssetType" } } }, "OnchainQuotes_QuoteStatus": { "description": "Current lifecycle status of a quote. `offered` quotes can be executed; `executed`, `expired`, and `failed` are final states.", "type": "string", "enum": [ "offered", "executing", "executed", "expired", "failed", "pending" ] }, "Swaps_QuoteStatus": { "description": "Current lifecycle status of a quote. `offered` quotes can be executed; `executed`, `expired`, and `failed` are final states.", "type": "string", "enum": [ "offered", "executing", "executed", "expired", "failed", "pending" ] }, "Swaps_QuoteLimitAmountSide": { "description": "Side whose asset denominates the requested quote limits.", "type": "string", "enum": [ "from", "to" ] }, "Swaps_QuoteLimitReason": { "description": "Constraint that contributed to the returned `maximum`. Reasons are ordered by binding priority; the first value is the primary constraint when multiple apply. `other` covers internal or uncommon constraints not otherwise listed.", "type": "string", "enum": [ "user_balance", "liquidity", "other" ] }, "OnchainQuotes_WalletNetwork": { "description": "Blockchain network used for wallet-funded onchain execution.", "type": "string", "enum": [ "ethereum" ] }, "PriceTriggerSwaps_PriceTriggerSwapStatus": { "description": "Current lifecycle status of a price-triggered swap. `active` waits for the trigger; `completed`, `cancelled`, and `failed` are final states.", "type": "string", "enum": [ "active", "completed", "cancelled", "failed" ] }, "PriceTriggerSwaps_PriceTriggerSwapFailureReason": { "description": "Reason a price-triggered swap failed.", "type": "string", "enum": [ "user_locked", "expired_payment_method", "asset_unavailable", "pair_unavailable", "retries_exhausted", "funding_method_deleted", "other" ] }, "OnchainQuotes_AssetAmount": { "description": "An asset and the decimal amount denominated in that asset.", "type": "object", "required": [ "symbol", "type", "amount" ], "properties": { "symbol": { "description": "Asset ticker symbol, such as BTC, USD, or TSLAx.", "type": "string" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/OnchainQuotes_AssetType" }, "amount": { "description": "Decimal amount as a string to preserve precision.", "type": "string" } } }, "PriceTriggerSwaps_AssetAmount": { "description": "An asset and the decimal amount denominated in that asset.", "type": "object", "required": [ "symbol", "type", "amount" ], "properties": { "symbol": { "description": "Asset ticker symbol, such as BTC, USD, or TSLAx.", "type": "string" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetType" }, "amount": { "description": "Decimal amount as a string to preserve precision.", "type": "string" } } }, "Swaps_AssetAmount": { "description": "An asset and the decimal amount denominated in that asset.", "type": "object", "required": [ "symbol", "type", "amount" ], "properties": { "symbol": { "description": "Asset ticker symbol, such as BTC, USD, or TSLAx.", "type": "string" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/Swaps_AssetType" }, "amount": { "description": "Decimal amount as a string to preserve precision.", "type": "string" } } }, "OnchainQuotes_Rate": { "description": "Exchange rate applied to a quote or executed price-triggered swap.", "type": "object", "required": [ "base", "quote", "price" ], "properties": { "base": { "description": "Base asset of the rate pair.", "$ref": "#/components/schemas/OnchainQuotes_AssetRef" }, "quote": { "description": "Quote asset of the rate pair.", "$ref": "#/components/schemas/OnchainQuotes_AssetRef" }, "price": { "description": "Price of one unit of the base asset denominated in the quote asset.", "$ref": "#/components/schemas/Price" } } }, "PriceTriggerSwaps_Rate": { "description": "Exchange rate applied to a quote or executed price-triggered swap.", "type": "object", "required": [ "base", "quote", "price" ], "properties": { "base": { "description": "Base asset of the rate pair.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetRef" }, "quote": { "description": "Quote asset of the rate pair.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetRef" }, "price": { "description": "Price of one unit of the base asset denominated in the quote asset.", "$ref": "#/components/schemas/Price" } } }, "Swaps_Rate": { "description": "Exchange rate applied to a quote or executed price-triggered swap.", "type": "object", "required": [ "base", "quote", "price" ], "properties": { "base": { "description": "Base asset of the rate pair.", "$ref": "#/components/schemas/Swaps_AssetRef" }, "quote": { "description": "Quote asset of the rate pair.", "$ref": "#/components/schemas/Swaps_AssetRef" }, "price": { "description": "Price of one unit of the base asset denominated in the quote asset.", "$ref": "#/components/schemas/Price" } } }, "OnchainQuotes_Fee": { "description": "A single fee charged against a quote or executed swap.", "type": "object", "required": [ "symbol", "type", "amount" ], "properties": { "symbol": { "description": "Asset ticker symbol the fee is denominated in.", "type": "string" }, "type": { "description": "Classification of the fee asset.", "$ref": "#/components/schemas/OnchainQuotes_AssetType" }, "amount": { "description": "Fee amount as a decimal string.", "type": "string" } } }, "PriceTriggerSwaps_Fee": { "description": "A single fee charged against a quote or executed swap.", "type": "object", "required": [ "symbol", "type", "amount" ], "properties": { "symbol": { "description": "Asset ticker symbol the fee is denominated in.", "type": "string" }, "type": { "description": "Classification of the fee asset.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetType" }, "amount": { "description": "Fee amount as a decimal string.", "type": "string" } } }, "Swaps_Fee": { "description": "A single fee charged against a quote or executed swap.", "type": "object", "required": [ "symbol", "type", "amount" ], "properties": { "symbol": { "description": "Asset ticker symbol the fee is denominated in.", "type": "string" }, "type": { "description": "Classification of the fee asset.", "$ref": "#/components/schemas/Swaps_AssetType" }, "amount": { "description": "Fee amount as a decimal string.", "type": "string" } } }, "OnchainQuotes_Fees": { "description": "Breakdown of all fees charged for a quote or executed swap.", "type": "object", "required": [ "trade" ], "properties": { "trade": { "description": "Trading fee charged for the quote or executed swap.", "$ref": "#/components/schemas/OnchainQuotes_Fee" } } }, "PriceTriggerSwaps_Fees": { "description": "Breakdown of all fees charged for a quote or executed swap.", "type": "object", "required": [ "trade" ], "properties": { "trade": { "description": "Trading fee charged for the quote or executed swap.", "$ref": "#/components/schemas/PriceTriggerSwaps_Fee" } } }, "Swaps_Fees": { "description": "Breakdown of all fees charged for a quote or executed swap.", "type": "object", "required": [ "trade" ], "properties": { "trade": { "description": "Trading fee charged for the quote or executed swap.", "$ref": "#/components/schemas/Swaps_Fee" } } }, "OnchainQuotes_QuoteWallet": { "description": "Wallet that funds an onchain quote.", "type": "object", "required": [ "address", "network" ], "properties": { "address": { "description": "Wallet address that will fund the onchain execution.", "type": "string", "minLength": 1, "maxLength": 64 }, "network": { "description": "Network on which the wallet address exists.", "$ref": "#/components/schemas/OnchainQuotes_WalletNetwork" } } }, "OnchainQuotes_ExecutionDetails": { "description": "Onchain execution payload for a quoted swap.", "type": "object", "required": [ "chain_id", "proxy_address", "proxy_swap_message" ], "properties": { "chain_id": { "description": "Chain identifier where the proxy swap can be executed.", "type": "string" }, "proxy_address": { "description": "Onchain proxy contract address used for execution.", "type": "string" }, "proxy_swap_message": { "description": "Signed proxy swap message required for execution.", "$ref": "#/components/schemas/OnchainQuotes_ProxySwapMessage" } } }, "OnchainQuotes_ProxySwapMessage": { "description": "Signed message bundle used to execute an onchain quote.", "type": "object", "required": [ "atomic_message", "atomic_signature", "signature", "client_address", "authorization_deadline" ], "properties": { "atomic_message": { "description": "Atomic transfer details covered by the signatures.", "$ref": "#/components/schemas/OnchainQuotes_AtomicMessage" }, "atomic_signature": { "description": "Signature for the atomic transfer message.", "type": "string" }, "signature": { "description": "Signature authorizing the proxy swap.", "type": "string" }, "client_address": { "description": "Client wallet address that signed the proxy swap message.", "type": "string" }, "authorization_deadline": { "description": "Unix timestamp after which the proxy authorization signature is no longer valid.", "type": "integer", "format": "int64", "minimum": 0 } } }, "OnchainQuotes_AtomicMessage": { "description": "Atomic transfer instructions for an onchain quote.", "type": "object", "required": [ "quote_id", "expiration", "incoming_transfer", "outgoing_transfer" ], "properties": { "quote_id": { "description": "Identifier of the quote being executed.", "type": "string" }, "expiration": { "description": "Unix timestamp after which the atomic message is no longer valid.", "type": "integer", "format": "int64", "minimum": 0 }, "incoming_transfer": { "description": "Transfer expected from the client.", "$ref": "#/components/schemas/OnchainQuotes_TokenTransfer" }, "outgoing_transfer": { "description": "Transfer sent to the client when execution succeeds.", "$ref": "#/components/schemas/OnchainQuotes_TokenTransfer" } } }, "OnchainQuotes_TokenTransfer": { "description": "Token transfer instruction inside an atomic onchain quote message.", "type": "object", "required": [ "from", "to", "token", "amount" ], "properties": { "from": { "description": "Sender address for the transfer.", "type": "string" }, "to": { "description": "Recipient address for the transfer.", "type": "string" }, "token": { "description": "Token contract address for the transfer.", "type": "string" }, "amount": { "description": "Token amount as a decimal string.", "type": "string" } } }, "Swaps_Quote": { "description": "A priced swap quote. Execute it before `expires_at`.", "type": "object", "required": [ "id", "status", "expires_at", "from", "to", "fees", "rate" ], "properties": { "id": { "description": "Unique identifier for this quote.", "type": "string" }, "status": { "description": "Current lifecycle status of the quote.", "$ref": "#/components/schemas/Swaps_QuoteStatus" }, "expires_at": { "description": "Time at which this quote expires if it has not been executed.", "$ref": "#/components/schemas/DateTime" }, "from": { "description": "Source asset and amount for the trade.", "$ref": "#/components/schemas/Swaps_AssetAmount" }, "to": { "description": "Destination asset and amount for the trade.", "$ref": "#/components/schemas/Swaps_AssetAmount" }, "fees": { "description": "Fees charged for the quote.", "$ref": "#/components/schemas/Swaps_Fees" }, "rate": { "description": "Exchange rate applied to the quote.", "$ref": "#/components/schemas/Swaps_Rate" } } }, "OnchainQuotes_OnchainQuote": { "description": "A wallet-funded onchain quote.", "type": "object", "required": [ "id", "status", "from", "to" ], "properties": { "id": { "description": "Unique identifier for this quote.", "type": "string" }, "status": { "description": "Current lifecycle status of the quote.", "$ref": "#/components/schemas/OnchainQuotes_QuoteStatus" }, "expires_at": { "description": "Time at which this quote expires if it has not been executed.", "$ref": "#/components/schemas/DateTime" }, "from": { "description": "Source asset and amount for the trade.", "$ref": "#/components/schemas/OnchainQuotes_AssetAmount" }, "to": { "description": "Destination asset and amount for the trade.", "$ref": "#/components/schemas/OnchainQuotes_AssetAmount" }, "fees": { "description": "Fees charged for the quote, when available.", "$ref": "#/components/schemas/OnchainQuotes_Fees" }, "rate": { "description": "Exchange rate applied to the quote, when available.", "$ref": "#/components/schemas/OnchainQuotes_Rate" }, "execution_details": { "description": "Execution details returned with a newly signed onchain quote.", "$ref": "#/components/schemas/OnchainQuotes_ExecutionDetails" } } }, "OnchainQuotes_SoftQuote": { "description": "A short-lived indicative price for a wallet-funded onchain swap. It carries no execution details and cannot be executed.", "type": "object", "required": [ "from", "to", "rate" ], "properties": { "from": { "description": "Source asset and amount for the trade.", "$ref": "#/components/schemas/OnchainQuotes_AssetAmount" }, "to": { "description": "Destination asset and amount for the trade.", "$ref": "#/components/schemas/OnchainQuotes_AssetAmount" }, "rate": { "description": "Indicative exchange rate for the soft quote.", "$ref": "#/components/schemas/OnchainQuotes_Rate" } } }, "Swaps_CreateQuoteFrom": { "description": "Source side of a quote request. Set `amount` here when the source amount is fixed.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Source asset ticker symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the source asset.", "$ref": "#/components/schemas/Swaps_AssetType" }, "amount": { "description": "Decimal asset amount as a string to preserve precision.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "Swaps_CreateQuoteTo": { "description": "Destination side of a quote request. Set `amount` here when the destination amount is fixed.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Destination asset ticker symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the destination asset.", "$ref": "#/components/schemas/Swaps_AssetType" }, "amount": { "description": "Decimal asset amount as a string to preserve precision.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "Swaps_QuoteLimits": { "description": "Effective point-in-time limits for the selected amount side.", "type": "object", "required": [ "asset", "minimum_swap", "maximum", "precision" ], "properties": { "asset": { "description": "Asset that denominates the returned amounts.", "$ref": "#/components/schemas/Swaps_AssetRef" }, "minimum_swap": { "description": "Smallest amount that can be submitted on create quote for a normal swap.", "type": "string", "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "maximum": { "description": "Largest amount currently available after applying liquidity and other trading constraints.", "type": "string", "maxLength": 64, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "precision": { "description": "Maximum number of decimal places supported for ordinary tradable amounts.", "type": "integer", "format": "int32", "minimum": 0 }, "limit_reasons": { "description": "Constraints that contributed to `maximum`, ordered by binding priority.", "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/Swaps_QuoteLimitReason" } } } }, "Swaps_QuoteFee": { "description": "Partner fee applied to a quote.", "type": "object", "properties": { "bps": { "description": "Fee in basis points, where 1 bps is 0.01%.", "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "default": 0 }, "absolute": { "description": "Absolute fee amount in quote currency.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "OnchainQuotes_CreateOnchainQuoteFrom": { "description": "Source side of a wallet-funded onchain quote request. Set `amount` here when the source amount is fixed.", "type": "object", "required": [ "symbol", "type", "wallet" ], "properties": { "symbol": { "description": "Source asset ticker symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the source asset.", "$ref": "#/components/schemas/OnchainQuotes_AssetType" }, "amount": { "description": "Decimal asset amount as a string to preserve precision.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "wallet": { "description": "Wallet that will fund the onchain execution.", "$ref": "#/components/schemas/OnchainQuotes_QuoteWallet" } } }, "OnchainQuotes_CreateOnchainQuoteTo": { "description": "Destination side of a wallet-funded onchain quote request. Set `amount` here when the destination amount is fixed.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Destination asset ticker symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the destination asset.", "$ref": "#/components/schemas/OnchainQuotes_AssetType" }, "amount": { "description": "Decimal asset amount as a string to preserve precision.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "OnchainQuotes_GetSoftQuoteFrom": { "description": "Source side of a soft quote request. Set `amount` here when the source amount is fixed.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Source asset ticker symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the source asset.", "$ref": "#/components/schemas/OnchainQuotes_AssetType" }, "amount": { "description": "Decimal asset amount as a string to preserve precision.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "OnchainQuotes_GetSoftQuoteTo": { "description": "Destination side of a soft quote request. Set `amount` here when the destination amount is fixed.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Destination asset ticker symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the destination asset.", "$ref": "#/components/schemas/OnchainQuotes_AssetType" }, "amount": { "description": "Decimal asset amount as a string to preserve precision.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "Swaps_QuoteExecution": { "description": "Result of executing a quote.", "type": "object", "required": [ "id", "status" ], "properties": { "id": { "description": "Unique identifier of the executed quote.", "type": "string" }, "status": { "description": "Lifecycle status after the execution attempt.", "$ref": "#/components/schemas/Swaps_QuoteStatus" } } }, "PriceTriggerSwaps_PriceTriggerCondition": { "description": "Price condition that determines when a price-triggered swap fires. Exactly one threshold is present.", "allOf": [ { "type": "object", "required": [ "base", "quote" ], "properties": { "base": { "description": "Base asset of the pair to monitor.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetRef" }, "quote": { "description": "Quote asset of the pair to monitor.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetRef" } } }, { "title": "threshold", "oneOf": [ { "title": "Drops to", "type": "object", "required": [ "drops_to" ], "properties": { "drops_to": { "description": "Fire when the monitored price reaches this value or below.", "type": "string" } } }, { "title": "Rises to", "type": "object", "required": [ "rises_to" ], "properties": { "rises_to": { "description": "Fire when the monitored price reaches this value or above.", "type": "string" } } } ] } ] }, "PriceTriggerSwaps_PriceTriggerSwap": { "description": "A swap that submits a trade when its price condition is met.", "type": "object", "required": [ "id", "status", "trade", "when", "created_at", "updated_at" ], "properties": { "id": { "description": "Unique identifier for this price-triggered swap.", "type": "string" }, "status": { "description": "Current lifecycle status of the price-triggered swap.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapStatus" }, "trade": { "description": "Trade to execute when the condition fires.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapRequestedTrade" }, "when": { "description": "Price condition that triggers the trade.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerCondition" }, "executed": { "description": "Realized trade details once the swap has executed.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapExecuted" }, "created_at": { "description": "Time at which the price-triggered swap was created.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which the price-triggered swap was last updated.", "$ref": "#/components/schemas/DateTime" }, "failure_reason": { "description": "Reason the price-triggered swap failed, when status is failed.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapFailureReason" }, "client_order_id": { "description": "A client order identifier which uniquely identifies a price trigger swap, echoed when it was provided on creation.", "type": "string", "maxLength": 64 } } }, "PriceTriggerSwaps_PriceTriggerSwapExecuted": { "description": "Realized trade details for an executed price-triggered swap.", "type": "object", "required": [ "from", "to", "rate", "fees", "executed_at" ], "properties": { "from": { "description": "Source asset and amount executed.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetAmount" }, "to": { "description": "Destination asset and amount received.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetAmount" }, "rate": { "description": "Exchange rate at which the trade executed.", "$ref": "#/components/schemas/PriceTriggerSwaps_Rate" }, "fees": { "description": "Fees charged on the executed trade.", "$ref": "#/components/schemas/PriceTriggerSwaps_Fees" }, "executed_at": { "description": "Time at which the trade executed.", "$ref": "#/components/schemas/DateTime" } } }, "PriceTriggerSwaps_PriceTriggerSwapRequestedTrade": { "description": "Requested trade attached to a price-triggered swap. Exactly one side carries `amount`; the other side is filled when the trade executes.", "type": "object", "required": [ "from", "to", "fee" ], "properties": { "from": { "description": "Requested source asset and optional fixed amount.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerRequestedTradeAsset" }, "to": { "description": "Requested destination asset and optional fixed amount.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerRequestedTradeAsset" }, "fee": { "description": "Partner fee applied to the trade.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerRequestedFee" } } }, "PriceTriggerSwaps_PriceTriggerRequestedTradeAsset": { "description": "Requested asset side returned on a price-triggered swap.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset ticker symbol.", "type": "string" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetType" }, "amount": { "description": "Decimal amount when this side was fixed by the request.", "type": "string" } } }, "PriceTriggerSwaps_PriceTriggerSwapFee": { "description": "Partner fee applied to a price-triggered swap.", "type": "object", "default": { "bps": 0 }, "properties": { "bps": { "description": "Fee in basis points, where 1 bps is 0.01%.", "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "default": 0 }, "absolute": { "description": "Absolute fee amount in the trade's quote currency.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "PriceTriggerSwaps_PriceTriggerRequestedFee": { "description": "Partner fee locked onto a requested price-triggered swap, expressed as the effective basis-points rate applied when it executes.", "type": "object", "required": [ "bps" ], "properties": { "bps": { "description": "Effective fee in basis points.", "type": "string" } } }, "PriceTriggerSwaps_PriceTriggerTradeAssetInput": { "description": "Asset side of a price-triggered swap trade request.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset ticker symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetType" }, "amount": { "description": "Decimal asset amount as a string to preserve precision.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "PriceTriggerSwaps_PriceTriggerSwapTradeInput": { "description": "Trade to submit when the condition is met. Set `amount` on exactly one of `from` or `to`; the other side is calculated when the trade executes.", "type": "object", "required": [ "from", "to" ], "properties": { "from": { "description": "Source asset and optional fixed amount for the trade.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerTradeAssetInput" }, "to": { "description": "Destination asset and optional fixed amount for the trade.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerTradeAssetInput" }, "fee": { "description": "Optional partner fee applied to the trade.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerSwapFee" } } }, "PriceTriggerSwaps_PriceTriggerConditionAssetInput": { "description": "Asset in the pair monitored by a price-triggered swap condition.", "type": "object", "required": [ "symbol", "type" ], "properties": { "symbol": { "description": "Asset ticker symbol.", "$ref": "#/components/schemas/AssetSymbol" }, "type": { "description": "Classification of the asset.", "$ref": "#/components/schemas/PriceTriggerSwaps_AssetType" } } }, "PriceTriggerSwaps_PriceTriggerConditionInput": { "description": "Price condition to monitor before executing a price-triggered swap. Set exactly one of `drops_to` or `rises_to`.", "allOf": [ { "type": "object", "required": [ "base", "quote" ], "properties": { "base": { "description": "Base asset of the pair to monitor.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerConditionAssetInput" }, "quote": { "description": "Quote asset of the pair to monitor.", "$ref": "#/components/schemas/PriceTriggerSwaps_PriceTriggerConditionAssetInput" } } }, { "title": "threshold", "oneOf": [ { "title": "Drops to", "type": "object", "required": [ "drops_to" ], "properties": { "drops_to": { "description": "Fire when the monitored price reaches this value or below. Mutually exclusive with `rises_to`.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, { "title": "Rises to", "type": "object", "required": [ "rises_to" ], "properties": { "rises_to": { "description": "Fire when the monitored price reaches this value or above. Mutually exclusive with `drops_to`.", "type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)?$" } } } ] } ] }, "Swaps_OnchainExecutionUnsupportedError": { "title": "Onchain Execution Unsupported", "description": "The quote cannot be executed through the onchain execution path.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "onchain_execution_unsupported" ] } } } ] } } } ] }, "Swaps_QuoteAmountTooSmallCause": { "description": "Details about a quote amount that is below the supported minimum.", "type": "object", "required": [ "field", "message", "symbol", "minimum" ], "properties": { "field": { "description": "Dot-notation path to the affected request field.", "type": "string" }, "message": { "description": "Human-readable explanation of the rejected amount.", "type": "string" }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-A-Za-z0-9._/]+$", "description": "Asset symbol whose requested amount is below the supported minimum." }, "minimum": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Minimum supported amount, denominated in `symbol`." } } }, "Swaps_QuoteAmountTooLargeCause": { "description": "Details about a quote amount that exceeds the supported maximum.", "type": "object", "required": [ "field", "message", "symbol", "maximum" ], "properties": { "field": { "description": "Dot-notation path to the affected request field.", "type": "string" }, "message": { "description": "Human-readable explanation of the rejected amount.", "type": "string" }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-A-Za-z0-9._/]+$", "description": "Asset symbol whose requested amount exceeds the supported maximum." }, "maximum": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "Maximum supported amount, denominated in `symbol`." } } }, "Swaps_QuoteAmountPrecisionTooHighCause": { "description": "Details about a quote amount with more decimal places than supported.", "type": "object", "required": [ "field", "message", "precision", "maximum_precision" ], "properties": { "field": { "description": "Dot-notation path to the affected request field.", "type": "string" }, "message": { "description": "Human-readable explanation of the rejected amount precision.", "type": "string" }, "precision": { "description": "Number of decimal places in the requested amount.", "type": "integer", "format": "int32", "minimum": 0 }, "maximum_precision": { "description": "Maximum number of decimal places supported for the requested amount.", "type": "integer", "format": "int32", "minimum": 0 } } }, "Swaps_TotalMarginTooLowCause": { "description": "Details about a requested total margin below the supported minimum.", "type": "object", "required": [ "field", "message", "requested_margin_bps", "minimum_margin_bps" ], "properties": { "field": { "description": "Dot-notation path to the affected request field.", "type": "string" }, "message": { "description": "Human-readable explanation of the rejected margin.", "type": "string" }, "requested_margin_bps": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[+-]?[0-9]+(\\.[0-9]+)?$", "description": "Requested total margin in basis points, represented as a decimal string." }, "minimum_margin_bps": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[+-]?[0-9]+(\\.[0-9]+)?$", "description": "Minimum supported total margin in basis points, represented as a decimal string." } } }, "Swaps_TotalMarginTooHighCause": { "description": "Details about a requested total margin above the supported maximum.", "type": "object", "required": [ "field", "message", "requested_margin_bps", "maximum_margin_bps" ], "properties": { "field": { "description": "Dot-notation path to the affected request field.", "type": "string" }, "message": { "description": "Human-readable explanation of the rejected margin.", "type": "string" }, "requested_margin_bps": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[+-]?[0-9]+(\\.[0-9]+)?$", "description": "Requested total margin in basis points, represented as a decimal string." }, "maximum_margin_bps": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[+-]?[0-9]+(\\.[0-9]+)?$", "description": "Maximum supported total margin in basis points, represented as a decimal string." } } }, "Swaps_QuoteAmountTooSmallError": { "title": "Quote Amount Too Small", "description": "The requested quote amount is below the minimum supported amount.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "quote_amount_too_small" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Swaps_QuoteAmountTooSmallCause" } } } } ] } } } ] }, "Swaps_QuoteAmountTooLargeError": { "title": "Quote Amount Too Large", "description": "The requested quote amount exceeds the maximum supported amount.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "quote_amount_too_large" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Swaps_QuoteAmountTooLargeCause" } } } } ] } } } ] }, "Swaps_QuoteAmountPrecisionTooHighError": { "title": "Quote Amount Precision Too High", "description": "The requested quote amount has more decimal places than supported.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "quote_amount_precision_too_high" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Swaps_QuoteAmountPrecisionTooHighCause" } } } } ] } } } ] }, "Swaps_TotalMarginTooLowError": { "title": "Total Margin Too Low", "description": "The requested total margin is below the supported minimum.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "total_margin_too_low" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Swaps_TotalMarginTooLowCause" } } } } ] } } } ] }, "Swaps_TotalMarginTooHighError": { "title": "Total Margin Too High", "description": "The requested total margin exceeds the supported maximum.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 400 }, "code": { "type": "string", "enum": [ "total_margin_too_high" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Swaps_TotalMarginTooHighCause" } } } } ] } } } ] }, "OnchainQuotes_TradeLockedError": { "title": "Trade Locked", "description": "The trade cannot proceed because the source or destination is locked.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "trade_locked" ] } } } ] } } } ] }, "Swaps_TradeLockedError": { "title": "Trade Locked", "description": "The trade cannot proceed because the source or destination is locked.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "trade_locked" ] } } } ] } } } ] }, "Swaps_AcquisitionLimitExceededError": { "title": "Acquisition Limit Exceeded", "description": "The trade would exceed an acquisition limit that applies to the account.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "acquisition_limit_exceeded" ] } } } ] } } } ] }, "Swaps_SuitabilityLimitExceededError": { "title": "Suitability Limit Exceeded", "description": "The trade would exceed a suitability limit that applies to the account.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "suitability_limit_exceeded" ] } } } ] } } } ] }, "Swaps_PatternDayTradingProtectionError": { "title": "Pattern Day Trading Protection", "description": "The trade was blocked by pattern day trading protection.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "pattern_day_trading_protection" ] } } } ] } } } ] }, "Swaps_PotentialWashTradeError": { "title": "Potential Wash Trade", "description": "The trade was blocked because it could be a wash trade.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 403 }, "code": { "type": "string", "enum": [ "potential_wash_trade" ] } } } ] } } } ] }, "Swaps_QuoteCancelledCause": { "description": "Details about a quote that has been canceled.", "type": "object", "required": [ "field", "message", "reason" ], "properties": { "field": { "description": "Dot-notation path to the quote identifier.", "type": "string" }, "message": { "description": "Human-readable explanation of the quote state.", "type": "string" }, "reason": { "title": "QuoteCancellationReason", "type": "string", "enum": [ "market_moved", "expired", "unknown" ], "description": "Public reason why the quote was canceled." } } }, "Swaps_SellOnlyAssetCause": { "description": "Details about one asset that is currently sell-only.", "type": "object", "required": [ "field", "message", "symbol" ], "properties": { "field": { "description": "Dot-notation path to the affected asset symbol.", "type": "string" }, "message": { "description": "Human-readable explanation of the trading restriction.", "type": "string" }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-A-Za-z0-9._/]+$", "description": "Symbol of an asset that is currently sell-only." } } }, "Swaps_IpoAssetCause": { "description": "Details about an asset in its initial public offering period.", "type": "object", "required": [ "field", "message", "symbol" ], "properties": { "field": { "description": "Dot-notation path to the affected asset symbol.", "type": "string" }, "message": { "description": "Human-readable explanation of the trading restriction.", "type": "string" }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-A-Za-z0-9._/]+$", "description": "Symbol of the asset in its initial public offering period." } } }, "Swaps_OtcSellOnlyCause": { "description": "Details about an OTC asset that is currently sell-only.", "type": "object", "required": [ "field", "message", "symbol" ], "properties": { "field": { "description": "Dot-notation path to the affected asset symbol.", "type": "string" }, "message": { "description": "Human-readable explanation of the trading restriction.", "type": "string" }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-A-Za-z0-9._/]+$", "description": "Symbol of the OTC asset that is currently sell-only." } } }, "OnchainQuotes_QuoteNotFoundError": { "description": "No quote exists for the supplied quote identifier.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "quote_not_found" ] } } } ] } } } ] }, "Swaps_QuoteNotFoundError": { "description": "No quote exists for the supplied quote identifier.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "quote_not_found" ] } } } ] } } } ] }, "PriceTriggerSwaps_PriceTriggerSwapNotFoundError": { "description": "No price-triggered swap exists for the supplied identifier.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "price_trigger_swap_not_found" ] } } } ] } } } ] }, "Swaps_InsufficientFundsError": { "title": "Insufficient Funds", "description": "The account does not have sufficient funds to execute the quote.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "insufficient_funds" ] } } } ] } } } ] }, "Swaps_QuoteCancelledError": { "title": "Quote Canceled", "description": "The quote has been canceled and can no longer be executed.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "quote_cancelled" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Swaps_QuoteCancelledCause" } } } } ] } } } ] }, "Swaps_QuoteExecutionFailedError": { "title": "Quote Execution Failed", "description": "The quote could not be executed because its execution failed.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "quote_execution_failed" ] } } } ] } } } ] }, "Swaps_InsufficientMarginError": { "title": "Insufficient Margin", "description": "The account does not have sufficient margin to execute the quote.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "insufficient_margin" ] } } } ] } } } ] }, "Swaps_SellOnlyAssetError": { "title": "Sell Only Asset", "description": "The destination asset is currently sell-only and cannot be acquired.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "sell_only_asset" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 32, "description": "One cause for each asset that is currently sell-only.", "items": { "$ref": "#/components/schemas/Swaps_SellOnlyAssetCause" } } } } ] } } } ] }, "Swaps_FractionalExtendedHoursError": { "title": "Fractional Extended Hours", "description": "Fractional equity trading is unavailable outside regular market hours.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "fractional_extended_hours" ] } } } ] } } } ] }, "Swaps_IpoAssetError": { "title": "IPO Asset", "description": "The asset cannot be traded while it is in its initial public offering period.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "ipo_asset" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Swaps_IpoAssetCause" } } } } ] } } } ] }, "Swaps_OtcRegularHoursOnlyError": { "title": "OTC Regular Hours Only", "description": "The OTC asset can only be traded during regular market hours.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "otc_regular_hours_only" ] } } } ] } } } ] }, "Swaps_OtcSellOnlyError": { "title": "OTC Sell Only", "description": "The OTC asset is currently sell-only and cannot be acquired.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code", "causes" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "otc_sell_only" ] }, "causes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Swaps_OtcSellOnlyCause" } } } } ] } } } ] }, "Swaps_EquityMarketClosedError": { "title": "Equity Market Closed", "description": "The equity market is closed and the trade cannot be submitted.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "equity_market_closed" ] } } } ] } } } ] }, "Swaps_IllegalOrderTypeAfterHoursError": { "title": "Illegal Order Type After Hours", "description": "The requested order type is unavailable outside regular market hours.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "illegal_order_type_after_hours" ] } } } ] } } } ] }, "PriceTriggerSwaps_PriceTriggerSwapNotCancellableError": { "description": "The price-triggered swap is no longer in a cancelable state.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "price_trigger_swap_not_cancellable" ] } } } ] } } } ] }, "PriceTriggerSwaps_PriceTriggerSwapClientOrderIdDuplicateError": { "description": "The client order id is already in use for another price-triggered swap.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "price_trigger_swap_client_order_id_duplicate" ] } } } ] } } } ] }, "PriceTriggerSwaps_PriceTriggerSwapTargetPriceAlreadyAvailableError": { "description": "The requested target price would trigger immediately.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 412 }, "code": { "type": "string", "enum": [ "price_trigger_swap_target_price_already_available" ] } } } ] } } } ] }, "Swaps_QuoteExpiredError": { "description": "The quote has expired and can no longer be executed.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 410 }, "code": { "type": "string", "enum": [ "quote_expired" ] } } } ] } } } ] }, "Swaps_InsufficientLiquidityError": { "title": "Insufficient Liquidity", "description": "The requested trade cannot be quoted because liquidity is insufficient.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "insufficient_liquidity" ] } } } ] } } } ] }, "TravelRuleVerifications_CreateTravelRuleVerificationBody": { "description": "Request to create a hosted declaration or self-attestation verification.", "oneOf": [ { "title": "Hosted declaration", "$ref": "#/components/schemas/TravelRuleVerifications_HostedDeclarationVerificationBody" }, { "title": "Self-attestation", "$ref": "#/components/schemas/TravelRuleVerifications_SelfAttestationVerificationBody" } ], "discriminator": { "propertyName": "method", "mapping": { "hosted_declaration": "#/components/schemas/TravelRuleVerifications_HostedDeclarationVerificationBody", "self_attestation": "#/components/schemas/TravelRuleVerifications_SelfAttestationVerificationBody" } } }, "TravelRuleVerifications_HostedDeclarationVerificationBody": { "description": "Request to verify a hosted wallet through a hosted declaration.", "type": "object", "additionalProperties": false, "required": [ "address", "method" ], "properties": { "address": { "description": "Wallet address to verify.", "type": "string", "minLength": 1, "maxLength": 256 }, "method": { "description": "Hosted declaration discriminator.", "type": "string", "enum": [ "hosted_declaration" ] } } }, "TravelRuleVerifications_SelfAttestationVerificationBody": { "description": "Request to verify a self-hosted wallet through self-attestation.", "type": "object", "additionalProperties": false, "required": [ "address", "method", "evidence" ], "properties": { "address": { "description": "Wallet address to verify.", "type": "string", "minLength": 1, "maxLength": 256 }, "method": { "description": "Self-attestation discriminator.", "type": "string", "enum": [ "self_attestation" ] }, "evidence": { "description": "Evidence that the user confirmed ownership and completed partner-side two-factor authentication.", "$ref": "#/components/schemas/TravelRuleVerifications_SelfAttestationEvidence" } } }, "TravelRuleVerifications_SelfAttestationEvidence": { "description": "Partner-collected evidence supporting a self-hosted wallet verification.", "type": "object", "required": [ "ownership_confirmed", "two_factor_completed", "two_factor_method", "attestation_text", "user_confirmed_at" ], "properties": { "ownership_confirmed": { "description": "Whether the user confirmed that they own or control the wallet.", "type": "boolean" }, "two_factor_completed": { "description": "Whether the partner confirmed that the user completed two-factor authentication.", "type": "boolean" }, "two_factor_method": { "description": "Two-factor authentication method completed by the user.", "$ref": "#/components/schemas/TravelRuleVerifications_TwoFactorMethod" }, "attestation_text": { "description": "Ownership statement confirmed by the user.", "type": "string", "minLength": 1, "maxLength": 4096 }, "user_confirmed_at": { "description": "Time at which the user confirmed the ownership statement.", "$ref": "#/components/schemas/DateTime" } } }, "TravelRuleVerifications_CreateTravelRuleVerificationEnvelope": { "description": "Response returned after creating a Travel Rule verification case.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Travel Rule verification case.", "$ref": "#/components/schemas/TravelRuleVerifications_TravelRuleVerification" } } }, "TravelRuleVerifications_GetTravelRuleVerificationEnvelope": { "description": "Response returned when reading a Travel Rule verification case.", "type": "object", "required": [ "data" ], "properties": { "data": { "description": "Travel Rule verification case.", "$ref": "#/components/schemas/TravelRuleVerifications_TravelRuleVerification" } } }, "TravelRuleVerifications_TravelRuleVerification": { "description": "Travel Rule verification case for a wallet address.", "type": "object", "required": [ "verification_id", "wallet_type", "status" ], "properties": { "verification_id": { "description": "Stable PWS identifier for the verification case.", "type": "string", "minLength": 1, "maxLength": 64 }, "wallet_type": { "description": "Type of wallet being verified.", "$ref": "#/components/schemas/TravelRuleVerifications_VerificationWalletType" }, "method": { "description": "Verification method submitted or started for this case, when one has been selected.", "$ref": "#/components/schemas/TravelRuleVerifications_VerificationMethod" }, "status": { "description": "Current verification status.", "$ref": "#/components/schemas/TravelRuleVerifications_VerificationStatus" }, "created_at": { "description": "Time at which PWS created the verification case projection.", "$ref": "#/components/schemas/DateTime" }, "updated_at": { "description": "Time at which PWS last updated the verification case projection.", "$ref": "#/components/schemas/DateTime" } } }, "TravelRuleVerifications_VerificationStatus": { "description": "Partner-facing proactive verification status. Pending is reserved for recovery when the Travel submission outcome is uncertain.", "type": "string", "enum": [ "pending", "verified", "failed" ] }, "TravelRuleVerifications_VerificationWalletType": { "description": "Wallet type for the verification case.", "type": "string", "enum": [ "hosted", "self_hosted" ] }, "TravelRuleVerifications_VerificationMethod": { "description": "Verification method for the case.", "type": "string", "enum": [ "hosted_declaration", "self_attestation" ] }, "TravelRuleVerifications_TwoFactorMethod": { "description": "Partner-side two-factor authentication method completed by the user.", "type": "string", "enum": [ "otp", "passkey" ] }, "TravelRuleVerifications_VerificationNotFoundError": { "description": "No Travel Rule verification case exists for the supplied identifier.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "verification_not_found" ] } } } ] } } } ] }, "TravelRuleVerifications_WalletTypeMismatchError": { "description": "The wallet address already has a verification with a different wallet type.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "wallet_type_mismatch" ] } } } ] } } } ] }, "TravelRuleVerifications_VerificationNotEnabledError": { "description": "Travel Rule address verification is not enabled for the user.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "verification_not_enabled" ] } } } ] } } } ] }, "TravelRuleVerifications_SatoshiTestRequiredError": { "description": "The address requires a Satoshi test and cannot use a weaker verification method.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "satoshi_test_required" ] } } } ] } } } ] }, "TravelRuleVerifications_VerificationRejectedError": { "description": "Travel Rule rejected the submitted verification.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 409 }, "code": { "type": "string", "enum": [ "verification_rejected" ] } } } ] } } } ] }, "Users_User": { "title": "User", "description": "Retrieved user resource.", "type": "object", "properties": { "id": { "description": "User ID, also used as the user's canonical identifier.", "type": "string", "minLength": 14, "maxLength": 42 }, "external_reference": { "description": "Optional partner-supplied reference for this user. Typically an identifier in the partner's own system, but any opaque string the partner wants to associate with the user is accepted.", "type": "string" }, "created_at": { "description": "The datetime when the user was created in ISO 8601 format.", "type": "string", "format": "date-time" }, "accounts": { "description": "Accounts associated with the user.", "type": "array", "items": { "description": "Account associated with a user.", "title": "UserAccount", "type": "object", "properties": { "id": { "description": "Public account identifier.", "type": "string", "minLength": 1, "maxLength": 42 }, "name": { "description": "Account display name.", "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "description": "Longer description of what the account is for. Absent when the account has none.", "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "name" ] } } }, "required": [ "created_at", "id" ] }, "Users_UserNotFoundError": { "description": "The requested user does not exist or is not accessible.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "user_not_found" ] } } } ] } } } ] }, "Verifications_VerificationSummary": { "type": "object", "description": "One verification recorded by the server.", "additionalProperties": false, "properties": { "verification_id": { "type": "string", "description": "Public identifier for a Payward-managed verification.", "pattern": "^PV[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{6}$", "minLength": 20, "maxLength": 20, "example": "PVABCDE-FGHIJ-KLMNOP" }, "types": { "type": "array", "description": "Document roles this verification covers. Hosted verifications cover the evidence collected in one session. URL verifications cover one role.", "items": { "$ref": "#/components/schemas/Verifications_VerificationType" }, "minItems": 1, "uniqueItems": true, "example": [ "proof_of_identity" ] }, "method": { "$ref": "#/components/schemas/Verifications_VerificationMethod" }, "status": { "$ref": "#/components/schemas/Verifications_VerificationStatus" }, "reasons": { "type": "array", "description": "Failure reasons accompanying the current status. Present when the verification has failure details.", "items": { "$ref": "#/components/schemas/Verifications_VerificationFailureReason" }, "maxItems": 20 }, "created_at": { "type": "string", "format": "date-time", "description": "Server timestamp when the verification was first recorded.", "example": "2026-05-20T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Server timestamp when the verification was last updated.", "example": "2026-05-20T14:45:00Z" } }, "required": [ "verification_id", "types", "method", "status", "created_at", "updated_at" ] }, "Verifications_VerificationFailureReason": { "type": "object", "description": "Grouped failure reason for a verification.", "properties": { "code": { "type": "string", "description": "Machine-readable failure reason code. Treat this value as informational unless your Payward integration defines specific handling.", "example": "verification_failed" }, "details": { "type": "array", "description": "Additional explanatory text. Display these strings, but do not parse or branch on them.", "items": { "type": "string", "minLength": 1, "maxLength": 1024 }, "maxItems": 32, "example": [ "Verification could not be completed." ] } }, "required": [ "code" ] }, "Verifications_VerificationStatus": { "type": "string", "description": "Lifecycle status of a verification.", "enum": [ "started", "pending", "completed", "failed" ] }, "Verifications_VerificationMethod": { "type": "string", "description": "How the verification evidence was collected.", "enum": [ "hosted", "url" ] }, "Verifications_VerificationType": { "type": "string", "description": "Document role covered by a verification.", "enum": [ "proof_of_identity", "proof_of_address", "proof_of_liveness", "validated_tax_id", "other", "proof_of_source_of_funds", "proof_of_source_of_wealth" ] }, "Verifications_ListVerificationsData": { "description": "Collection of verification summaries for a user.", "type": "object", "properties": { "verifications": { "type": "array", "description": "Verification summaries in reverse chronological order.", "items": { "$ref": "#/components/schemas/Verifications_VerificationSummary" }, "maxItems": 100 } }, "required": [ "verifications" ] }, "Verifications_HostedVerificationRequest": { "type": "object", "description": "Empty request body. PWS derives the provider and verification requirement.", "additionalProperties": false, "properties": {}, "example": {} }, "Verifications_HostedVerificationResponseBody": { "description": "Hosted verification methods available to the user, or an indication that none are required.", "type": "object", "additionalProperties": false, "properties": { "data": { "description": "Hosted verification result for the user's current requirements.", "title": "HostedVerificationResult", "oneOf": [ { "$ref": "#/components/schemas/Verifications_HostedVerificationMethodsResult" }, { "$ref": "#/components/schemas/Verifications_HostedVerificationNotRequiredResult" } ] } }, "required": [ "data" ] }, "Verifications_HostedVerificationEmbeddedMethod": { "description": "Provider-specific configuration for an embedded verification flow.", "type": "object", "additionalProperties": false, "properties": { "sumsub": { "$ref": "#/components/schemas/Verifications_SumsubEmbeddedVerificationMethod" } }, "required": [ "sumsub" ] }, "Verifications_HostedVerificationMethods": { "description": "Hosted verification methods available through web, embedded, or both interfaces.", "oneOf": [ { "$ref": "#/components/schemas/Verifications_HostedVerificationWebOnlyMethods" }, { "$ref": "#/components/schemas/Verifications_HostedVerificationEmbeddedOnlyMethods" }, { "$ref": "#/components/schemas/Verifications_HostedVerificationWebAndEmbeddedMethods" } ] }, "Verifications_HostedVerificationWebOnlyMethods": { "title": "Web", "description": "A hosted verification that is available through the web interface only.", "type": "object", "additionalProperties": false, "properties": { "web": { "description": "Configuration for the hosted web verification flow.", "$ref": "#/components/schemas/Verifications_HostedVerificationWebMethod" } }, "required": [ "web" ] }, "Verifications_HostedVerificationEmbeddedOnlyMethods": { "title": "Embedded", "description": "A hosted verification that is available through an embedded provider interface only.", "type": "object", "additionalProperties": false, "properties": { "embedded": { "description": "Configuration for the embedded verification flow.", "$ref": "#/components/schemas/Verifications_HostedVerificationEmbeddedMethod" } }, "required": [ "embedded" ] }, "Verifications_HostedVerificationWebAndEmbeddedMethods": { "title": "Web and embedded", "description": "A hosted verification available through both web and embedded interfaces.", "type": "object", "additionalProperties": false, "properties": { "web": { "description": "Configuration for the hosted web verification flow.", "$ref": "#/components/schemas/Verifications_HostedVerificationWebMethod" }, "embedded": { "description": "Configuration for the embedded verification flow.", "$ref": "#/components/schemas/Verifications_HostedVerificationEmbeddedMethod" } }, "required": [ "web", "embedded" ] }, "Verifications_HostedVerificationMethodsResult": { "title": "Verification methods", "description": "Public verification ID and hosted methods that the user can use to complete the required verification.", "type": "object", "additionalProperties": false, "properties": { "methods": { "description": "Interfaces available for completing the hosted verification.", "$ref": "#/components/schemas/Verifications_HostedVerificationMethods" }, "verification_id": { "type": "string", "description": "Public identifier for the created or reused Payward-managed verification.", "pattern": "^PV[A-Z0-9]{5}-[A-Z0-9]{5}-[A-Z0-9]{6}$", "minLength": 20, "maxLength": 20, "example": "PVABCDE-FGHIJ-KLMNOP" } }, "required": [ "methods", "verification_id" ] }, "Verifications_HostedVerificationNotRequiredResult": { "title": "Not required", "description": "Indicates that the user has no hosted verification to complete.", "type": "object", "additionalProperties": false, "properties": { "not_required": { "type": "object", "additionalProperties": false, "description": "The user has no actionable KYC requirement." } }, "required": [ "not_required" ] }, "Verifications_HostedVerificationWebMethod": { "description": "Expiring link to a provider-hosted verification interface.", "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "description": "Expiring URL for the hosted verification UI.", "example": "https://in.sumsub.com/websdk/pws-example" }, "expires_at": { "type": "string", "format": "date-time", "description": "Time when the hosted URL expires.", "example": "2026-07-29T18:00:00Z" } }, "required": [ "url", "expires_at" ] }, "Verifications_SumsubEmbeddedVerificationMethod": { "description": "Expiring credentials for starting an embedded Sumsub verification session.", "type": "object", "additionalProperties": false, "properties": { "access_token": { "type": "string", "description": "Expiring Sumsub SDK access token." }, "user_id": { "$ref": "#/components/schemas/UserId" }, "expires_at": { "type": "string", "format": "date-time", "description": "Time when the embedded session expires.", "example": "2026-07-29T18:00:00Z" } }, "required": [ "access_token", "user_id", "expires_at" ] }, "Verifications_VerificationStatusOk": { "title": "Active", "type": "object", "additionalProperties": false, "description": "The user is active.", "properties": { "state": { "description": "Current verification state of the user.", "type": "string", "enum": [ "ok" ] }, "user_action_required": { "type": "boolean", "description": "Whether the user or partner can complete a required action now." }, "required_actions": { "type": "array", "description": "Ordered actions associated with the current verification state.", "items": { "$ref": "#/components/schemas/Verifications_VerificationRequiredAction" } } }, "required": [ "state", "user_action_required", "required_actions" ] }, "Verifications_VerificationStatusDisabled": { "title": "Disabled", "type": "object", "additionalProperties": false, "description": "The user is disabled.", "properties": { "state": { "description": "Current verification state of the user.", "type": "string", "enum": [ "disabled" ] }, "user_action_required": { "type": "boolean", "description": "Whether the user or partner can complete a required action now." }, "required_actions": { "type": "array", "description": "Ordered actions associated with the current verification state.", "items": { "$ref": "#/components/schemas/Verifications_VerificationRequiredAction" } } }, "required": [ "state", "user_action_required", "required_actions" ] }, "Verifications_VerificationStatusClosed": { "title": "Closed", "type": "object", "additionalProperties": false, "description": "The user is closed.", "properties": { "state": { "description": "Current verification state of the user.", "type": "string", "enum": [ "closed" ] }, "user_action_required": { "type": "boolean", "description": "Whether the user or partner can complete a required action now." } }, "required": [ "state", "user_action_required" ] }, "Verifications_VerificationRequiredAction": { "description": "Next verification-related action for the user or partner.", "oneOf": [ { "$ref": "#/components/schemas/Verifications_CompleteVerificationAction" }, { "$ref": "#/components/schemas/Verifications_ProvideVerificationDetailsAction" }, { "$ref": "#/components/schemas/Verifications_WaitForVerificationAction" } ], "discriminator": { "propertyName": "action_type", "mapping": { "verification": "#/components/schemas/Verifications_CompleteVerificationAction", "provide_details": "#/components/schemas/Verifications_ProvideVerificationDetailsAction", "wait": "#/components/schemas/Verifications_WaitForVerificationAction" } } }, "Verifications_CompleteVerificationAction": { "title": "Complete verification", "type": "object", "additionalProperties": false, "description": "A verification the user must complete.", "properties": { "action_type": { "description": "Discriminator identifying a verification completion action.", "type": "string", "enum": [ "verification" ] }, "verification_type": { "$ref": "#/components/schemas/Verifications_RequiredVerificationType" }, "reasons": { "type": "array", "description": "Reason codes for the required verification.", "items": { "$ref": "#/components/schemas/Verifications_RequiredVerificationReason" } }, "deadline": { "type": "string", "format": "date-time", "description": "Deadline for completing the verification." } }, "required": [ "action_type", "verification_type" ] }, "Verifications_ProvideVerificationDetailsAction": { "title": "Provide details", "type": "object", "additionalProperties": false, "description": "Details the user must provide.", "properties": { "action_type": { "description": "Discriminator identifying an additional-details action.", "type": "string", "enum": [ "provide_details" ] }, "details_type": { "$ref": "#/components/schemas/Verifications_RequiredDetailsType" }, "reason": { "$ref": "#/components/schemas/Verifications_ProvideDetailsReason", "description": "Reason code for the required details." }, "deadline": { "type": "string", "format": "date-time", "description": "Deadline for providing the details." } }, "required": [ "action_type", "details_type" ] }, "Verifications_WaitForVerificationAction": { "title": "Wait", "type": "object", "additionalProperties": false, "description": "No user or partner action is required while Payward completes a check.", "properties": { "action_type": { "description": "Discriminator identifying a wait action.", "type": "string", "enum": [ "wait" ] }, "wait_reason_code": { "$ref": "#/components/schemas/Verifications_WaitReason", "description": "Reason code for the wait." } }, "required": [ "action_type", "wait_reason_code" ] }, "Verifications_RequiredVerificationType": { "type": "string", "description": "Stable reference for the next verification flow.", "enum": [ "identity", "residence", "selfie", "sanctions_check", "pep_check", "negative_news_check", "tax_id", "proof_of_source_of_funds", "proof_of_source_of_wealth" ] }, "Verifications_RequiredVerificationReason": { "type": "string", "description": "Reason that a verification is required.", "enum": [ "initial_onboarding" ] }, "Verifications_ProvideDetailsReason": { "type": "string", "description": "Reason that additional details are required.", "enum": [ "initial_onboarding" ] }, "Verifications_WaitReason": { "type": "string", "description": "Reason that no user or partner action is currently required.", "enum": [ "processing", "pending", "blocked" ] }, "Verifications_RequiredDetailsType": { "description": "Details the user or partner must provide.", "oneOf": [ { "$ref": "#/components/schemas/Verifications_TermsOfServiceRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_FullNameRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_DateOfBirthRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_CityOfBirthRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_CountryOfBirthRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_NationalitiesRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_ResidenceRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_PhoneRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_OccupationRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_TaxIdsRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_EmployerRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_ClientIdentifierRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_GreekDssInvestorIdRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_SourceOfFundsRequiredDetails" }, { "$ref": "#/components/schemas/Verifications_SourceOfWealthRequiredDetails" } ], "discriminator": { "propertyName": "type", "mapping": { "terms_of_service": "#/components/schemas/Verifications_TermsOfServiceRequiredDetails", "full_name": "#/components/schemas/Verifications_FullNameRequiredDetails", "date_of_birth": "#/components/schemas/Verifications_DateOfBirthRequiredDetails", "city_of_birth": "#/components/schemas/Verifications_CityOfBirthRequiredDetails", "country_of_birth": "#/components/schemas/Verifications_CountryOfBirthRequiredDetails", "nationalities": "#/components/schemas/Verifications_NationalitiesRequiredDetails", "residence": "#/components/schemas/Verifications_ResidenceRequiredDetails", "phone": "#/components/schemas/Verifications_PhoneRequiredDetails", "occupation": "#/components/schemas/Verifications_OccupationRequiredDetails", "tax_ids": "#/components/schemas/Verifications_TaxIdsRequiredDetails", "employer": "#/components/schemas/Verifications_EmployerRequiredDetails", "client_identifier": "#/components/schemas/Verifications_ClientIdentifierRequiredDetails", "greek_dss_investor_id": "#/components/schemas/Verifications_GreekDssInvestorIdRequiredDetails", "source_of_funds": "#/components/schemas/Verifications_SourceOfFundsRequiredDetails", "source_of_wealth": "#/components/schemas/Verifications_SourceOfWealthRequiredDetails" } } }, "Verifications_TermsOfServiceRequiredDetails": { "title": "Terms of service", "type": "object", "additionalProperties": false, "description": "Terms of service that the user must accept.", "properties": { "type": { "description": "Discriminator identifying terms-of-service details.", "type": "string", "enum": [ "terms_of_service" ] }, "version": { "type": "integer", "format": "int32", "minimum": 1, "description": "Required terms of service version." } }, "required": [ "type", "version" ] }, "Verifications_FullNameRequiredDetails": { "title": "Full name", "description": "Indicates that the user's full name must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying full-name details.", "type": "string", "enum": [ "full_name" ] } }, "required": [ "type" ] }, "Verifications_DateOfBirthRequiredDetails": { "title": "Date of birth", "description": "Indicates that the user's date of birth must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying date-of-birth details.", "type": "string", "enum": [ "date_of_birth" ] } }, "required": [ "type" ] }, "Verifications_CityOfBirthRequiredDetails": { "title": "City of birth", "description": "Indicates that the user's city of birth must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying city-of-birth details.", "type": "string", "enum": [ "city_of_birth" ] } }, "required": [ "type" ] }, "Verifications_CountryOfBirthRequiredDetails": { "title": "Country of birth", "description": "Indicates that the user's country of birth must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying country-of-birth details.", "type": "string", "enum": [ "country_of_birth" ] } }, "required": [ "type" ] }, "Verifications_NationalitiesRequiredDetails": { "title": "Nationalities", "description": "Indicates that the user's nationalities must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying nationality details.", "type": "string", "enum": [ "nationalities" ] } }, "required": [ "type" ] }, "Verifications_ResidenceRequiredDetails": { "title": "Residence", "description": "Indicates that the user's residence details must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying residence details.", "type": "string", "enum": [ "residence" ] } }, "required": [ "type" ] }, "Verifications_PhoneRequiredDetails": { "title": "Phone", "description": "Indicates that the user's phone number must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying phone details.", "type": "string", "enum": [ "phone" ] } }, "required": [ "type" ] }, "Verifications_OccupationRequiredDetails": { "title": "Occupation", "description": "Indicates that the user's occupation must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying occupation details.", "type": "string", "enum": [ "occupation" ] } }, "required": [ "type" ] }, "Verifications_TaxIdsRequiredDetails": { "title": "Tax IDs", "description": "Indicates that the user's tax identifiers must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying tax-identifier details.", "type": "string", "enum": [ "tax_ids" ] } }, "required": [ "type" ] }, "Verifications_EmployerRequiredDetails": { "title": "Employer", "description": "Indicates that the user's employer must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying employer details.", "type": "string", "enum": [ "employer" ] } }, "required": [ "type" ] }, "Verifications_ClientIdentifierRequiredDetails": { "title": "Client identifier", "description": "Indicates that the user's client identifier must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying client-identifier details.", "type": "string", "enum": [ "client_identifier" ] } }, "required": [ "type" ] }, "Verifications_GreekDssInvestorIdRequiredDetails": { "title": "Greek DSS investor ID", "description": "Indicates that the user's Greek DSS investor ID must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying Greek DSS investor ID details.", "type": "string", "enum": [ "greek_dss_investor_id" ] } }, "required": [ "type" ] }, "Verifications_SourceOfFundsRequiredDetails": { "title": "Source of funds", "description": "Indicates that the user's source of funds declaration must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying source of funds details.", "type": "string", "enum": [ "source_of_funds" ] } }, "required": [ "type" ] }, "Verifications_SourceOfWealthRequiredDetails": { "title": "Source of wealth", "description": "Indicates that the user's source of wealth declaration must be provided.", "type": "object", "additionalProperties": false, "properties": { "type": { "description": "Discriminator identifying source of wealth details.", "type": "string", "enum": [ "source_of_wealth" ] } }, "required": [ "type" ] }, "Verifications_VerificationRequirementsNotFoundError": { "description": "The requested user's verification requirements do not exist.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "verification_requirements_not_found" ] } } } ] } } } ] }, "Webhooks_WebhookEventType": { "title": "WebhookEventType", "description": "Event type supported by the webhooks API.", "type": "string", "enum": [ "quote.executed", "quote.cancelled", "quote.execution_failed", "user.closed", "user.disabled", "conversion.deposit_completed", "conversion.deposit_failed", "conversion.deposit_held", "conversion.withdrawal_completed", "conversion.withdrawal_failed", "conversion.quote_execution_failed", "conversion.travel_rule_blocked", "transaction.swap", "transaction.price_trigger_swap", "transaction.earn_reward", "transaction.deposit", "transaction.withdrawal", "transaction.transfer", "conversion.quote_executed", "funds.deposit_received", "funds.deposit_held", "funds.deposit_credited", "funds.deposit_returned", "funds.deposit_failed", "verification.requirements_updated", "verification.updated", "price_trigger_swap.executed", "price_trigger_swap.execution_failed", "price_trigger_swap.cancelled", "price_trigger_swap.created", "price_trigger_swap.failed", "funds.withdrawal_held", "funds.withdrawal_complete", "funds.withdrawal_failed", "recurring_swap.created", "recurring_swap.executed", "recurring_swap.execution_failed", "recurring_swap.cancelled", "recurring_swap.failed", "recurring_swap.paused", "recurring_swap.resumed", "transaction.recurring_swap" ] }, "Webhooks_QuoteExecutedPayload": { "title": "QuoteExecutedPayload", "description": "Payload delivered for the `quote.executed` webhook event.", "type": "object", "required": [ "type", "quote_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "quote.executed" }, "quote_id": { "description": "Public quote identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "executed_at": { "description": "Time at which the quote was executed.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_QuoteCancelledPayload": { "title": "QuoteCancelledPayload", "description": "Payload delivered for the `quote.cancelled` webhook event.", "type": "object", "required": [ "type", "quote_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "quote.cancelled" }, "quote_id": { "description": "Public quote identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" } } }, "Webhooks_QuoteExecutionFailedPayload": { "title": "QuoteExecutionFailedPayload", "description": "Payload delivered for the `quote.execution_failed` webhook event.", "type": "object", "required": [ "type", "quote_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "quote.execution_failed" }, "quote_id": { "description": "Public quote identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" } } }, "Webhooks_UserClosedPayload": { "title": "UserClosedPayload", "description": "Payload delivered for the `user.closed` webhook event.", "type": "object", "required": [ "type", "user_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "user.closed" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_UserDisabledPayload": { "title": "UserDisabledPayload", "description": "Payload delivered for the `user.disabled` webhook event.", "type": "object", "required": [ "type", "user_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "user.disabled" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_ConversionChainReferences": { "title": "ConversionChainReferences", "description": "Funding transaction references observed in a conversion lifecycle.", "type": "object", "properties": { "deposit_txid": { "description": "Inbound deposit transaction identifier.", "type": "string" }, "withdraw_txid": { "description": "Outbound withdrawal transaction identifier.", "type": "string" }, "blockchain_transaction_id": { "description": "On-chain transaction identifier or hash.", "type": "string" } } }, "Webhooks_ConversionFailureCode": { "title": "ConversionFailureCode", "description": "Stable public conversion failure category.", "type": "string", "enum": [ "amount_too_small", "quote_expired", "destination_rejected", "unknown", "travel_rule_data_missing", "wallet_not_whitelisted", "wallet_verification_method_not_supported" ] }, "Webhooks_ConversionConvertingStatus": { "title": "ConversionConvertingStatus", "description": "Conversion lifecycle status for an active conversion.", "type": "string", "const": "converting" }, "Webhooks_ConversionFailedStatus": { "title": "ConversionFailedStatus", "description": "Conversion lifecycle status for a failed conversion.", "type": "string", "const": "failed" }, "Webhooks_ConversionHeldStatus": { "title": "ConversionHeldStatus", "description": "Conversion lifecycle status for a held conversion.", "type": "string", "const": "held" }, "Webhooks_ConversionCompletedStatus": { "title": "ConversionCompletedStatus", "description": "Conversion lifecycle status for a completed conversion.", "type": "string", "const": "completed" }, "Webhooks_ConversionFee": { "title": "ConversionFee", "description": "Fee breakdown for an executed conversion quote.", "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "description": "Fee amount as a decimal string.", "type": "string" }, "currency": { "description": "Fee asset symbol.", "type": "string" }, "fee_bps": { "description": "Fee in basis points.", "type": "integer", "minimum": 0, "maximum": 4294967295 } } }, "Webhooks_PortfolioTransactionStatus": { "title": "PortfolioTransactionStatus", "description": "Current public portfolio transaction status.", "type": "string", "enum": [ "uncategorized", "in_progress", "successful", "failed" ] }, "Webhooks_PortfolioTransactionAmount": { "title": "PortfolioTransactionAmount", "description": "Native amount of an asset involved in a portfolio transaction.", "type": "object", "required": [ "symbol", "amount" ], "properties": { "symbol": { "description": "Asset symbol.", "type": "string" }, "amount": { "description": "Native amount as a decimal string.", "type": "string" } } }, "Webhooks_PortfolioTransactionReferenceKind": { "title": "PortfolioTransactionReferenceKind", "description": "Originating-system reference kind.", "type": "string", "enum": [ "funding", "transfer" ] }, "Webhooks_PortfolioTransactionReference": { "title": "PortfolioTransactionReference", "description": "Public identifier assigned by the originating system.", "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "description": "Originating-system reference kind.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionReferenceKind" }, "id": { "description": "Public originating-system identifier.", "type": "string" } } }, "Webhooks_PortfolioTransactionTradeType": { "title": "PortfolioTransactionTradeType", "description": "Trade direction from the user's perspective.", "type": "string", "enum": [ "buy", "sell", "convert" ] }, "Webhooks_PortfolioTransactionSwapDetails": { "title": "PortfolioTransactionSwapDetails", "description": "Swap-specific transaction details.", "type": "object", "properties": { "quote_id": { "description": "Associated public quote identifier.", "type": "string" }, "trade_type": { "description": "Trade direction from the user's perspective.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionTradeType" } } }, "Webhooks_PortfolioTransactionEarnRewardDetails": { "title": "PortfolioTransactionEarnRewardDetails", "description": "Earn-reward-specific transaction details.", "type": "object", "properties": { "strategy_id": { "description": "Earn strategy identifier.", "type": "string" }, "reward_id": { "description": "Earn reward identifier.", "type": "string" } } }, "Webhooks_PortfolioTransactionFundingDetails": { "title": "PortfolioTransactionFundingDetails", "description": "Funding-specific transaction details.", "type": "object", "required": [ "crypto_transaction_id" ], "properties": { "crypto_transaction_id": { "description": "On-chain transaction identifier or hash.", "type": "string" } } }, "Webhooks_FundsDepositReason": { "title": "FundsDepositReason", "description": "Partner-safe reason why a deposit failed or was returned.", "type": "string", "enum": [ "account_details_mismatch", "limit_exceeded", "duplicate", "account_restricted", "other" ] }, "Webhooks_VerificationRequirementsUpdatedPayload": { "title": "VerificationRequirementsUpdatedPayload", "description": "Payload delivered for the `verification.requirements_updated` webhook event.", "type": "object", "required": [ "type", "user_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "verification.requirements_updated" }, "user_id": { "$ref": "#/components/schemas/UserId" } } }, "Webhooks_VerificationUpdatedPayload": { "title": "VerificationUpdatedPayload", "description": "Payload delivered for the `verification.updated` webhook event.", "type": "object", "required": [ "type", "user_id", "verification_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "verification.updated" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "verification_id": { "description": "Public verification identifier.", "type": "string" } } }, "Webhooks_ConversionDepositCompletedPayload": { "title": "ConversionDepositCompletedPayload", "description": "Payload delivered for the `conversion.deposit_completed` webhook event.", "type": "object", "required": [ "type", "transaction_id", "conversion_id", "user_id", "status", "observed_at", "chain_references" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "conversion.deposit_completed" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "conversion_id": { "description": "Public conversion rule identifier.", "type": "string", "format": "uuid" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "status": { "description": "Public conversion lifecycle status.", "$ref": "#/components/schemas/Webhooks_ConversionConvertingStatus" }, "observed_at": { "description": "Time at which the lifecycle transition was observed.", "$ref": "#/components/schemas/DateTime" }, "chain_references": { "description": "Funding transaction references observed in the lifecycle.", "$ref": "#/components/schemas/Webhooks_ConversionChainReferences" }, "deposit_reference": { "description": "User payment reference from the inbound deposit.", "type": "string" }, "deposit_amount": { "description": "Inbound deposit amount as a decimal string.", "type": "string" }, "deposit_currency": { "description": "Inbound deposit asset symbol.", "type": "string" }, "network": { "description": "Crypto delivery network.", "type": "string" } } }, "Webhooks_ConversionDepositFailedPayload": { "title": "ConversionDepositFailedPayload", "description": "Payload delivered for the `conversion.deposit_failed` webhook event.", "type": "object", "required": [ "type", "transaction_id", "conversion_id", "user_id", "status", "observed_at", "chain_references" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "conversion.deposit_failed" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "conversion_id": { "description": "Public conversion rule identifier.", "type": "string", "format": "uuid" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "status": { "description": "Public conversion lifecycle status.", "$ref": "#/components/schemas/Webhooks_ConversionFailedStatus" }, "observed_at": { "description": "Time at which the lifecycle transition was observed.", "$ref": "#/components/schemas/DateTime" }, "chain_references": { "description": "Funding transaction references observed in the lifecycle.", "$ref": "#/components/schemas/Webhooks_ConversionChainReferences" }, "error_code": { "description": "Stable public conversion failure category.", "$ref": "#/components/schemas/Webhooks_ConversionFailureCode" }, "deposit_amount": { "description": "Inbound deposit amount as a decimal string.", "type": "string" }, "deposit_currency": { "description": "Inbound deposit asset symbol.", "type": "string" } } }, "Webhooks_ConversionDepositHeldPayload": { "title": "ConversionDepositHeldPayload", "description": "Payload delivered for the `conversion.deposit_held` webhook event.", "type": "object", "required": [ "type", "transaction_id", "conversion_id", "user_id", "status", "observed_at", "chain_references" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "conversion.deposit_held" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "conversion_id": { "description": "Public conversion rule identifier.", "type": "string", "format": "uuid" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "status": { "description": "Public conversion lifecycle status.", "$ref": "#/components/schemas/Webhooks_ConversionHeldStatus" }, "observed_at": { "description": "Time at which the lifecycle transition was observed.", "$ref": "#/components/schemas/DateTime" }, "chain_references": { "description": "Funding transaction references observed in the lifecycle.", "$ref": "#/components/schemas/Webhooks_ConversionChainReferences" }, "deposit_amount": { "description": "Inbound deposit amount as a decimal string.", "type": "string" }, "deposit_currency": { "description": "Inbound deposit asset symbol.", "type": "string" } } }, "Webhooks_ConversionWithdrawalCompletedPayload": { "title": "ConversionWithdrawalCompletedPayload", "description": "Payload delivered for the `conversion.withdrawal_completed` webhook event.", "type": "object", "required": [ "type", "transaction_id", "conversion_id", "user_id", "status", "observed_at", "chain_references" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "conversion.withdrawal_completed" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "conversion_id": { "description": "Public conversion rule identifier.", "type": "string", "format": "uuid" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "status": { "description": "Public conversion lifecycle status.", "$ref": "#/components/schemas/Webhooks_ConversionCompletedStatus" }, "observed_at": { "description": "Time at which the lifecycle transition was observed.", "$ref": "#/components/schemas/DateTime" }, "chain_references": { "description": "Funding transaction references observed in the lifecycle.", "$ref": "#/components/schemas/Webhooks_ConversionChainReferences" }, "withdrawal_amount": { "description": "Outbound withdrawal amount as a decimal string.", "type": "string" }, "withdrawal_currency": { "description": "Outbound withdrawal asset symbol.", "type": "string" }, "network": { "description": "Crypto delivery network.", "type": "string" }, "destination_address": { "description": "Crypto destination address.", "type": "string" } } }, "Webhooks_ConversionWithdrawalFailedPayload": { "title": "ConversionWithdrawalFailedPayload", "description": "Payload delivered for the `conversion.withdrawal_failed` webhook event.", "type": "object", "required": [ "type", "transaction_id", "conversion_id", "user_id", "status", "observed_at", "chain_references" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "conversion.withdrawal_failed" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "conversion_id": { "description": "Public conversion rule identifier.", "type": "string", "format": "uuid" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "status": { "description": "Public conversion lifecycle status.", "$ref": "#/components/schemas/Webhooks_ConversionFailedStatus" }, "observed_at": { "description": "Time at which the lifecycle transition was observed.", "$ref": "#/components/schemas/DateTime" }, "chain_references": { "description": "Funding transaction references observed in the lifecycle.", "$ref": "#/components/schemas/Webhooks_ConversionChainReferences" }, "error_code": { "description": "Stable public conversion failure category.", "$ref": "#/components/schemas/Webhooks_ConversionFailureCode" }, "withdrawal_amount": { "description": "Outbound withdrawal amount as a decimal string.", "type": "string" }, "withdrawal_currency": { "description": "Outbound withdrawal asset symbol.", "type": "string" }, "destination_address": { "description": "Crypto destination address.", "type": "string" } } }, "Webhooks_ConversionQuoteExecutionFailedPayload": { "title": "ConversionQuoteExecutionFailedPayload", "description": "Payload delivered for the `conversion.quote_execution_failed` webhook event.", "type": "object", "required": [ "type", "transaction_id", "conversion_id", "user_id", "status", "observed_at", "chain_references" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "conversion.quote_execution_failed" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "conversion_id": { "description": "Public conversion rule identifier.", "type": "string", "format": "uuid" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "status": { "description": "Public conversion lifecycle status.", "$ref": "#/components/schemas/Webhooks_ConversionFailedStatus" }, "observed_at": { "description": "Time at which the lifecycle transition was observed.", "$ref": "#/components/schemas/DateTime" }, "chain_references": { "description": "Funding transaction references observed in the lifecycle.", "$ref": "#/components/schemas/Webhooks_ConversionChainReferences" }, "error_code": { "description": "Stable public conversion failure category.", "$ref": "#/components/schemas/Webhooks_ConversionFailureCode" }, "source_amount": { "description": "Quote source amount as a decimal string.", "type": "string" }, "source_currency": { "description": "Quote source asset symbol.", "type": "string" }, "destination_currency": { "description": "Quote destination asset symbol.", "type": "string" } } }, "Webhooks_ConversionTravelRuleBlockedPayload": { "title": "ConversionTravelRuleBlockedPayload", "description": "Payload delivered for the `conversion.travel_rule_blocked` webhook event.", "type": "object", "required": [ "type", "transaction_id", "conversion_id", "user_id", "status", "observed_at", "chain_references" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "conversion.travel_rule_blocked" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "conversion_id": { "description": "Public conversion rule identifier.", "type": "string", "format": "uuid" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "status": { "description": "Public conversion lifecycle status.", "$ref": "#/components/schemas/Webhooks_ConversionFailedStatus" }, "observed_at": { "description": "Time at which the lifecycle transition was observed.", "$ref": "#/components/schemas/DateTime" }, "chain_references": { "description": "Funding transaction references observed in the lifecycle.", "$ref": "#/components/schemas/Webhooks_ConversionChainReferences" }, "error_code": { "description": "Stable public conversion failure category.", "$ref": "#/components/schemas/Webhooks_ConversionFailureCode" }, "source_amount": { "description": "Quote source amount as a decimal string.", "type": "string" }, "source_currency": { "description": "Quote source asset symbol.", "type": "string" }, "destination_currency": { "description": "Quote destination asset symbol.", "type": "string" } } }, "Webhooks_ConversionQuoteExecutedPayload": { "title": "ConversionQuoteExecutedPayload", "description": "Payload delivered for the `conversion.quote_executed` webhook event.", "type": "object", "required": [ "type", "transaction_id", "conversion_id", "user_id", "status", "observed_at", "chain_references" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "conversion.quote_executed" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "conversion_id": { "description": "Public conversion rule identifier.", "type": "string", "format": "uuid" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "status": { "description": "Public conversion lifecycle status.", "$ref": "#/components/schemas/Webhooks_ConversionConvertingStatus" }, "observed_at": { "description": "Time at which the lifecycle transition was observed.", "$ref": "#/components/schemas/DateTime" }, "chain_references": { "description": "Funding transaction references observed in the lifecycle.", "$ref": "#/components/schemas/Webhooks_ConversionChainReferences" }, "source_amount": { "description": "Quote source amount as a decimal string.", "type": "string" }, "source_currency": { "description": "Quote source asset symbol.", "type": "string" }, "destination_amount": { "description": "Quote destination amount as a decimal string.", "type": "string" }, "destination_currency": { "description": "Quote destination asset symbol.", "type": "string" }, "quote_id": { "description": "Public quote identifier.", "type": "string" }, "executed_at": { "description": "Time at which the quote was executed.", "$ref": "#/components/schemas/DateTime" }, "rate": { "description": "Executed unit price as a decimal string.", "type": "string" }, "fee": { "description": "Fee breakdown for the executed quote.", "$ref": "#/components/schemas/Webhooks_ConversionFee" } } }, "Webhooks_TransactionSwapPayload": { "title": "TransactionSwapPayload", "description": "Payload delivered for the `transaction.swap` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "transaction.swap" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" }, "status": { "description": "Current public portfolio transaction status.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionStatus" }, "spend": { "description": "Asset spent by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "receive": { "description": "Asset received by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "details": { "description": "Swap-specific transaction details.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionSwapDetails" } } }, "Webhooks_TransactionPriceTriggerSwapPayload": { "title": "TransactionPriceTriggerSwapPayload", "description": "Payload delivered for the `transaction.price_trigger_swap` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "transaction.price_trigger_swap" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" }, "status": { "description": "Current public portfolio transaction status.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionStatus" }, "spend": { "description": "Asset spent by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "receive": { "description": "Asset received by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "details": { "description": "Swap-specific transaction details.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionSwapDetails" } } }, "Webhooks_TransactionEarnRewardPayload": { "title": "TransactionEarnRewardPayload", "description": "Payload delivered for the `transaction.earn_reward` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "transaction.earn_reward" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" }, "status": { "description": "Current public portfolio transaction status.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionStatus" }, "spend": { "description": "Asset spent by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "receive": { "description": "Asset received by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "details": { "description": "Earn-reward-specific transaction details.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionEarnRewardDetails" } } }, "Webhooks_TransactionDepositPayload": { "title": "TransactionDepositPayload", "description": "Payload delivered for the `transaction.deposit` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "transaction.deposit" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" }, "status": { "description": "Current public portfolio transaction status.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionStatus" }, "spend": { "description": "Asset spent by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "receive": { "description": "Asset received by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "reference": { "description": "Public identifier assigned by the originating system.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionReference" }, "details": { "description": "Funding-specific transaction details.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionFundingDetails" } } }, "Webhooks_TransactionWithdrawalPayload": { "title": "TransactionWithdrawalPayload", "description": "Payload delivered for the `transaction.withdrawal` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "transaction.withdrawal" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" }, "status": { "description": "Current public portfolio transaction status.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionStatus" }, "spend": { "description": "Asset spent by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "receive": { "description": "Asset received by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "reference": { "description": "Public identifier assigned by the originating system.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionReference" }, "details": { "description": "Funding-specific transaction details.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionFundingDetails" } } }, "Webhooks_TransactionTransferPayload": { "title": "TransactionTransferPayload", "description": "Payload delivered for the `transaction.transfer` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "transaction.transfer" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" }, "status": { "description": "Current public portfolio transaction status.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionStatus" }, "spend": { "description": "Asset spent by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "receive": { "description": "Asset received by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "reference": { "description": "Public identifier assigned by the originating system.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionReference" } } }, "Webhooks_FundsDepositAssetAmount": { "title": "FundsDepositAssetAmount", "description": "Public asset and decimal value reported for a deposit amount or fee.", "type": "object", "required": [ "asset", "value" ], "properties": { "asset": { "description": "Public asset symbol.", "type": "string", "minLength": 1 }, "value": { "description": "Amount as a decimal string.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^-?[0-9]+(\\.[0-9]+)?$" } } }, "Webhooks_FundsDepositReceivedPayload": { "title": "FundsDepositReceivedPayload", "description": "Payload delivered for the `funds.deposit_received` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "funds.deposit_received" }, "transaction_id": { "description": "Opaque funding transaction reference.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "amount": { "description": "Deposit amount. Absent when it cannot be resolved to a public asset and decimal value.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "fee": { "description": "Deposit fee, including a zero fee. Absent when fee data is unavailable or cannot be resolved.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "observed_at": { "description": "Time at which the deposit transition was observed.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_FundsDepositHeldPayload": { "title": "FundsDepositHeldPayload", "description": "Payload delivered for the `funds.deposit_held` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "funds.deposit_held" }, "transaction_id": { "description": "Opaque funding transaction reference.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "amount": { "description": "Deposit amount. Absent when it cannot be resolved to a public asset and decimal value.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "fee": { "description": "Deposit fee, including a zero fee. Absent when fee data is unavailable or cannot be resolved.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "observed_at": { "description": "Time at which the deposit transition was observed.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_FundsDepositCreditedPayload": { "title": "FundsDepositCreditedPayload", "description": "Payload delivered for the `funds.deposit_credited` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "funds.deposit_credited" }, "transaction_id": { "description": "Opaque funding transaction reference.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "amount": { "description": "Deposit amount. Absent when it cannot be resolved to a public asset and decimal value.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "fee": { "description": "Deposit fee, including a zero fee. Absent when fee data is unavailable or cannot be resolved.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "observed_at": { "description": "Time at which the deposit transition was observed.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_FundsDepositReturnedPayload": { "title": "FundsDepositReturnedPayload", "description": "Payload delivered for the `funds.deposit_returned` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "reason" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "funds.deposit_returned" }, "transaction_id": { "description": "Opaque funding transaction reference.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "amount": { "description": "Deposit amount. Absent when it cannot be resolved to a public asset and decimal value.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "fee": { "description": "Deposit fee, including a zero fee. Absent when fee data is unavailable or cannot be resolved.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "observed_at": { "description": "Time at which the deposit transition was observed.", "$ref": "#/components/schemas/DateTime" }, "reason": { "description": "Partner-safe reason why the deposit was returned.", "$ref": "#/components/schemas/Webhooks_FundsDepositReason" } } }, "Webhooks_FundsDepositFailedPayload": { "title": "FundsDepositFailedPayload", "description": "Payload delivered for the `funds.deposit_failed` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "reason" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "funds.deposit_failed" }, "transaction_id": { "description": "Opaque funding transaction reference.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "amount": { "description": "Deposit amount. Absent when it cannot be resolved to a public asset and decimal value.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "fee": { "description": "Deposit fee, including a zero fee. Absent when fee data is unavailable or cannot be resolved.", "$ref": "#/components/schemas/Webhooks_FundsDepositAssetAmount" }, "observed_at": { "description": "Time at which the deposit transition was observed.", "$ref": "#/components/schemas/DateTime" }, "reason": { "description": "Partner-safe reason why the deposit failed.", "$ref": "#/components/schemas/Webhooks_FundsDepositReason" } } }, "Webhooks_FundsWithdrawalAssetAmount": { "title": "FundsWithdrawalAssetAmount", "description": "Asset denomination and quantity associated with a withdrawal amount or fee.", "type": "object", "required": [ "asset", "value" ], "properties": { "asset": { "description": "Public symbol of the asset in which the value is denominated.", "type": "string", "minLength": 1 }, "value": { "description": "Quantity denominated in `asset`.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^-?[0-9]+(\\.[0-9]+)?$" } } }, "Webhooks_FundsWithdrawalHeldPayload": { "title": "FundsWithdrawalHeldPayload", "description": "Payload delivered for the `funds.withdrawal_held` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "funds.withdrawal_held" }, "transaction_id": { "description": "Opaque withdrawal transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "amount": { "description": "When `amount.asset` equals `fee.asset`, the gross withdrawal amount, inclusive of the fee. When the fee uses another asset, the withdrawal amount in its own asset. PWS reports it when the source value can be resolved to a public asset.", "$ref": "#/components/schemas/Webhooks_FundsWithdrawalAssetAmount" }, "fee": { "description": "Fee charged for the withdrawal. When the fee uses a different asset from `amount`, PWS reports it separately. PWS reports it independently when the value can be resolved to a public asset.", "$ref": "#/components/schemas/Webhooks_FundsWithdrawalAssetAmount" } } }, "Webhooks_FundsWithdrawalCompletePayload": { "title": "FundsWithdrawalCompletePayload", "description": "Payload delivered for the `funds.withdrawal_complete` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "funds.withdrawal_complete" }, "transaction_id": { "description": "Opaque withdrawal transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "amount": { "description": "When `amount.asset` equals `fee.asset`, the gross withdrawal amount, inclusive of the fee. When the fee uses another asset, the withdrawal amount in its own asset. PWS reports it when the source value can be resolved to a public asset.", "$ref": "#/components/schemas/Webhooks_FundsWithdrawalAssetAmount" }, "fee": { "description": "Fee charged for the withdrawal. When the fee uses a different asset from `amount`, PWS reports it separately. PWS reports it independently when the value can be resolved to a public asset.", "$ref": "#/components/schemas/Webhooks_FundsWithdrawalAssetAmount" } } }, "Webhooks_FundsWithdrawalFailedPayload": { "title": "FundsWithdrawalFailedPayload", "description": "Payload delivered for the `funds.withdrawal_failed` webhook event.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "funds.withdrawal_failed" }, "transaction_id": { "description": "Opaque withdrawal transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "amount": { "description": "Amount recorded for the withdrawal request. This does not imply that the amount remained debited after failure. PWS reports it when the source value can be resolved to a public asset.", "$ref": "#/components/schemas/Webhooks_FundsWithdrawalAssetAmount" }, "fee": { "description": "Fee recorded or calculated for the withdrawal request. This does not imply that the fee was ultimately charged; failed withdrawals may be reversed. PWS reports it independently when the source value can be resolved to a public asset.", "$ref": "#/components/schemas/Webhooks_FundsWithdrawalAssetAmount" } } }, "Webhooks_PriceTriggerSwapAssetAmount": { "title": "PriceTriggerSwapAssetAmount", "description": "Asset and amount on a requested or executed scheduled swap trade leg.", "type": "object", "required": [ "symbol" ], "properties": { "symbol": { "description": "Public asset symbol.", "type": "string" }, "amount": { "description": "Decimal amount as a string. Absent when only the asset is known.", "type": "string" } } }, "Webhooks_PriceTriggerSwapThreshold": { "title": "PriceTriggerSwapThreshold", "description": "Price threshold that activates the swap. Exactly one threshold direction is present.", "oneOf": [ { "title": "Drops to", "type": "object", "required": [ "drops_to" ], "properties": { "drops_to": { "description": "Fire when the monitored price reaches this value or below.", "type": "string" } } }, { "title": "Rises to", "type": "object", "required": [ "rises_to" ], "properties": { "rises_to": { "description": "Fire when the monitored price reaches this value or above.", "type": "string" } } } ] }, "Webhooks_PriceTriggerSwapWhen": { "title": "PriceTriggerSwapWhen", "description": "Monitored pair and threshold for a price-trigger swap. Exactly one of `drops_to` or `rises_to` is present.", "allOf": [ { "type": "object", "required": [ "base", "quote" ], "properties": { "base": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapAssetAmount" }, "quote": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapAssetAmount" } } }, { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapThreshold" } ] }, "Webhooks_PriceTriggerSwapRequestedTrade": { "title": "PriceTriggerSwapRequestedTrade", "description": "Requested source and destination assets for a scheduled swap.", "type": "object", "required": [ "from", "to" ], "properties": { "from": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapAssetAmount" }, "to": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapAssetAmount" } } }, "Webhooks_PriceTriggerSwapRequested": { "title": "PriceTriggerSwapRequested", "description": "Requested trade and trigger condition for a price-trigger swap.", "type": "object", "required": [ "trade", "when" ], "properties": { "trade": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapRequestedTrade" }, "when": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapWhen" } } }, "Webhooks_PriceTriggerSwapExecutedDetails": { "title": "PriceTriggerSwapExecutedDetails", "description": "Realized fill details for a successful scheduled swap occurrence.", "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "description": "Public quote identifier for the executed fill.", "type": "string" }, "from": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapAssetAmount" }, "to": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapAssetAmount" }, "fee": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapAssetAmount" }, "rate": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapAssetAmount" }, "executed_at": { "description": "Time at which the swap was executed.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_PriceTriggerSwapFailureReason": { "title": "PriceTriggerSwapFailureReason", "description": "Partner-safe reason for a failed execution attempt or terminal swap failure. Scheduler reasons that are internal implementation details are normalized to `other`.", "type": "string", "enum": [ "system_error", "insufficient_market_liquidity", "insufficient_funds", "user_locked", "user_request", "other" ] }, "Webhooks_PriceTriggerSwapExecutedPayload": { "title": "PriceTriggerSwapExecutedPayload", "description": "Payload delivered for the `price_trigger_swap.executed` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp", "requested" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "price_trigger_swap.executed" }, "id": { "description": "Scheduled-action / price-trigger-swap identifier.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" }, "requested": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapRequested" }, "executed": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapExecutedDetails" } } }, "Webhooks_PriceTriggerSwapExecutionFailedPayload": { "title": "PriceTriggerSwapExecutionFailedPayload", "description": "Payload delivered for the `price_trigger_swap.execution_failed` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "price_trigger_swap.execution_failed" }, "id": { "description": "Scheduled-action / price-trigger-swap identifier.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" }, "failure_reason": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapFailureReason" } } }, "Webhooks_PriceTriggerSwapCancelledPayload": { "title": "PriceTriggerSwapCancelledPayload", "description": "Payload delivered for the `price_trigger_swap.cancelled` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "price_trigger_swap.cancelled" }, "id": { "description": "Scheduled-action / price-trigger-swap identifier.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_PriceTriggerSwapCreatedPayload": { "title": "PriceTriggerSwapCreatedPayload", "description": "Payload delivered for the `price_trigger_swap.created` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp", "requested" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "price_trigger_swap.created" }, "id": { "description": "Scheduled-action / price-trigger-swap identifier.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" }, "requested": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapRequested" } } }, "Webhooks_PriceTriggerSwapFailedPayload": { "title": "PriceTriggerSwapFailedPayload", "description": "Payload delivered for the `price_trigger_swap.failed` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp", "failure_reason" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "price_trigger_swap.failed" }, "id": { "description": "Scheduled-action / price-trigger-swap identifier.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" }, "failure_reason": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapFailureReason" } } }, "Webhooks_RecurringSwapFailureReason": { "title": "RecurringSwapFailureReason", "description": "Reason the recurring swap stopped permanently. An expired payment method is delivered as `other`.", "type": "string", "enum": [ "user_locked", "asset_unavailable", "pair_unavailable", "retries_exhausted", "funding_method_deleted", "other" ] }, "Webhooks_RecurringSwapInterval": { "title": "RecurringSwapInterval", "description": "Cadence on which the recurring swap submits its trade.", "type": "string", "enum": [ "day", "week", "two_weeks", "month", "quarter", "year" ] }, "Webhooks_RecurringSwapSchedule": { "title": "RecurringSwapSchedule", "description": "Schedule that determines when each recurring swap occurrence is submitted. The fixed UTC offset does not adjust for daylight saving time.", "type": "object", "required": [ "interval", "timezone_offset_minutes" ], "properties": { "interval": { "description": "Cadence of the scheduled trade.", "$ref": "#/components/schemas/Webhooks_RecurringSwapInterval" }, "starts_at": { "description": "Time requested for the first occurrence. Omission means the first occurrence was requested immediately.", "$ref": "#/components/schemas/DateTime" }, "timezone_offset_minutes": { "description": "Offset from UTC used to anchor the schedule.", "type": "integer", "format": "int32", "minimum": -720, "maximum": 900 } } }, "Webhooks_RecurringSwapCreatedPayload": { "title": "RecurringSwapCreatedPayload", "description": "Payload delivered for the `recurring_swap.created` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp", "trade", "schedule" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "recurring_swap.created" }, "id": { "description": "Identifier of the recurring swap whose lifecycle changed.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" }, "trade": { "description": "Source and destination assets for each occurrence.", "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapRequestedTrade" }, "schedule": { "description": "Cadence on which the trade is submitted.", "$ref": "#/components/schemas/Webhooks_RecurringSwapSchedule" } } }, "Webhooks_RecurringSwapExecutedPayload": { "title": "RecurringSwapExecutedPayload", "description": "Payload delivered for the `recurring_swap.executed` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp", "trade", "schedule", "occurrence_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "recurring_swap.executed" }, "id": { "description": "Identifier of the recurring swap whose lifecycle changed.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" }, "trade": { "description": "Source and destination assets for each occurrence.", "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapRequestedTrade" }, "schedule": { "description": "Cadence on which the trade is submitted.", "$ref": "#/components/schemas/Webhooks_RecurringSwapSchedule" }, "executed": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapExecutedDetails" }, "occurrence_id": { "description": "Identifier of the scheduled occurrence. Use it with the recurring swap identifier to correlate execution outcomes.", "type": "string", "minLength": 1 } } }, "Webhooks_RecurringSwapExecutionFailedPayload": { "title": "RecurringSwapExecutionFailedPayload", "description": "Payload delivered for the `recurring_swap.execution_failed` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp", "occurrence_id" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "recurring_swap.execution_failed" }, "id": { "description": "Identifier of the recurring swap whose lifecycle changed.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" }, "failure_reason": { "$ref": "#/components/schemas/Webhooks_PriceTriggerSwapFailureReason" }, "occurrence_id": { "description": "Identifier of the scheduled occurrence. Use it with the recurring swap identifier to correlate execution outcomes.", "type": "string", "minLength": 1 } } }, "Webhooks_RecurringSwapCancelledPayload": { "title": "RecurringSwapCancelledPayload", "description": "Payload delivered for the `recurring_swap.cancelled` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "recurring_swap.cancelled" }, "id": { "description": "Identifier of the recurring swap whose lifecycle changed.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_RecurringSwapFailedPayload": { "title": "RecurringSwapFailedPayload", "description": "Payload delivered for the `recurring_swap.failed` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp", "failure_reason" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "recurring_swap.failed" }, "id": { "description": "Identifier of the recurring swap whose lifecycle changed.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" }, "failure_reason": { "$ref": "#/components/schemas/Webhooks_RecurringSwapFailureReason" } } }, "Webhooks_RecurringSwapPausedPayload": { "title": "RecurringSwapPausedPayload", "description": "Payload delivered for the `recurring_swap.paused` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "recurring_swap.paused" }, "id": { "description": "Identifier of the recurring swap whose lifecycle changed.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_RecurringSwapResumedPayload": { "title": "RecurringSwapResumedPayload", "description": "Payload delivered for the `recurring_swap.resumed` webhook event.", "type": "object", "required": [ "type", "id", "user_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "recurring_swap.resumed" }, "id": { "description": "Identifier of the recurring swap whose lifecycle changed.", "type": "string" }, "client_order_id": { "description": "Partner-supplied order identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "timestamp": { "description": "Time at which the lifecycle transition occurred.", "$ref": "#/components/schemas/DateTime" } } }, "Webhooks_TransactionRecurringSwapPayload": { "title": "TransactionRecurringSwapPayload", "description": "Payload delivered when a recurring swap portfolio transaction changes.", "type": "object", "required": [ "type", "transaction_id", "user_id", "account_id", "timestamp" ], "properties": { "type": { "description": "Webhook event identifier.", "type": "string", "const": "transaction.recurring_swap" }, "transaction_id": { "description": "Public transaction identifier.", "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" }, "account_id": { "$ref": "#/components/schemas/AccountId" }, "timestamp": { "description": "Time at which the event was observed.", "$ref": "#/components/schemas/DateTime" }, "status": { "description": "Current public portfolio transaction status.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionStatus" }, "spend": { "description": "Asset spent by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "receive": { "description": "Asset received by this transaction.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionAmount" }, "details": { "description": "Swap-specific transaction details.", "$ref": "#/components/schemas/Webhooks_PortfolioTransactionSwapDetails" } } }, "Webhooks_WebhookNotFoundError": { "description": "The requested webhook does not exist or is not accessible.", "allOf": [ { "$ref": "#/components/schemas/PwsGeneralErrorEnvelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/PwsGeneralError" }, { "type": "object", "required": [ "status", "code" ], "properties": { "status": { "type": "integer", "format": "int32", "const": 404 }, "code": { "type": "string", "enum": [ "webhook_not_found" ] } } } ] } } } ] } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "API-Key", "description": "Your public API key. Identifies the partner making the request." }, "ApiTimestamp": { "type": "apiKey", "in": "header", "name": "API-Timestamp", "description": "Time the request was signed, as Unix milliseconds. Included in the request signature. Requests signed too far from the server's time are rejected." }, "ApiSign": { "type": "apiKey", "in": "header", "name": "API-Sign", "description": "HMAC signature over the request, computed with your private key." } }, "responses": { "ConversionsBadRequestResponse": { "description": "Validation error.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/conversions-bad-request" } } } } }, "ConversionsInvalidWithdrawalAddressResponse": { "description": "Request validation failed or the withdrawal destination is invalid.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Bad Request", "$ref": "#/components/schemas/BadRequestError" }, { "title": "Invalid withdrawal address", "$ref": "#/components/schemas/Conversions_ConversionInvalidWithdrawalAddressErrorResponse" } ] }, "examples": { "invalid-request": { "$ref": "#/components/examples/conversions-bad-request" }, "invalid-withdrawal-address": { "$ref": "#/components/examples/conversions-invalid-withdrawal-address" } } } } }, "ConversionsUnauthenticatedResponse": { "description": "Authentication required.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/conversions-unauthenticated" } } } } }, "ConversionsForbiddenResponse": { "description": "Forbidden.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/conversions-forbidden" } } } } }, "ConversionsNotFoundResponse": { "description": "The requested conversion resource was not found.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversions_ConversionsNotFoundErrorResponse" }, "examples": { "conversion-resource-not-found": { "$ref": "#/components/examples/conversions-not-found" } } } } }, "ConversionsOnDemandConflictResponse": { "description": "The conversion cannot be created with the supplied account state, destination wallet address, or idempotency key.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Idempotency key already used", "$ref": "#/components/schemas/Conversions_OnDemandConversionIdempotencyKeyAlreadyUsedError" }, { "title": "Insufficient funds", "$ref": "#/components/schemas/Conversions_ConversionInsufficientFundsErrorResponse" }, { "title": "Address ownership verification required", "$ref": "#/components/schemas/Conversions_ConversionAddressOwnershipVerificationRequiredErrorResponse" }, { "title": "Withdrawal method unavailable", "$ref": "#/components/schemas/Conversions_ConversionWithdrawalMethodUnavailableErrorResponse" } ] }, "examples": { "idempotency-key-already-used": { "$ref": "#/components/examples/conversions-idempotency-key-already-used" }, "insufficient-funds": { "$ref": "#/components/examples/conversions-insufficient-funds" }, "address-ownership-verification-required": { "$ref": "#/components/examples/conversions-address-ownership-verification-required" }, "withdrawal-method-unavailable": { "$ref": "#/components/examples/conversions-withdrawal-method-unavailable" } } } } }, "ConversionsOnDemandPrepareConflictResponse": { "description": "The conversion cannot be prepared with the supplied account state, destination wallet address, or idempotency key.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Idempotency key already used", "$ref": "#/components/schemas/Conversions_OnDemandConversionIdempotencyKeyAlreadyUsedError" }, { "title": "Insufficient funds", "$ref": "#/components/schemas/Conversions_ConversionInsufficientFundsErrorResponse" }, { "title": "Address ownership verification required", "$ref": "#/components/schemas/Conversions_ConversionAddressOwnershipVerificationRequiredErrorResponse" }, { "title": "Withdrawal method unavailable", "$ref": "#/components/schemas/Conversions_ConversionWithdrawalMethodUnavailableErrorResponse" }, { "title": "Prepare limit reached", "$ref": "#/components/schemas/Conversions_OnDemandConversionPrepareLimitReachedError" } ] }, "examples": { "idempotency-key-already-used": { "$ref": "#/components/examples/conversions-idempotency-key-already-used" }, "insufficient-funds": { "$ref": "#/components/examples/conversions-insufficient-funds" }, "address-ownership-verification-required": { "$ref": "#/components/examples/conversions-address-ownership-verification-required" }, "withdrawal-method-unavailable": { "$ref": "#/components/examples/conversions-withdrawal-method-unavailable" }, "prepare-limit-reached": { "$ref": "#/components/examples/conversions-on-demand-prepare-limit-reached" } } } } }, "ConversionsOnDemandExecuteConflictResponse": { "description": "The conversion cannot be executed with its current status, the account state, the destination wallet address, or the supplied idempotency key.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Idempotency key already used", "$ref": "#/components/schemas/Conversions_OnDemandConversionIdempotencyKeyAlreadyUsedError" }, { "title": "Insufficient funds", "$ref": "#/components/schemas/Conversions_ConversionInsufficientFundsErrorResponse" }, { "title": "Address ownership verification required", "$ref": "#/components/schemas/Conversions_ConversionAddressOwnershipVerificationRequiredErrorResponse" }, { "title": "Already executed", "$ref": "#/components/schemas/Conversions_OnDemandConversionAlreadyExecutedError" } ] }, "examples": { "idempotency-key-already-used": { "$ref": "#/components/examples/conversions-idempotency-key-already-used" }, "insufficient-funds": { "$ref": "#/components/examples/conversions-insufficient-funds" }, "address-ownership-verification-required": { "$ref": "#/components/examples/conversions-address-ownership-verification-required" }, "already-executed": { "$ref": "#/components/examples/conversions-on-demand-already-executed" } } } } }, "ConversionsOnDemandCanceledResponse": { "description": "The prepared conversion was canceled or its price lock expired.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversions_OnDemandConversionCanceledError" }, "examples": { "canceled": { "$ref": "#/components/examples/conversions-on-demand-canceled" } } } } }, "ConversionsConversionLimitReachedResponse": { "description": "The maximum number of conversion rules was reached.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversions_ConversionLimitReachedErrorResponse" }, "examples": { "conversion-limit-reached": { "$ref": "#/components/examples/conversions-conversion-limit-reached" } } } } }, "ConversionsRuleAlreadyDeletedResponse": { "description": "The conversion rule was already deleted.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversions_RuleAlreadyDeletedErrorResponse" }, "examples": { "rule-already-deleted": { "$ref": "#/components/examples/conversions-rule-already-deleted" } } } } }, "ConversionsResourceExhaustedResponse": { "description": "Rate limit exceeded.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/conversions-resource-exhausted" } } } } }, "ConversionsInternalResponse": { "description": "Internal server error.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/conversions-internal" } } } } }, "ConversionsUnimplementedResponse": { "description": "Operation not implemented.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "operation-not-implemented": { "$ref": "#/components/examples/conversions-unimplemented" } } } } }, "ConversionsUnavailableResponse": { "description": "Service unavailable.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/conversions-unavailable" } } } } }, "ConversionsDeadlineExceededResponse": { "description": "Request deadline exceeded.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/conversions-deadline-exceeded" } } } } }, "EarnBadRequestResponse": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/earn-bad-request" } } } } }, "EarnSetPreferencesForbiddenResponse": { "description": "Permission denied or account not eligible", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Forbidden", "$ref": "#/components/schemas/ForbiddenError" }, { "title": "Account not eligible", "$ref": "#/components/schemas/AutoEarn_NotEligibleError" } ] }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/earn-forbidden" }, "not-eligible": { "$ref": "#/components/examples/earn-not-eligible" } } } } }, "EarnUnauthenticatedResponse": { "description": "Authentication failed", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/earn-unauthenticated" } } } } }, "EarnForbiddenResponse": { "description": "Permission denied", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/earn-forbidden" } } } } }, "BondedEarnWriteForbiddenResponse": { "description": "The account is not eligible for the strategy (`forbidden`), or the API gateway rejected the request (`gateway`). Branch on `error.code`.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "not-eligible": { "$ref": "#/components/examples/earn-forbidden" } } } } }, "EarnResourceExhaustedResponse": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/earn-resource-exhausted" } } } } }, "EarnInternalResponse": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/earn-internal" } } } } }, "EarnUnavailableResponse": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/earn-service-unavailable" } } } } }, "EarnDeadlineExceededResponse": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/earn-deadline-exceeded" } } } } }, "BondedEarnNotFoundResponse": { "description": "The strategy or request does not exist, or is not available to the account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/bonded-earn-not-found" } } } } }, "BondedEarnNotEnabledResponse": { "description": "Bonded earn is not enabled.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "$ref": "#/components/examples/bonded-earn-not-enabled" } } } } }, "BondedEarnAllocateBadRequestResponse": { "description": "The request was rejected. Branch on `error.code`.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Bad request", "$ref": "#/components/schemas/BadRequestError" }, { "title": "Amount too high", "$ref": "#/components/schemas/BondedEarn_AmountTooHighError" } ] }, "examples": { "invalid-request": { "$ref": "#/components/examples/earn-bad-request" }, "amount-too-high": { "$ref": "#/components/examples/bonded-earn-amount-too-high" } } } } }, "BondedEarnDeallocateBadRequestResponse": { "description": "The request was rejected. Branch on `error.code`.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Bad request", "$ref": "#/components/schemas/BadRequestError" }, { "title": "Insufficient balance", "$ref": "#/components/schemas/BondedEarn_InsufficientBalanceError" }, { "title": "Amount too high", "$ref": "#/components/schemas/BondedEarn_AmountTooHighError" } ] }, "examples": { "invalid-request": { "$ref": "#/components/examples/earn-bad-request" }, "insufficient-balance": { "$ref": "#/components/examples/bonded-earn-insufficient-balance" }, "amount-too-high": { "$ref": "#/components/examples/bonded-earn-amount-too-high" } } } } }, "BondedEarnWriteNotFoundResponse": { "description": "The strategy does not exist. Branch on `error.code`.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Not found", "$ref": "#/components/schemas/NotFoundError" }, { "title": "Strategy not found", "$ref": "#/components/schemas/BondedEarn_StrategyNotFoundError" } ] }, "examples": { "strategy-not-found": { "$ref": "#/components/examples/bonded-earn-strategy-not-found" } } } } }, "BondedEarnConflictResponse": { "description": "The request conflicts with a request that was already recorded or is still running. Branch on `error.code`.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Request conflict", "$ref": "#/components/schemas/BondedEarn_RequestConflictError" }, { "title": "Idempotency key reused", "$ref": "#/components/schemas/BondedEarn_IdempotencyKeyReusedError" }, { "title": "Allocation in progress", "$ref": "#/components/schemas/BondedEarn_AllocationInProgressError" } ] }, "examples": { "idempotency-key-reused": { "$ref": "#/components/examples/bonded-earn-idempotency-key-reused" }, "allocation-in-progress": { "$ref": "#/components/examples/bonded-earn-allocation-in-progress" }, "request-conflict": { "$ref": "#/components/examples/bonded-earn-request-conflict" } } } } }, "FundingBadRequestResponse": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/funding-bad-request" } } } } }, "FundingCreateAddressBadRequestResponse": { "description": "The request is invalid.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-scope": { "$ref": "#/components/examples/funding-create-address-invalid-scope" }, "invalid-address-details": { "$ref": "#/components/examples/funding-create-address-invalid-details" }, "invalid-name": { "$ref": "#/components/examples/funding-create-address-invalid-name" } } } } }, "FundingUpdateAddressBadRequestResponse": { "description": "The request is invalid, or account settings temporarily prevent funding-address changes.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-name": { "$ref": "#/components/examples/funding-update-address-invalid-name" }, "account-settings": { "$ref": "#/components/examples/funding-update-address-account-settings" } } } } }, "FundingTransferBadRequestResponse": { "description": "Request validation failed or the transfer could not be processed. The request is validated before its idempotency key is compared with a recorded request. A rejection before the key is recorded may leave it available for another request.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-transfer": { "$ref": "#/components/examples/funding-invalid-transfer" }, "self-transfer": { "$ref": "#/components/examples/funding-self-transfer" }, "unsupported-asset": { "$ref": "#/components/examples/funding-unsupported-asset" }, "insufficient-balance": { "$ref": "#/components/examples/funding-insufficient-balance" } } } } }, "FundingDerivativesTransferBadRequestResponse": { "description": "Request validation failed or the derivatives transfer could not be processed.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "amount-too-small": { "$ref": "#/components/examples/funding-derivative-transfer-amount-too-small" }, "unsupported-asset": { "$ref": "#/components/examples/funding-derivative-transfer-unsupported-asset" }, "insufficient-balance": { "$ref": "#/components/examples/funding-derivative-transfer-insufficient-balance" }, "insufficient-futures-balance": { "$ref": "#/components/examples/funding-derivative-transfer-insufficient-futures-balance" }, "futures-unavailable": { "$ref": "#/components/examples/funding-derivative-transfer-futures-unavailable" }, "transfer-rejected": { "$ref": "#/components/examples/funding-derivative-transfer-rejected" }, "invalid-direction": { "$ref": "#/components/examples/funding-derivative-transfer-invalid-direction" } } } } }, "FundingDerivativesTransferNotFoundResponse": { "description": "The selected account does not exist or cannot be selected by the authenticated caller.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "derivatives-transfer-account-not-found": { "$ref": "#/components/examples/funding-derivative-transfer-account-not-found" } } } } }, "FundingDepositActivationBadRequestResponse": { "description": "Request validation failed or the selected account or method cannot be activated.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-method-id": { "$ref": "#/components/examples/funding-deposit-activation-invalid-method-id" }, "insufficient-documentation": { "$ref": "#/components/examples/funding-deposit-activation-insufficient-documentation" } } } } }, "FundingLightningInvoiceBadRequestResponse": { "description": "Request validation failed or an invoice cannot be created for the requested asset and amount.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/funding-bad-request" }, "amount-too-small": { "$ref": "#/components/examples/funding-lightning-amount-too-small" }, "amount-too-large": { "$ref": "#/components/examples/funding-lightning-amount-too-large" }, "unsupported-asset": { "$ref": "#/components/examples/funding-lightning-unsupported-asset" } } } } }, "FundingWithdrawalBadRequestResponse": { "description": "Request validation failed or the withdrawal could not be created for the requested method, address, asset, or amount.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/funding-withdrawal-invalid-amount" }, "insufficient-funds": { "$ref": "#/components/examples/funding-withdrawal-insufficient-funds" }, "amount-too-small": { "$ref": "#/components/examples/funding-withdrawal-amount-too-small" }, "incompatible-address": { "$ref": "#/components/examples/funding-withdrawal-incompatible-address" }, "unsupported-asset": { "$ref": "#/components/examples/funding-withdrawal-unsupported-asset" }, "invalid-fee-token": { "$ref": "#/components/examples/funding-withdrawal-invalid-fee-token" }, "fee-token-network-scope": { "$ref": "#/components/examples/funding-withdrawal-fee-token-network-scope" } } } } }, "FundingWithdrawalFeeQuoteBadRequestResponse": { "description": "Request validation failed or a fee quote could not be created for the requested funding method and amount.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-method-id": { "$ref": "#/components/examples/funding-withdrawal-fee-quote-invalid-method" }, "invalid-amount": { "$ref": "#/components/examples/funding-withdrawal-fee-quote-invalid-amount" } } } } }, "FundingUnauthenticatedResponse": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/funding-unauthenticated" } } } } }, "FundingForbiddenResponse": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/funding-forbidden" } } } } }, "FundingUpdateAddressForbiddenResponse": { "description": "The caller is not allowed to update the funding address, or the address is read-only.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/funding-forbidden" }, "address-read-only": { "$ref": "#/components/examples/funding-update-address-read-only" } } } } }, "FundingNotFoundResponse": { "description": "The funding address does not exist or is not available to the selected account.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "funding-address-not-found": { "$ref": "#/components/examples/funding-not-found" } } } } }, "FundingResourceExhaustedResponse": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/funding-resource-exhausted" } } } } }, "FundingInternalResponse": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/funding-internal" } } } } }, "FundingUnimplementedResponse": { "description": "Operation not implemented", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "operation-not-implemented": { "$ref": "#/components/examples/funding-unimplemented" } } } } }, "FundingUnavailableResponse": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/funding-unavailable" } } } } }, "FundingDeadlineExceededResponse": { "description": "Request deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/funding-deadline-exceeded" } } } } }, "RampBadRequestResponse": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "bad-request": { "value": { "error": { "type": "validation_error", "status": 400, "instance": "req_123", "code": "bad_request" } } } } } } }, "RampUnauthenticatedResponse": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "unauthenticated": { "value": { "error": { "type": "authentication_error", "status": 401, "instance": "req_123", "code": "unauthenticated" } } } } } } }, "RampForbiddenResponse": { "description": "Forbidden", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "error": { "type": "authorization_error", "status": 403, "instance": "req_123", "code": "forbidden" } } } } } } }, "RampResourceExhaustedResponse": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "resource-exhausted": { "value": { "error": { "type": "rate_limit_error", "status": 429, "instance": "req_123", "code": "resource_exhausted" } } } } } } }, "RampInternalResponse": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "value": { "error": { "type": "internal_error", "status": 500, "instance": "req_123", "code": "internal" } } } } } } }, "RampUnimplementedResponse": { "description": "Not implemented", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "unimplemented": { "value": { "error": { "type": "api_error", "status": 501, "instance": "req_123", "code": "unimplemented" } } } } } } }, "RampUnavailableResponse": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "unavailable": { "value": { "error": { "type": "service_error", "status": 503, "instance": "req_123", "code": "unavailable" } } } } } } }, "RampDeadlineExceededResponse": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "deadline-exceeded": { "value": { "error": { "type": "service_error", "status": 504, "instance": "req_123", "code": "deadline_exceeded" } } } } } } }, "RampBankLinkNotFoundResponse": { "description": "Not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ramp_BankLinkNotFoundError" }, "examples": { "bank-link-not-found": { "value": { "error": { "type": "not_found_error", "status": 404, "instance": "req_123", "code": "bank_link_not_found" } } } } } } }, "RampBankLinkActivationRestartRequiredResponse": { "description": "Conflict: this Bank Link cannot continue and cannot be reconnected. Create a new Bank Link and send the customer through the hosted widget again.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ramp_BankLinkActivationRestartRequiredError" }, "examples": { "bank-link-activation-restart-required": { "value": { "error": { "type": "conflict_error", "status": 409, "instance": "req_123", "code": "bank_link_activation_restart_required" } } } } } } }, "RampNotFoundResponse": { "description": "Not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not-found": { "value": { "error": { "type": "not_found_error", "status": 404, "instance": "req_123", "code": "not_found" } } } } } } }, "RampBankLinkMethodNotLinkableBadRequestResponse": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Bad request", "$ref": "#/components/schemas/BadRequestError" }, { "title": "Bank Link method not linkable", "$ref": "#/components/schemas/Ramp_BankLinkMethodNotLinkableError" } ] }, "examples": { "bad-request": { "value": { "error": { "type": "validation_error", "status": 400, "instance": "req_123", "code": "bad_request" } } }, "bank-link-method-not-linkable": { "value": { "error": { "type": "validation_error", "status": 400, "instance": "req_123", "code": "bank_link_method_not_linkable" } } } } } } }, "RampUnlinkProviderRejectedResponse": { "description": "Conflict: the provider refused to sever the connection (for example, transactions are still settling). The Bank Link is not unlinked and keeps its current status; retry the unlink once the condition clears.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ramp_BankLinkProviderRejectedError" }, "examples": { "bank-link-provider-rejected": { "value": { "error": { "type": "conflict_error", "status": 409, "instance": "req_123", "code": "bank_link_provider_rejected" } } } } } } }, "ReportsBadRequestResponse": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/reports-bad-request" } } } } }, "ReportsUnauthenticatedResponse": { "description": "Authentication failed", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/reports-unauthenticated" } } } } }, "ReportsForbiddenResponse": { "description": "Permission denied", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/reports-forbidden" } } } } }, "ReportsResourceExhaustedResponse": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/reports-resource-exhausted" } } } } }, "ReportsInternalResponse": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/reports-internal" } } } } }, "ReportsUnimplementedResponse": { "description": "Operation not implemented", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "operation-not-implemented": { "$ref": "#/components/examples/reports-unimplemented" } } } } }, "ReportsUnavailableResponse": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/reports-service-unavailable" } } } } }, "ReportsDeadlineExceededResponse": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/reports-deadline-exceeded" } } } } }, "SwapQuoteBadRequestResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/swap-quote-bad-request" } } } } }, "SwapOnchainQuoteBadRequestResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/swap-onchain-quote-bad-request" } } } } }, "SwapPriceTriggerSwapBadRequestResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/swap-price-trigger-swap-bad-request" } } } } }, "SwapQuoteUnauthenticatedResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/swap-quote-unauthenticated" } } } } }, "SwapOnchainQuoteUnauthenticatedResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/swap-onchain-quote-unauthenticated" } } } } }, "SwapPriceTriggerSwapUnauthenticatedResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/swap-price-trigger-swap-unauthenticated" } } } } }, "SwapQuoteForbiddenResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/swap-quote-forbidden" } } } } }, "SwapOnchainQuoteForbiddenResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/swap-onchain-quote-forbidden" } } } } }, "SwapPriceTriggerSwapForbiddenResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/swap-price-trigger-swap-forbidden" } } } } }, "SwapQuoteResourceExhaustedResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/swap-quote-resource-exhausted" } } } } }, "SwapOnchainQuoteResourceExhaustedResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/swap-onchain-quote-resource-exhausted" } } } } }, "SwapPriceTriggerSwapResourceExhaustedResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/swap-price-trigger-swap-resource-exhausted" } } } } }, "SwapQuoteInternalResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/swap-quote-internal" } } } } }, "SwapOnchainQuoteInternalResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/swap-onchain-quote-internal" } } } } }, "SwapPriceTriggerSwapInternalResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/swap-price-trigger-swap-internal" } } } } }, "SwapQuoteUnavailableResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/swap-quote-service-unavailable" } } } } }, "SwapOnchainQuoteUnavailableResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/swap-onchain-quote-service-unavailable" } } } } }, "SwapPriceTriggerSwapUnavailableResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/swap-price-trigger-swap-service-unavailable" } } } } }, "SwapQuoteDeadlineExceededResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/swap-quote-deadline-exceeded" } } } } }, "SwapOnchainQuoteDeadlineExceededResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/swap-onchain-quote-deadline-exceeded" } } } } }, "SwapPriceTriggerSwapDeadlineExceededResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/swap-price-trigger-swap-deadline-exceeded" } } } } }, "TravelRuleBadRequestResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/travel-rule-bad-request" } } } } }, "TravelRuleUnauthenticatedResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/travel-rule-unauthenticated" } } } } }, "TravelRuleForbiddenResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/travel-rule-forbidden" } } } } }, "TravelRuleResourceExhaustedResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/travel-rule-resource-exhausted" } } } } }, "TravelRuleInternalResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/travel-rule-internal" } } } } }, "TravelRuleUnavailableResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/travel-rule-unavailable" } } } } }, "TravelRuleDeadlineExceededResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/travel-rule-deadline-exceeded" } } } } }, "TravelRuleVerificationNotFoundResponse": { "description": "", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleVerifications_VerificationNotFoundError" }, "examples": { "verification-not-found": { "$ref": "#/components/examples/travel-rule-verification-not-found" } } } } }, "TravelRuleVerificationConflictResponse": { "description": "The verification conflicts with the current Travel Rule state.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Wallet type mismatch", "$ref": "#/components/schemas/TravelRuleVerifications_WalletTypeMismatchError" }, { "title": "Verification not enabled", "$ref": "#/components/schemas/TravelRuleVerifications_VerificationNotEnabledError" }, { "title": "Satoshi test required", "$ref": "#/components/schemas/TravelRuleVerifications_SatoshiTestRequiredError" }, { "title": "Verification rejected", "$ref": "#/components/schemas/TravelRuleVerifications_VerificationRejectedError" } ] }, "examples": { "wallet-type-mismatch": { "$ref": "#/components/examples/travel-rule-wallet-type-mismatch" }, "verification-not-enabled": { "$ref": "#/components/examples/travel-rule-verification-not-enabled" }, "satoshi-test-required": { "$ref": "#/components/examples/travel-rule-satoshi-test-required" }, "verification-rejected": { "$ref": "#/components/examples/travel-rule-verification-rejected" } } } } }, "UsersBadRequestResponse": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/users-bad-request" } } } } }, "UsersUnauthenticatedResponse": { "description": "Authentication failed", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/users-unauthenticated" } } } } }, "UsersForbiddenResponse": { "description": "Permission denied", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/users-forbidden" } } } } }, "UsersResourceExhaustedResponse": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/users-resource-exhausted" } } } } }, "UsersInternalResponse": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/users-internal" } } } } }, "UsersUnavailableResponse": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/users-service-unavailable" } } } } }, "UsersDeadlineExceededResponse": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/users-deadline-exceeded" } } } } }, "VerificationsBadRequestResponse": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "bad-request": { "value": { "error": { "type": "validation_error", "status": 400, "instance": "req_123", "code": "bad_request" } } } } } } }, "VerificationsUnauthenticatedResponse": { "description": "Authentication required", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "unauthenticated": { "value": { "error": { "type": "authentication_error", "status": 401, "instance": "req_123", "code": "unauthenticated" } } } } } } }, "VerificationsForbiddenResponse": { "description": "The API gateway rejected the request (`gateway`), for example because `user_id` doesn't identify one of your users, or the service refused the operation (`forbidden`). Branch on `error.code`.", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "error": { "type": "authorization_error", "status": 403, "instance": "req_123", "code": "forbidden" } } }, "unknown-user": { "summary": "The user ID doesn't identify one of your users", "value": { "error": { "type": "service_error", "status": 403, "instance": "req_123", "code": "gateway" } } } } } } }, "VerificationsResourceExhaustedResponse": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "resource-exhausted": { "value": { "error": { "type": "rate_limit_error", "status": 429, "instance": "req_123", "code": "resource_exhausted" } } } } } } }, "VerificationsInternalResponse": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "value": { "error": { "type": "internal_error", "status": 500, "instance": "req_123", "code": "internal" } } } } } } }, "VerificationsUnimplementedResponse": { "description": "Error response", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnimplementedError" }, "examples": { "unimplemented": { "value": { "error": { "type": "api_error", "status": 501, "instance": "req_123", "code": "unimplemented" } } } } } } }, "VerificationsUnavailableResponse": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "unavailable": { "value": { "error": { "type": "service_error", "status": 503, "instance": "req_123", "code": "unavailable" } } } } } } }, "VerificationsDeadlineExceededResponse": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "deadline-exceeded": { "value": { "error": { "type": "service_error", "status": 504, "instance": "req_123", "code": "deadline_exceeded" } } } } } } }, "VerificationsVerificationRequirementsNotFoundResponse": { "description": "Verification requirements not found", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verifications_VerificationRequirementsNotFoundError" }, "examples": { "verification-requirements-not-found": { "value": { "error": { "type": "verifications_error", "status": 404, "instance": "req_123", "code": "verification_requirements_not_found" } } } } } } }, "WebhooksBadRequestResponse": { "description": "Validation error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" }, "examples": { "invalid-request": { "$ref": "#/components/examples/webhooks-bad-request" } } } } }, "WebhooksUnauthenticatedResponse": { "description": "Authentication failed", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedError" }, "examples": { "authentication-failed": { "$ref": "#/components/examples/webhooks-unauthenticated" } } } } }, "WebhooksForbiddenResponse": { "description": "Permission denied", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "caller-is-not-allowed": { "$ref": "#/components/examples/webhooks-forbidden" } } } } }, "WebhooksResourceExhaustedResponse": { "description": "Rate limit exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedError" }, "examples": { "rate-limit-exceeded": { "$ref": "#/components/examples/webhooks-resource-exhausted" } } } } }, "WebhooksInternalResponse": { "description": "Internal server error", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" }, "examples": { "internal-error": { "$ref": "#/components/examples/webhooks-internal" } } } } }, "WebhooksUnavailableResponse": { "description": "Service unavailable", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" }, "examples": { "service-unavailable": { "$ref": "#/components/examples/webhooks-service-unavailable" } } } } }, "WebhooksDeadlineExceededResponse": { "description": "Deadline exceeded", "headers": { "X-Trace-Id": { "$ref": "#/components/headers/TraceId" }, "Strict-Transport-Security": { "$ref": "#/components/headers/StrictTransportSecurity" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineExceededError" }, "examples": { "request-deadline-exceeded": { "$ref": "#/components/examples/webhooks-deadline-exceeded" } } } } } } }, "x-tagGroups": [ { "name": "PWS Assets API", "tags": [ "Assets" ] }, { "name": "PWS Conversions API", "tags": [ "Conversions" ] }, { "name": "PWS Earn API", "tags": [ "Auto Earn", "Bonded Earn" ] }, { "name": "PWS Funding API", "tags": [ "Funding", "Derivative transfers" ] }, { "name": "PWS Portfolio API", "tags": [ "Portfolio" ] }, { "name": "PWS Ramp API", "tags": [ "Ramp" ] }, { "name": "PWS Reports API", "tags": [ "Reports" ] }, { "name": "PWS Swap API", "tags": [ "Swaps", "Onchain quotes", "Price trigger swaps" ] }, { "name": "PWS Travel Rule API", "tags": [ "Travel Rule verifications" ] }, { "name": "PWS Users API", "tags": [ "Users" ] }, { "name": "PWS Verifications API", "tags": [ "Verifications" ] }, { "name": "PWS Webhooks API", "tags": [ "Webhooks" ] } ] }