{"openapi":"3.1.0","info":{"title":"uSwap Partner API","version":"1.0.0","description":"SDK-oriented OpenAPI contract for organization API-key partner 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."}],"paths":{"/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, scopes, and dispatch split rules."},"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.","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.","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"}}],"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/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"}}},"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"}},"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. 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"},"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"},"dispatch_splits":{"anyOf":[{"type":"object","properties":{"routes":{"type":"array","items":{"type":"object","properties":{"portion_bps":{"type":"number"},"destination_kind":{"type":"string","enum":["next_leg","explicit_address","refund_destination","user_destination"]},"explicit_destination":{"oneOf":[{"type":"object","properties":{"kind":{"const":"intents_balance","type":"string"},"account_id":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"}},"required":["kind","account_id","asset_v1","amount_raw"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"chain_address","type":"string"},"chain":{"type":"string"},"address":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","chain","address","asset_v1","amount_raw"],"additionalProperties":false}]},"label":{"type":"string"}},"required":["portion_bps","destination_kind"],"additionalProperties":false}},"atomic":{"const":true,"type":"boolean"}},"required":["routes","atomic"],"additionalProperties":false},{"type":"null"}]},"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","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.","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"}},"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"},"dispatch_splits":{"anyOf":[{"type":"object","properties":{"routes":{"type":"array","items":{"type":"object","properties":{"portion_bps":{"type":"number"},"destination_kind":{"type":"string","enum":["next_leg","explicit_address","refund_destination","user_destination"]},"explicit_destination":{"oneOf":[{"type":"object","properties":{"kind":{"const":"intents_balance","type":"string"},"account_id":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"}},"required":["kind","account_id","asset_v1","amount_raw"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"chain_address","type":"string"},"chain":{"type":"string"},"address":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","chain","address","asset_v1","amount_raw"],"additionalProperties":false}]},"label":{"type":"string"}},"required":["portion_bps","destination_kind"],"additionalProperties":false}},"atomic":{"const":true,"type":"boolean"}},"required":["routes","atomic"],"additionalProperties":false},{"type":"null"}]},"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"},"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":"...","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"},"dispatch_splits":{"anyOf":[{"type":"object","properties":{"routes":{"type":"array","items":{"type":"object","properties":{"portion_bps":{"type":"number"},"destination_kind":{"type":"string","enum":["next_leg","explicit_address","refund_destination","user_destination"]},"explicit_destination":{"oneOf":[{"type":"object","properties":{"kind":{"const":"intents_balance","type":"string"},"account_id":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"}},"required":["kind","account_id","asset_v1","amount_raw"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"chain_address","type":"string"},"chain":{"type":"string"},"address":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","chain","address","asset_v1","amount_raw"],"additionalProperties":false}]},"label":{"type":"string"}},"required":["portion_bps","destination_kind"],"additionalProperties":false}},"atomic":{"const":true,"type":"boolean"}},"required":["routes","atomic"],"additionalProperties":false},{"type":"null"}]},"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, refund destination, and dispatch splits.","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"},"dispatch_splits":{"anyOf":[{"type":"object","properties":{"routes":{"type":"array","items":{"type":"object","properties":{"portion_bps":{"type":"number"},"destination_kind":{"type":"string","enum":["next_leg","explicit_address","refund_destination","user_destination"]},"explicit_destination":{"oneOf":[{"type":"object","properties":{"kind":{"const":"intents_balance","type":"string"},"account_id":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"}},"required":["kind","account_id","asset_v1","amount_raw"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"chain_address","type":"string"},"chain":{"type":"string"},"address":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","chain","address","asset_v1","amount_raw"],"additionalProperties":false}]},"label":{"type":"string"}},"required":["portion_bps","destination_kind"],"additionalProperties":false}},"atomic":{"const":true,"type":"boolean"}},"required":["routes","atomic"],"additionalProperties":false},{"type":"null"}]},"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.","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"},"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"},"dispatch_splits":{"anyOf":[{"type":"object","properties":{"routes":{"type":"array","items":{"type":"object","properties":{"portion_bps":{"type":"number"},"destination_kind":{"type":"string","enum":["next_leg","explicit_address","refund_destination","user_destination"]},"explicit_destination":{"oneOf":[{"type":"object","properties":{"kind":{"const":"intents_balance","type":"string"},"account_id":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"}},"required":["kind","account_id","asset_v1","amount_raw"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"chain_address","type":"string"},"chain":{"type":"string"},"address":{"type":"string"},"asset_v1":{"type":"string"},"amount_raw":{"type":"string"},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["kind","chain","address","asset_v1","amount_raw"],"additionalProperties":false}]},"label":{"type":"string"}},"required":["portion_bps","destination_kind"],"additionalProperties":false}},"atomic":{"const":true,"type":"boolean"}},"required":["routes","atomic"],"additionalProperties":false},{"type":"null"}]},"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":"...","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","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"}}}}}}}},"components":{"securitySchemes":{"OrganizationApiKey":{"type":"http","scheme":"bearer","bearerFormat":"uswp_org","description":"Organization API key: Authorization: Bearer uswp_org_<prefix>_<secret>"}},"schemas":{"Error":{"type":"object","additionalProperties":true,"required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}