{"openapi":"3.1.0","info":{"title":"uSwap Partner API","version":"1.0.0","description":"SDK-oriented OpenAPI contract for organization API-key and affiliate self-service integrations."},"servers":[{"url":"https://partner-api.uswap.net"}],"tags":[{"name":"Catalog","description":"Discover assets, networks, dynamic product groups, address prompts, and amount bounds. The catalog is the source of truth for `asset_v1` identifiers used in every other endpoint."},{"name":"Quotes","description":"Quotes resolve a source/destination pair into one or more executable route plans. A quote contains a `draft_id` and one or more `plan_id`s; commit one of them by passing the ids back into the intent endpoint."},{"name":"Payments","description":"Payment sessions are checkout-style pay-mode bridges. A partner creates a fixed outbound obligation, users fund the bridge from supported crypto sources, and uSwap creates the final outbound intent only after the collection target is met. Use automatic capture for normal checkout and manual capture for escrow/release flows."},{"name":"Bridges","description":"A bridge is a persistent container holding a canonical destination, ingress endpoints (deposit addresses) and default routing policies. Intents commit specific conversion orders against a bridge."},{"name":"Intents","description":"An intent is a specific conversion order created from a quote. Each intent has matched deposits, executions, deliveries, and per-leg state. Intent destination is immutable after creation."},{"name":"Digital delivery","description":"Digital products can produce protected delivery artifacts such as account credentials and login-code actions. Generic intent delivery rows intentionally omit those secrets; fetch the scoped vault when your integration owns the bridge."},{"name":"Ingress & holds","description":"Some ingress rails require a manual deposit notification, and some deposits land in a `held` state pending partner action. Use these endpoints to push notifications and resolve held deposits."},{"name":"Managed positions","description":"Bridges that route through peer-managed providers or Telegram number rentals expose managed positions: persistent state representing a counterparty agreement or rented asset. The endpoints below let you inspect available actions and sync state."},{"name":"Webhooks","description":"Manage organization webhooks and inspect their delivery history. Webhook secrets are returned only on create and rotation — store them. See the Webhook signature guide for verification."},{"name":"Stats","description":"Aggregate metrics for dashboards and reporting. Use the dedicated `/v1/intents` and `/v1/bridges` endpoints for paginated row access."},{"name":"Affiliates","description":"Organization-scoped creator-code management and affiliate self-service. Organization routes accept either a matching API key or a dashboard session; self-service tokens can never edit split configuration."}],"paths":{"/v1/referrals/resolve":{"post":{"operationId":"resolveReferral","tags":["Affiliates"],"summary":"Resolve creator code","description":"Issues a server-authenticated, TTL-bound referral token for an active creator code. Unknown or inactive codes return a null attribution.","security":[],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string"}},"required":["username"],"additionalProperties":false}}}}}},"/v1/flows":{"get":{"operationId":"getFlows","tags":["Catalog"],"summary":"Flow catalog","description":"Returns a compact, machine-readable index of every flow group and its endpoints. Useful for quick discovery from a script.","security":[{"OrganizationApiKey":["catalog:read"]}],"responses":{"200":{"description":"Index of flow groups and required scopes."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/assets":{"get":{"operationId":"listAssets","tags":["Catalog"],"summary":"List assets","description":"Paginated developer-facing flat list plus grouped categories. Each item is a canonical chain asset usable directly in quote, bridge and intent requests. Fiat destinations are expanded as distinct assets (e.g. `fiat-zelle` → `zelle-citi`, `zelle-chase`). Prepaid cards surface under the Fiat category.","security":[{"OrganizationApiKey":["catalog:read"]}],"parameters":[{"name":"side","in":"query","required":false,"description":"Whether to list source-eligible (`from`) or destination-eligible (`to`) assets.","schema":{"type":"string","enum":["from","to"]}},{"name":"query","in":"query","required":false,"description":"Full-text match across symbol, name and chain id.","schema":{"type":"string"}},{"name":"counterpart_asset_v1","in":"query","required":false,"description":"Filter to assets that can pair with this counterpart.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque token from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"cursor":null,"items":[{"asset_id":"usdc","asset_v1":"asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","symbol":"USDC","name":"USD Coin","category":"Crypto","chain":{"id":"base","name":"Base","image":"/networks/base.svg","address_type":"crypto"},"decimals":6,"networks":[{"asset_v1":"asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","chain_id":"base","chain_name":"Base","chain_image":"/networks/base.svg","decimals":6}]}],"categories":[{"name":"Crypto","items":[]}]}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/assets/lookup":{"post":{"operationId":"assetLookup","tags":["Catalog"],"summary":"Lookup asset metadata","description":"Hydrates up to 250 canonical asset ids. Use this to render stored bridge and intent rows without scanning the full catalog.","security":[{"OrganizationApiKey":["catalog:read"]}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset_v1s":{"type":"array","items":{"type":"string"}}},"required":["asset_v1s"],"additionalProperties":false},"example":{"asset_v1s":["asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"]}}}}}},"/v1/catalog/assets/{asset_v1}/networks":{"get":{"operationId":"assetNetworks","tags":["Catalog"],"summary":"Networks for an asset","description":"Returns every concrete network or dynamic product for an asset. Supports CakePay country/brand groups and Telegram number rentals.","security":[{"OrganizationApiKey":["catalog:read"]}],"parameters":[{"name":"asset_v1","in":"path","required":true,"description":"Canonical asset id.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor for paged dynamic catalogs.","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Filter by network/product text.","schema":{"type":"string"}},{"name":"parent_group_id","in":"query","required":false,"description":"Group id returned by network-groups.","schema":{"type":"string"}},{"name":"group_id","in":"query","required":false,"description":"Nested group id returned by network-groups.","schema":{"type":"string"}},{"name":"paged","in":"query","required":false,"description":"Force pagination for large static catalogs.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/assets/{asset_v1}/network-groups":{"get":{"operationId":"assetNetworkGroups","tags":["Catalog"],"summary":"Network groups for an asset","description":"Returns dynamic grouping layers for picker UIs, such as CakePay countries and brands. When a taxonomy applies (e.g. gift-card brands), every response includes `category_counts` — an ordered `{ id, name, count }[]` giving the exact number of groups per browse category over the full query-filtered set, so a client can render category pills without scanning every page. Pass `category` to page within one category.","security":[{"OrganizationApiKey":["catalog:read"]}],"parameters":[{"name":"asset_v1","in":"path","required":true,"description":"Canonical asset id or catalog asset id.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor. Scoped to `category` when one is supplied; a cursor whose category no longer matches restarts at page 1.","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Filter groups by text.","schema":{"type":"string"}},{"name":"parent_group_id","in":"query","required":false,"description":"Fetch nested groups under a parent.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Page within a single browse category (a `category_counts[].id`). Omit to page the full set and receive per-category totals.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/networks/{chain}/assets":{"get":{"operationId":"networkAssets","tags":["Catalog"],"summary":"Assets on a network","description":"Lists assets supported on the specified chain with amount bounds and display metadata.","security":[{"OrganizationApiKey":["catalog:read"]}],"parameters":[{"name":"chain","in":"path","required":true,"description":"Chain id, e.g. `base`, `bitcoin`, `monero`.","schema":{"type":"string"}},{"name":"bridge_id","in":"query","required":false,"description":"Optional bridge id. Narrows assets to rails actually present on that bridge.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/level":{"post":{"operationId":"catalogLevel","tags":["Catalog"],"summary":"Resolve a catalog level","description":"The unified picker surface. Every screen of every catalog family — the top asset grid, gift-card country → brand → SKU, telegram/discord products, number rentals, fiat rails, plain-crypto networks — is one `level`: a list of `items` where each item is either a selectable `leaf` (carries its own `asset_v1` + chain) or a `drill` node descending one level. Send the level `path` (`asset` plus the `segments` echoed from a parent response's drill `node.segment`), optional `side`, `query`, and `category`, plus the opaque `cursor` from the previous page. The response returns `meta` (title, paging mode, and — when a taxonomy applies — ordered `categories` with exact `category_counts`), the `items`, and the next `cursor` (null when the level is complete). This is the same view the realtime `catalog.level` channel serves; the legacy per-shape catalog endpoints above remain available and unchanged.","security":[{"OrganizationApiKey":["catalog:read"]}],"responses":{"200":{"description":"Level envelope: `meta` (path, title, `search`/`paging`/`layout` modes, and optional `categories` with `category_counts`), an `items` array of leaf and drill entries, and a `cursor` (null when the level is fully paged)."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"object","properties":{"asset":{"anyOf":[{"type":"string"},{"type":"null"}]},"segments":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"id":{"type":"string"},"wire":{"type":"object","properties":{"parent_group_id":{"type":"string"},"group_id":{"type":"string"}},"additionalProperties":false}},"required":["key","id"],"additionalProperties":false}}},"required":["asset","segments"],"additionalProperties":false},"side":{"type":"string","enum":["from","to"]},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"query":{"type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["path"],"additionalProperties":false},"example":{"path":{"asset":"gift-card","segments":[{"key":"country","id":"country-us","wire":{"parent_group_id":"country-us"}}]},"side":"to","category":"Shopping","cursor":null}}}}}},"/v1/quotes":{"post":{"operationId":"createQuote","tags":["Quotes"],"summary":"Create a quote","description":"Plans routes across supported source, conversion, and payout rails. Returns one or more plans.","security":[{"OrganizationApiKey":["catalog:read"]}],"responses":{"200":{"description":"Quote envelope with `draft_id`, an array of `plans` (each with a list of `legs` and one `plan_id`), and route failure reasons when a path can't be priced."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_asset_v1":{"type":"string"},"destination_asset_v1":{"type":"string"},"destination_address":{"type":"string"},"destination_memo":{"anyOf":[{"type":"string"},{"type":"null"}]},"amount":{"type":"string"},"input_side":{"type":"string","enum":["from","to"]},"input_type":{"type":"string","enum":["usd","human","raw"]},"slippage_bps":{"type":"number"},"excluded_provider_ids":{"type":"array","items":{"type":"string"}},"referral_token":{"type":"string"}},"required":["source_asset_v1","destination_asset_v1","amount","input_side"],"additionalProperties":false},"example":{"source_asset_v1":"asset_v1:bitcoin:native:coin","destination_asset_v1":"asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","destination_address":"0xRecipient...","amount":"0.01","input_side":"from","input_type":"human","slippage_bps":100,"excluded_provider_ids":[]}}}}}},"/v1/quotes/{draft_id}/swap-leg":{"post":{"operationId":"swapLeg","tags":["Quotes"],"summary":"Swap a leg's provider","description":"Replace the provider on a specific leg of a planned route without re-quoting from scratch.","security":[{"OrganizationApiKey":["catalog:read"]}],"parameters":[{"name":"draft_id","in":"path","required":true,"description":"Draft id from `POST /v1/quotes`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draft_id":{"type":"string"},"plan_id":{"type":"string"},"route_leg_index":{"type":"number"},"new_provider_id":{"type":"string"}},"required":["draft_id","plan_id","route_leg_index","new_provider_id"],"additionalProperties":false},"example":{"draft_id":"drf_...","plan_id":"pln_...","route_leg_index":0,"new_provider_id":"thorchain"}}}}}},"/v1/bridges/{bridge_id}/quote":{"post":{"operationId":"bridgeQuote","tags":["Quotes"],"summary":"Quote against an existing bridge","description":"Quote a source asset to the bridge's persisted destination — no destination fields required.","security":[{"OrganizationApiKey":["catalog:read","bridges:read"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Target bridge.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_asset_v1":{"type":"string"},"amount":{"type":"string"},"input_side":{"type":"string","enum":["from","to"]},"input_type":{"type":"string","enum":["usd","human","raw"]},"slippage_bps":{"type":"number"},"excluded_provider_ids":{"type":"array","items":{"type":"string"}},"referral_token":{"type":"string"},"destination_asset_v1":{"type":"string"}},"required":["source_asset_v1","amount","input_side"],"additionalProperties":false},"example":{"source_asset_v1":"asset_v1:bitcoin:native:coin","amount":"0.01","input_side":"from"}}}}}},"/v1/payments":{"post":{"operationId":"createPayment","tags":["Payments"],"summary":"Create a payment","description":"Creates a pay-mode bridge and returns the canonical hosted payment URL. Pass a token from POST /v1/referrals/resolve to apply the organization's configured creator fee. Omit capture_mode for automatic checkout, or set capture_mode to manual and configure pay.release controls for escrow/release flows. The request is idempotent with Idempotency-Key.","security":[{"OrganizationApiKey":["bridges:write"]}],"responses":{"201":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"object","properties":{"asset_v1":{"type":"string"},"address":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["asset_v1"],"additionalProperties":false},"target_amount_raw":{"type":"string"},"collection_asset_v1":{"type":"string"},"expires_at":{"type":"string"},"referral_token":{"type":"string"},"policies":{"type":"object","properties":{"on_unmatched":{"type":"string","enum":["market","refund","hold"]},"default_on_mismatch":{"type":"string","enum":["market","refund","hold"]},"default_on_expiry":{"type":"string","enum":["refund","market","hold"]},"on_failure":{"type":"string","enum":["retry","refund","fallback"]},"slippage_bps":{"type":"number"},"default_execution_preference":{"const":"public","type":"string"},"mismatch_grace_seconds":{"type":"number"},"mismatch_hold_expiry_seconds":{"type":"number"},"mismatch_hold_expiry_action":{"type":"string","enum":["refund","market"]},"refund_destination":{"anyOf":[{"type":"object","properties":{"asset_v1":{"type":"string"},"address":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["asset_v1","address"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"capture_mode":{"type":"string","enum":["automatic","manual"]},"control_tokens":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"label":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["pay.release","pay.cancel","pay.refund","pay.extend_expiry","refund.set_destination","pay.override"]}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":{}}},"required":["scopes"],"additionalProperties":false}},"authorization_policy":{"type":"object","properties":{"actions":{"type":"object","additionalProperties":{}}},"additionalProperties":false},"external_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"pay_metadata":{"type":"object","additionalProperties":{}}},"required":["destination","target_amount_raw"],"additionalProperties":false},"example":{"destination":{"asset_v1":"asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","address":"0xRecipient...","memo":null},"target_amount_raw":"49990000","collection_asset_v1":"asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","referral_token":"<token returned by /v1/referrals/resolve>","capture_mode":"manual","control_tokens":[{"ref":"buyer","label":"Buyer approval","scopes":["pay.release"]},{"ref":"seller","label":"Seller approval","scopes":["pay.release"]}],"authorization_policy":{"actions":{"pay.release":{"kind":"quorum","threshold":2,"rules":[{"kind":"token_ref","ref":"buyer"},{"kind":"token_ref","ref":"seller"}]}}},"external_id":"merchant-order-123","metadata":{"order_id":"merchant-order-123"}}}}}}},"/v1/payments/{bridge_id}":{"get":{"operationId":"getPayment","tags":["Payments"],"summary":"Get a payment","description":"Returns payment status, capture/release status, collection progress, and safe bridge/pay-mode state for an organization-owned payment.","security":[{"OrganizationApiKey":["bridges:read"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payments/{bridge_id}/cancel":{"post":{"operationId":"cancelPayment","tags":["Payments"],"summary":"Cancel a payment","description":"Cancels a payment before fulfillment starts. If funds are present, refunds still require the explicit bridge refund destination flow; uSwap does not refund to sender implicitly.","security":[{"OrganizationApiKey":["bridges:write"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payments/{bridge_id}/actions":{"post":{"operationId":"paymentAction","tags":["Payments"],"summary":"Run a payment action","description":"Runs a payment control action. For pay.release, organization API keys act as the partner override when no control_token is supplied; delegated flows provide a scoped control token to record an approval against the release policy.","security":[{"OrganizationApiKey":["bridges:write"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["pay.release","pay.cancel"]},"control_token":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}}},"required":["action"],"additionalProperties":false},"example":{"action":"pay.release","control_token":"uswp_ctl_..."}}}}}},"/v1/bridges/open":{"post":{"operationId":"openBridge","tags":["Bridges"],"summary":"Open bridge and first intent","description":"Atomically creates an organization-owned bridge and commits a selected quote plan as its first intent. Use this for checkout and bot flows that do not need to persist the bridge before the first order. Optionally send source_amount_ceiling_raw (digits-only raw source units) to reject live repricing above the caller-approved spend.","security":[{"OrganizationApiKey":["bridges:write","intents:write"]}],"responses":{"201":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_asset_v1":{"type":"string"},"destination_asset_v1":{"type":"string"},"destination_address":{"type":"string"},"destination_memo":{"anyOf":[{"type":"string"},{"type":"null"}]},"amount":{"type":"string"},"input_side":{"type":"string","enum":["from","to"]},"input_type":{"type":"string","enum":["usd","human","raw"]},"slippage_bps":{"type":"number"},"excluded_provider_ids":{"type":"array","items":{"type":"string"}},"referral_token":{"type":"string"},"policies":{"type":"object","properties":{"on_unmatched":{"type":"string","enum":["market","refund","hold"]},"default_on_mismatch":{"type":"string","enum":["market","refund","hold"]},"default_on_expiry":{"type":"string","enum":["refund","market","hold"]},"on_failure":{"type":"string","enum":["retry","refund","fallback"]},"slippage_bps":{"type":"number"},"default_execution_preference":{"const":"public","type":"string"},"mismatch_grace_seconds":{"type":"number"},"mismatch_hold_expiry_seconds":{"type":"number"},"mismatch_hold_expiry_action":{"type":"string","enum":["refund","market"]},"refund_destination":{"anyOf":[{"type":"object","properties":{"asset_v1":{"type":"string"},"address":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["asset_v1","address"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"external_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}},"draft_id":{"type":"string"},"plan_id":{"type":"string"},"leg_plan_ids":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string"},"request_hash":{"type":"string"},"source_amount_ceiling_raw":{"type":"string","pattern":"^[0-9]+$","maxLength":340,"description":"Optional maximum source spend in the quoted source asset's raw atomic units. Up to 340 digits; live commit fails safely if the final required source exceeds it."},"intent_metadata":{"type":"object","additionalProperties":{}}},"required":["source_asset_v1","destination_asset_v1","amount","input_side","draft_id","plan_id","leg_plan_ids","expires_at","request_hash"],"additionalProperties":false},"example":{"source_asset_v1":"asset_v1:bitcoin:native:coin","destination_asset_v1":"asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","destination_address":"0xRecipient...","amount":"0.01","input_side":"from","input_type":"human","draft_id":"drf_...","plan_id":"pln_...","leg_plan_ids":["leg_..."],"expires_at":"2026-05-22T00:00:00.000Z","request_hash":"...","source_amount_ceiling_raw":"1000000","external_id":"merchant-order-123","metadata":{"order_id":"merchant-order-123"},"intent_metadata":{"customer_id":"cust_123"}}}}}}},"/v1/bridges":{"post":{"operationId":"createBridge","tags":["Bridges"],"summary":"Create a bridge","description":"Creates an organization-owned bridge bound to a canonical destination. Returns the bridge with derived ingress endpoints.","security":[{"OrganizationApiKey":["bridges:write"]}],"responses":{"201":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"object","properties":{"asset_v1":{"type":"string"},"address":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["asset_v1"],"additionalProperties":false},"policies":{"type":"object","properties":{"on_unmatched":{"type":"string","enum":["market","refund","hold"]},"default_on_mismatch":{"type":"string","enum":["market","refund","hold"]},"default_on_expiry":{"type":"string","enum":["refund","market","hold"]},"on_failure":{"type":"string","enum":["retry","refund","fallback"]},"slippage_bps":{"type":"number"},"default_execution_preference":{"const":"public","type":"string"},"mismatch_grace_seconds":{"type":"number"},"mismatch_hold_expiry_seconds":{"type":"number"},"mismatch_hold_expiry_action":{"type":"string","enum":["refund","market"]},"refund_destination":{"anyOf":[{"type":"object","properties":{"asset_v1":{"type":"string"},"address":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["asset_v1","address"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"external_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}}},"required":["destination"],"additionalProperties":false},"example":{"destination":{"asset_v1":"asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","address":"0xRecipient...","memo":null},"policies":{"on_unmatched":"market","default_on_mismatch":"hold","default_on_expiry":"hold","on_failure":"retry","slippage_bps":100},"external_id":"merchant-order-123","metadata":{"order_id":"merchant-order-123"}}}}}},"get":{"operationId":"listBridges","tags":["Bridges"],"summary":"List bridges","description":"Most recently active first. Limited to your organization.","security":[{"OrganizationApiKey":["bridges:read"]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"1–100. Default 50.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bridges/{bridge_id}":{"get":{"operationId":"getBridge","tags":["Bridges"],"summary":"Get a bridge","description":"Returns the bridge with destination, policies, ingress endpoints and asset metadata.","security":[{"OrganizationApiKey":["bridges:read"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bridges/{bridge_id}/policies":{"patch":{"operationId":"updateBridgePolicies","tags":["Bridges"],"summary":"Update bridge policies","description":"Partial update for slippage, mismatch/expiry/failure behavior, and refund destination.","security":[{"OrganizationApiKey":["bridges:write"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"on_unmatched":{"type":"string","enum":["market","refund","hold"]},"default_on_mismatch":{"type":"string","enum":["market","refund","hold"]},"default_on_expiry":{"type":"string","enum":["refund","market","hold"]},"on_failure":{"type":"string","enum":["retry","refund","fallback"]},"slippage_bps":{"type":"number"},"default_execution_preference":{"const":"public","type":"string"},"mismatch_grace_seconds":{"type":"number"},"mismatch_hold_expiry_seconds":{"type":"number"},"mismatch_hold_expiry_action":{"type":"string","enum":["refund","market"]},"refund_destination":{"anyOf":[{"type":"object","properties":{"asset_v1":{"type":"string"},"address":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["asset_v1","address"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"example":{"slippage_bps":75,"default_on_mismatch":"hold","mismatch_hold_expiry_seconds":3600,"mismatch_hold_expiry_action":"refund","refund_destination":{"asset_v1":"asset_v1:base:erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","address":"0xRefundRecipient...","memo":null}}}}}}},"/v1/bridges/{bridge_id}/ingress-endpoints":{"get":{"operationId":"bridgeIngress","tags":["Bridges"],"summary":"Ingress endpoints","description":"Deposit addresses (and memos where required) for every supported source network on this bridge.","security":[{"OrganizationApiKey":["bridges:read"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bridges/{bridge_id}/deposits":{"get":{"operationId":"bridgeDeposits","tags":["Bridges"],"summary":"List bridge deposits","description":"Recent deposits observed on any ingress endpoint of this bridge, including unmatched and held ones.","security":[{"OrganizationApiKey":["bridges:read"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bridges/{bridge_id}/intents":{"get":{"operationId":"bridgeIntents","tags":["Bridges"],"summary":"List bridge intents","description":"Intents created on this bridge, most recently updated first.","security":[{"OrganizationApiKey":["intents:read"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createIntent","tags":["Intents"],"summary":"Commit a quote","description":"Commits the chosen quote plan into an executable intent on the bridge. Optionally send source_amount_ceiling_raw (digits-only raw source units) to reject live repricing above the caller-approved spend.","security":[{"OrganizationApiKey":["intents:write"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Target bridge.","schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draft_id":{"type":"string"},"plan_id":{"type":"string"},"leg_plan_ids":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string"},"request_hash":{"type":"string"},"source_amount_ceiling_raw":{"type":"string","pattern":"^[0-9]+$","maxLength":340,"description":"Optional maximum source spend in the quoted source asset's raw atomic units. Up to 340 digits; live commit fails safely if the final required source exceeds it."},"intent_metadata":{"type":"object","additionalProperties":{}},"policies":{"type":"object","properties":{"on_unmatched":{"type":"string","enum":["market","refund","hold"]},"default_on_mismatch":{"type":"string","enum":["market","refund","hold"]},"default_on_expiry":{"type":"string","enum":["refund","market","hold"]},"on_failure":{"type":"string","enum":["retry","refund","fallback"]},"slippage_bps":{"type":"number"},"default_execution_preference":{"const":"public","type":"string"},"mismatch_grace_seconds":{"type":"number"},"mismatch_hold_expiry_seconds":{"type":"number"},"mismatch_hold_expiry_action":{"type":"string","enum":["refund","market"]},"refund_destination":{"anyOf":[{"type":"object","properties":{"asset_v1":{"type":"string"},"address":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["asset_v1","address"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false}},"required":["draft_id","plan_id","leg_plan_ids","expires_at","request_hash"],"additionalProperties":false},"example":{"draft_id":"drf_...","plan_id":"pln_...","leg_plan_ids":["leg_..."],"expires_at":"2026-05-22T00:00:00.000Z","request_hash":"...","source_amount_ceiling_raw":"1000000","intent_metadata":{"order_id":"merchant-order-123"},"policies":{"default_on_expiry":"refund"}}}}}}},"/v1/intents":{"get":{"operationId":"listIntents","tags":["Intents"],"summary":"List intents","description":"Server-side filtering and keyset cursor pagination across your organization's intents.","security":[{"OrganizationApiKey":["intents:read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"completed, executing, held, failed, refunded, refunding, pending, cancelled, expired.","schema":{"type":"string"}},{"name":"provider_id","in":"query","required":false,"description":"Execution provider label (e.g. oneclick, thorchain).","schema":{"type":"string"}},{"name":"day","in":"query","required":false,"description":"`YYYY-MM-DD`; matches `coalesce(completed_at, updated_at, created_at)::date`.","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Full-text across intent id, bridge id, external id, org slug/name.","schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Filters by `created_at`.","schema":{"type":"string","enum":["7d","30d","90d","all"]}},{"name":"limit","in":"query","required":false,"description":"1–500. Default 100.","schema":{"type":"number"}},{"name":"cursor","in":"query","required":false,"description":"Opaque token; keyset over (updated_at DESC, id DESC).","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"range":{"preset":"30d","from":"...","to":"..."},"items":[{"id":"in_...","bridge_id":"br_...","status":"completed","purpose":"forward","source_asset_v1":"asset_v1:base:erc20:0x...","destination_asset_v1":"asset_v1:monero:native:coin","source_asset":{"symbol":"USDC","network_id":"base","short_label":"USDC","image":"/assets/usdc.png","...":"..."},"destination_asset":{"...":"..."},"route_label":"USDC -> XMR","route_detail_label":"USDC on Base -> XMR on Monero","amount_usd":"1240.00","provider_id":"oneclick","organization_id":"org_...","organization":{"slug":"acme-pay","display_name":"Acme Pay"},"created_at":"...","updated_at":"...","completed_at":"...","status_detail":null}],"next_cursor":"eyJ1IjoiMjAyNi0wNS0..."}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/intents/{intent_id}":{"get":{"operationId":"getIntent","tags":["Intents"],"summary":"Get an intent","description":"Assembled intent view including current status, route, and any held-state metadata.","security":[{"OrganizationApiKey":["intents:read"]}],"parameters":[{"name":"intent_id","in":"path","required":true,"description":"Intent id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/intents/{intent_id}/replay":{"post":{"operationId":"replayIntent","tags":["Intents"],"summary":"Replay a funded intent","description":"Re-quotes and replaces an expired, held, or failed funded forward intent with a market intent. Rejected for provider-review holds or intents without credited funds.","security":[{"OrganizationApiKey":["intents:write"]}],"parameters":[{"name":"intent_id","in":"path","required":true,"description":"Intent id.","schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response.","content":{"application/json":{"example":{"ok":true,"replacement_intent_id":"in_...","intent":{}}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/intents/{intent_id}/legs":{"get":{"operationId":"intentLegs","tags":["Intents"],"summary":"Intent legs","description":"Granular per-leg state for multi-hop routes (provider, status, observed amounts, ingress/egress addresses).","security":[{"OrganizationApiKey":["intents:read"]}],"parameters":[{"name":"intent_id","in":"path","required":true,"description":"Intent id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/intents/{intent_id}/deposits":{"get":{"operationId":"intentDeposits","tags":["Intents"],"summary":"Intent deposits","description":"All deposits matched to (or held by) this intent.","security":[{"OrganizationApiKey":["intents:read"]}],"parameters":[{"name":"intent_id","in":"path","required":true,"description":"Intent id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/intents/{intent_id}/executions":{"get":{"operationId":"intentExecutions","tags":["Intents"],"summary":"Intent executions","description":"Provider execution records (swap legs and their on-chain or off-chain settlement state).","security":[{"OrganizationApiKey":["intents:read"]}],"parameters":[{"name":"intent_id","in":"path","required":true,"description":"Intent id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/intents/{intent_id}/deliveries":{"get":{"operationId":"intentDeliveries","tags":["Intents"],"summary":"Intent deliveries","description":"Outbound deliveries to the destination — txid/memo/amount and confirmation state.","security":[{"OrganizationApiKey":["intents:read"]}],"parameters":[{"name":"intent_id","in":"path","required":true,"description":"Intent id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bridges/{bridge_id}/digital-delivery":{"get":{"operationId":"digitalDeliveryGet","tags":["Digital delivery"],"summary":"Get delivery vault","description":"Returns sanitized protected delivery items for a bridge, optionally narrowed to an intent or leg.","security":[{"OrganizationApiKey":["intents:read"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}},{"name":"intent_id","in":"query","required":false,"description":"Optional intent id.","schema":{"type":"string"}},{"name":"delivery_intent_id","in":"query","required":false,"description":"Alias for intent_id.","schema":{"type":"string"}},{"name":"leg_id","in":"query","required":false,"description":"Optional delivery leg id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"bridge_id":"br_...","intent_id":"in_...","status":"delivered","items":[{"id":"ddi_...","label":"Telegram number","kind":"account","status":"delivered","purchased_at":"2026-05-22T00:00:00.000Z","actions":["request_login_code"],"fields":[{"label":"Login","value":"+15555550123","copy":true}]}],"review_required":false,"updated_at":"2026-05-22T00:00:00.000Z"}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bridges/{bridge_id}/digital-delivery/actions":{"post":{"operationId":"digitalDeliveryAction","tags":["Digital delivery"],"summary":"Run delivery action","description":"Runs a provider action against a public delivery item id, for example requesting a Telegram login code.","security":[{"OrganizationApiKey":["intents:write"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_item_id":{"type":"string"},"action":{"type":"string","enum":["email_code","email_letters","temp_email_password","telegram_code"]},"intent_id":{"type":"string"},"delivery_intent_id":{"type":"string"},"leg_id":{"type":"string"}},"required":["delivery_item_id","action"],"additionalProperties":false},"example":{"intent_id":"in_...","delivery_item_id":"ddi_...","action":"request_login_code"}}}}}},"/v1/bridges/{bridge_id}/deposits/notify":{"post":{"operationId":"depositNotify","tags":["Ingress & holds"],"summary":"Notify a deposit","description":"Notify uSwap that a deposit landed on a specific ingress network. Idempotent on `(network_id, tx_hash)`.","security":[{"OrganizationApiKey":["bridges:write"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"network_id":{"type":"string"},"tx_hash":{"type":"string"},"near_sender_account":{"type":"string"},"memo":{"type":"string"}},"required":["network_id","tx_hash"],"additionalProperties":false},"example":{"network_id":"base","tx_hash":"0x...","near_sender_account":null,"memo":null}}}}}},"/v1/bridges/{bridge_id}/deposits/{deposit_id}/resolve-hold":{"post":{"operationId":"resolveHold","tags":["Ingress & holds"],"summary":"Resolve a held deposit","description":"Take action on a deposit parked in a held state. `market` proceeds at current market rate, `refund` issues a refund to the source, `keep_holding` leaves the hold in place pending further action.","security":[{"OrganizationApiKey":["intents:write"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}},{"name":"deposit_id","in":"path","required":true,"description":"Held deposit id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["market","refund","keep_holding"]}},"required":["action"],"additionalProperties":false},"example":{"action":"market"}}}}}},"/v1/bridges/{bridge_id}/managed-positions":{"get":{"operationId":"bridgeManagedPositions","tags":["Managed positions"],"summary":"List bridge positions","description":"All managed positions attached to a bridge.","security":[{"OrganizationApiKey":["positions:read"]}],"parameters":[{"name":"bridge_id","in":"path","required":true,"description":"Bridge id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/managed-positions/{position_id}":{"get":{"operationId":"getManagedPosition","tags":["Managed positions"],"summary":"Get a managed position","description":"Full position state including counterparty and lifecycle.","security":[{"OrganizationApiKey":["positions:read"]}],"parameters":[{"name":"position_id","in":"path","required":true,"description":"Managed position id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/managed-positions/{position_id}/actions":{"get":{"operationId":"listManagedPositionActions","tags":["Managed positions"],"summary":"Available actions","description":"Lists actions currently available on the position (accept, cancel, settle, etc.).","security":[{"OrganizationApiKey":["positions:read"]}],"parameters":[{"name":"position_id","in":"path","required":true,"description":"Managed position id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"executeManagedPositionAction","tags":["Managed positions"],"summary":"Execute an action","description":"Execute a position action by name with its payload. Peer positions support funding/range actions; MarketApp number rentals support login-code toggles and requests.","security":[{"OrganizationApiKey":["positions:write"]}],"parameters":[{"name":"position_id","in":"path","required":true,"description":"Managed position id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action_type":{"type":"string","enum":["set_accepting","set_intent_range","set_currency_min_rate","set_market_rate","remove_funds","withdraw_deposit","toggle_login_code","request_login_code"]},"accepting":{"type":"boolean"},"min_raw":{"type":"string"},"method":{"type":"string"},"fee_bps":{"type":"number"},"amount_raw":{"type":"string"},"can_receive":{"type":"boolean"}},"required":["action_type"],"additionalProperties":false},"example":{"action_type":"request_login_code"}}}}}},"/v1/managed-positions/{position_id}/sync":{"post":{"operationId":"syncManagedPosition","tags":["Managed positions"],"summary":"Sync with peer","description":"Force a state sync with the counterparty system. Useful when a webhook delivery is delayed or missed.","security":[{"OrganizationApiKey":["positions:write"]}],"parameters":[{"name":"position_id","in":"path","required":true,"description":"Managed position id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhooks","description":"All active webhook endpoints for your organization.","security":[{"OrganizationApiKey":["webhooks:read"]}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Create a webhook","description":"Subscribe a URL to one or more event types. The response includes the signing secret — only this once.","security":[{"OrganizationApiKey":["webhooks:write"]}],"responses":{"201":{"description":"Successful response.","content":{"application/json":{"example":{"webhook":{"id":"owh_...","url":"https://example.com/uswap/webhook","status":"active","event_types":["intent.completed","intent.failed","deposit.held"]},"secret":"whsec_..."}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"event_types":{"type":"array","items":{"type":"string","enum":["bridge.created","bridge.updated","intent.created","intent.updated","intent.completed","intent.failed","deposit.detected","deposit.held","managed_position.updated","payment.created","payment.updated","payment.collecting","payment.funding","payment.funded_partial","payment.ready","payment.processing","payment.completed","payment.expired","payment.cancelled","payment.unsupported","payment.refund_required","payment.refunding"]}}},"required":["url","event_types"],"additionalProperties":false},"example":{"url":"https://example.com/uswap/webhook","description":"Production processor","event_types":["intent.completed","intent.failed","deposit.held"]}}}}}},"/v1/webhooks/{webhook_id}":{"patch":{"operationId":"updateWebhook","tags":["Webhooks"],"summary":"Update a webhook","description":"Partial update — URL, description, event subscriptions, status.","security":[{"OrganizationApiKey":["webhooks:write"]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"event_types":{"type":"array","items":{"type":"string","enum":["bridge.created","bridge.updated","intent.created","intent.updated","intent.completed","intent.failed","deposit.detected","deposit.held","managed_position.updated","payment.created","payment.updated","payment.collecting","payment.funding","payment.funded_partial","payment.ready","payment.processing","payment.completed","payment.expired","payment.cancelled","payment.unsupported","payment.refund_required","payment.refunding"]}},"status":{"type":"string","enum":["active","disabled"]}},"additionalProperties":false},"example":{"event_types":["intent.completed","intent.failed"]}}}}},"delete":{"operationId":"deleteWebhook","tags":["Webhooks"],"summary":"Disable a webhook","description":"Soft-disables the webhook (no further deliveries). Existing delivery records are preserved.","security":[{"OrganizationApiKey":["webhooks:write"]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}}],"responses":{"204":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhook_id}/rotate-secret":{"post":{"operationId":"rotateSecret","tags":["Webhooks"],"summary":"Rotate signing secret","description":"Returns a new `whsec_...` value. The previous secret is invalidated immediately — deploy the new one before rotating.","security":[{"OrganizationApiKey":["webhooks:write"]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhook_id}/deliveries":{"get":{"operationId":"listDeliveries","tags":["Webhooks"],"summary":"Delivery log","description":"Paginated history of delivery attempts. Bodies are omitted from list rows — fetch a specific delivery for the full payload.","security":[{"OrganizationApiKey":["webhooks:read"]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by delivery status.","schema":{"type":"string","enum":["pending","processing","delivered","failed","cancelled"]}},{"name":"event_type","in":"query","required":false,"description":"Filter by event type.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Only deliveries with `created_at >= since`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–100.","schema":{"type":"number"}},{"name":"cursor","in":"query","required":false,"description":"Keyset over (created_at DESC, id DESC).","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"items":[{"id":"owhd_...","webhook_id":"owh_...","event_type":"intent.completed","resource_type":"intent","resource_id":"in_...","status":"delivered","attempts":1,"next_attempt_at":"...","last_attempt_at":"...","last_status_code":200,"last_error":null,"created_at":"...","delivered_at":"..."}],"next_cursor":null}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhook_id}/deliveries/{delivery_id}":{"get":{"operationId":"getDelivery","tags":["Webhooks"],"summary":"Get a delivery","description":"Returns the full delivery record including the signed `payload` body — useful for replay/debug.","security":[{"OrganizationApiKey":["webhooks:read"]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"description":"Webhook id.","schema":{"type":"string"}},{"name":"delivery_id","in":"path","required":true,"description":"Delivery id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats/summary":{"get":{"operationId":"statsSummary","tags":["Stats"],"summary":"Summary","description":"Range-scoped KPIs, a daily time series, and provider/pair breakdowns from the same engine that powers the dashboard.","security":[{"OrganizationApiKey":["stats:read"]}],"parameters":[{"name":"range","in":"query","required":false,"description":"Time window.","schema":{"type":"string","enum":["7d","30d","90d","all"]}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"range":{"preset":"30d","from":"...","to":"..."},"details_available":false,"kpis":{"total_bridges":18,"active_bridges":12,"active_api_keys":3,"active_webhooks":2,"pending_webhooks":0,"members":4,"managed_positions":1,"total_intents":1366,"completed_swaps":1284,"failed_intents":21,"held_intents":12,"pending_intents":36,"refunded_intents":8,"cancelled_intents":5,"total_volume_usd":"2314000.00","fees_earned_usd":"11570.00","avg_completion_seconds":144},"daily":[{"date":"2026-05-25","volume_usd":"12340.00","swaps":24,"completed":22,"failed":1,"held":0,"refunded":1}],"providers":[{"provider_id":"oneclick","volume_usd":"1420000.00","swaps":812}],"pairs":[{"source_asset_v1":"...","destination_asset_v1":"...","volume_usd":"540000.00","swaps":311}],"recent_intents":[],"recent_bridges":[]}}}},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliate-registrations":{"post":{"operationId":"registerAffiliate","tags":["Affiliates"],"summary":"Register as an affiliate","description":"Public, organization-gated registration. Returns a one-time affiliate access token when the organization accepts the registration.","security":[],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Organization accepting registrations.","schema":{"type":"string"}}],"responses":{"201":{"description":"Affiliate registration created."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string"},"display_name":{"type":"string"},"xmr_address":{"type":"string"},"near_account":{"type":"string"},"captcha_token":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["username","display_name","near_account"],"additionalProperties":false}}}}}},"/v1/organizations/{organization_id}/affiliate-registration-settings":{"get":{"operationId":"getAffiliateRegistrationSettings","tags":["Affiliates"],"summary":"Get affiliate registration settings","description":"Returns the organization toggle, approval mode, cap, and current self-registration count.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAffiliateRegistrationSettings","tags":["Affiliates"],"summary":"Update affiliate registration settings","description":"Enables or disables self-registration and controls approval and registration-cap policy.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"auto_approve":{"type":"boolean"},"cap":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false}}}}}},"/v1/organizations/{organization_id}/payout-addresses":{"get":{"operationId":"getOrganizationPayoutAddresses","tags":["Affiliates"],"summary":"Get organization payout addresses","description":"Returns the organization-owned XMR and NEAR destinations used for its referral-fee share.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateOrganizationPayoutAddresses","tags":["Affiliates"],"summary":"Update organization payout addresses","description":"Updates the organization destinations that receive its referral-fee share.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"xmr_address":{"anyOf":[{"type":"string"},{"type":"null"}]},"near_account":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}}}},"/v1/organizations/{organization_id}/affiliates":{"post":{"operationId":"createAffiliate","tags":["Affiliates"],"summary":"Create affiliate","description":"Creates a globally unique creator code and returns its affiliate self-service token once.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string"},"display_name":{"type":"string"},"xmr_address":{"anyOf":[{"type":"string"},{"type":"null"}]},"near_account":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["username","display_name"],"additionalProperties":false}}}}},"get":{"operationId":"listAffiliates","tags":["Affiliates"],"summary":"List affiliates","description":"Lists creator codes and payout-address readiness for the organization.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliates/{affiliate_id}":{"get":{"operationId":"getAffiliate","tags":["Affiliates"],"summary":"Get affiliate","description":"Returns an affiliate and its effective default or per-affiliate split.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"affiliate_id","in":"path","required":true,"description":"Affiliate id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAffiliate","tags":["Affiliates"],"summary":"Update affiliate","description":"Updates display name, lifecycle status, or payout addresses.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"affiliate_id","in":"path","required":true,"description":"Affiliate id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string"},"status":{"type":"string","enum":["active","pending","paused","disabled"]},"xmr_address":{"anyOf":[{"type":"string"},{"type":"null"}]},"near_account":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}}}},"/v1/organizations/{organization_id}/affiliates/{affiliate_id}/category-fees":{"get":{"operationId":"getAffiliateCategoryFees","tags":["Affiliates"],"summary":"Get affiliate category fees","description":"Returns the affiliate's effective customer fee and allocation for every server-defined category.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"affiliate_id","in":"path","required":true,"description":"Affiliate id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliates/{affiliate_id}/category-fees/{category_id}":{"put":{"operationId":"adminSetAffiliateCategoryFee","tags":["Affiliates"],"summary":"Set affiliate category fee","description":"Organization admins can set a customer-fee override for one affiliate category. This is the same storefront setting exposed through affiliate self-service.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"affiliate_id","in":"path","required":true,"description":"Affiliate receiving the override.","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Server-defined fee category.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"total_fee_bps":{"type":"number"}},"required":["total_fee_bps"],"additionalProperties":false}}}}},"delete":{"operationId":"adminResetAffiliateCategoryFee","tags":["Affiliates"],"summary":"Reset affiliate category fee","description":"Organization admins can remove one category override so the affiliate inherits the current default fee.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"affiliate_id","in":"path","required":true,"description":"Affiliate whose override is resetting.","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Server-defined fee category.","schema":{"type":"string"}}],"responses":{"204":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliates/{affiliate_id}/split":{"put":{"operationId":"upsertAffiliateSplit","tags":["Affiliates"],"summary":"Set affiliate split","description":"Sets the affiliate-specific division of the organization slice. Platform floor is rejected and total fee cannot exceed the platform cap.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"affiliate_id","in":"path","required":true,"description":"Affiliate id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"affiliate_share_bps":{"type":"number"},"org_share_bps":{"type":"number"},"total_fee_bps":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["affiliate_share_bps","org_share_bps"],"additionalProperties":false}}}}}},"/v1/organizations/{organization_id}/affiliate-default-split":{"put":{"operationId":"upsertAffiliateDefaultSplit","tags":["Affiliates"],"summary":"Set default affiliate split","description":"Sets the organization default used when an affiliate has no override.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"affiliate_share_bps":{"type":"number"},"org_share_bps":{"type":"number"},"total_fee_bps":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["affiliate_share_bps","org_share_bps"],"additionalProperties":false}}}}},"get":{"operationId":"getAffiliateDefaultSplit","tags":["Affiliates"],"summary":"Get default affiliate split","description":"Returns the organization default, fixed platform floor, and current fee cap.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliate-fee-cap":{"get":{"operationId":"getOrganizationAffiliateFeeCap","tags":["Affiliates"],"summary":"Get organization affiliate fee cap","description":"Returns the organization maximum for default and category customer fees, plus the uSwap hard ceiling.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setOrganizationAffiliateFeeCap","tags":["Affiliates"],"summary":"Set organization affiliate fee cap","description":"Sets the maximum customer fee affiliates may use. Lowering it atomically lowers existing defaults and category overrides above the new cap.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fee_cap_bps":{"type":"number"}},"required":["fee_cap_bps"],"additionalProperties":false}}}}},"delete":{"operationId":"resetOrganizationAffiliateFeeCap","tags":["Affiliates"],"summary":"Reset organization affiliate fee cap","description":"Removes the organization override and restores the uSwap hard ceiling without raising stored fees.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"204":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliate-fee-self-service":{"get":{"operationId":"getOrganizationAffiliateFeeSelfService","tags":["Affiliates"],"summary":"Get affiliate-owned fee configuration policy","description":"Returns whether affiliates may change their own category fees. Organization administrators can always manage fees.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setOrganizationAffiliateFeeSelfService","tags":["Affiliates"],"summary":"Set affiliate-owned fee configuration policy","description":"Enables or disables affiliate-token category-fee mutations without changing stored fees or administrator access.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false}}}}}},"/v1/organizations/{organization_id}/affiliate-category-fee-caps":{"get":{"operationId":"getOrganizationAffiliateCategoryFeeCaps","tags":["Affiliates"],"summary":"Get organization affiliate category fee caps","description":"Returns each category's effective cap and whether it inherits the organization-wide maximum.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliate-category-fee-caps/{category_id}":{"put":{"operationId":"setOrganizationAffiliateCategoryFeeCap","tags":["Affiliates"],"summary":"Set organization affiliate category fee cap","description":"Sets one category maximum beneath the organization-wide cap and lowers existing affiliate overrides above it.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Server-defined fee category.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fee_cap_bps":{"type":"number"}},"required":["fee_cap_bps"],"additionalProperties":false}}}}},"delete":{"operationId":"resetOrganizationAffiliateCategoryFeeCap","tags":["Affiliates"],"summary":"Reset organization affiliate category fee cap","description":"Removes one category override so it inherits the organization-wide cap without raising stored affiliate fees.","security":[{"OrganizationApiKey":["affiliates:write"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Server-defined fee category.","schema":{"type":"string"}}],"responses":{"204":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliate-platform-floor":{"get":{"operationId":"getAffiliatePlatformFloor","tags":["Affiliates"],"summary":"Get organization platform floor","description":"Returns the effective organization platform floor, its override value, and inheritance source.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Organization whose platform policy is being read.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliates/{affiliate_id}/platform-floor":{"get":{"operationId":"getAffiliatePlatformFloorOverride","tags":["Affiliates"],"summary":"Get affiliate platform floor","description":"Returns the affiliate's effective platform floor, explicit override value, and inheritance source.","security":[{"OrganizationApiKey":["affiliates:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"affiliate_id","in":"path","required":true,"description":"Affiliate whose platform policy is being read.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/{organization_id}/affiliate-earnings":{"get":{"operationId":"affiliateEarnings","tags":["Affiliates"],"summary":"Affiliate earnings","description":"Returns organization-level creator-fee totals and per-swap ledger rows, optionally filtered by affiliate_id.","security":[{"OrganizationApiKey":["affiliate_earnings:read"]}],"parameters":[{"name":"organization_id","in":"path","required":true,"description":"Owning organization id.","schema":{"type":"string"}},{"name":"affiliate_id","in":"query","required":false,"description":"Optional affiliate filter.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1-500 ledger rows.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/affiliate/me":{"get":{"operationId":"affiliateSelf","tags":["Affiliates"],"summary":"Affiliate profile","description":"Returns the authenticated affiliate, payout readiness, and read-only effective split.","security":[{"AffiliateAccessToken":[]}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/affiliate/earnings":{"get":{"operationId":"affiliateSelfEarnings","tags":["Affiliates"],"summary":"My affiliate earnings","description":"Returns only the authenticated affiliate's summary and ledger rows.","security":[{"AffiliateAccessToken":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"1-500 ledger rows.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/affiliate/category-fees":{"get":{"operationId":"affiliateSelfCategoryFees","tags":["Affiliates"],"summary":"My category fees","description":"Lists inherited and explicitly overridden customer fees by category, including the current affiliate, organization, and platform allocations.","security":[{"AffiliateAccessToken":[]}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/affiliate/category-fees/{category_id}":{"put":{"operationId":"affiliateSetCategoryFee","tags":["Affiliates"],"summary":"Set category fee","description":"Sets the authenticated affiliate's customer fee for one server-defined category. The hard ceiling is 15%.","security":[{"AffiliateAccessToken":[]}],"parameters":[{"name":"category_id","in":"path","required":true,"description":"Server-defined fee category.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"total_fee_bps":{"type":"number"}},"required":["total_fee_bps"],"additionalProperties":false}}}}},"delete":{"operationId":"affiliateResetCategoryFee","tags":["Affiliates"],"summary":"Reset category fee","description":"Deletes the explicit category override so the category resumes inheriting the existing creator fee.","security":[{"AffiliateAccessToken":[]}],"parameters":[{"name":"category_id","in":"path","required":true,"description":"Server-defined fee category.","schema":{"type":"string"}}],"responses":{"204":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/affiliate/payout-addresses":{"patch":{"operationId":"affiliatePayoutAddresses","tags":["Affiliates"],"summary":"Update payout addresses","description":"Updates only the authenticated affiliate's XMR address and NEAR account. Split configuration is not accepted.","security":[{"AffiliateAccessToken":[]}],"responses":{"200":{"description":"Successful response."},"default":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"xmr_address":{"anyOf":[{"type":"string"},{"type":"null"}]},"near_account":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}}}}},"components":{"securitySchemes":{"OrganizationApiKey":{"type":"http","scheme":"bearer","bearerFormat":"uswp_org","description":"Organization API key: Authorization: Bearer uswp_org_<prefix>_<secret>"},"AffiliateAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"uswp_aff","description":"Affiliate self-service token issued once by the owning organization."}},"schemas":{"Error":{"type":"object","additionalProperties":true,"required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}