openapi: 3.1.0
info:
  description: OpenAPI-first public contract for tenant-facing B2B2X API surfaces. Terminology and resource semantics are sourced from b2b2x-mono.
  summary: Tenant-facing public API for the B2B2X platform.
  title: B2B2X Public API
  version: 0.1.0
servers:
  - description: Sandbox
    url: https://b2b2x-sandbox.youhodler.com/api
  - description: Production
    url: https://b2b2x-sandbox.youhodler.com/api
tags:
  - name: Activation
    description: Enterprise onboarding and initial tenant topology.
  - name: Setup
    description: Identity, access, policy, and approval setup.
  - name: Distribution
    description: Client onboarding, funding setup, and integration readiness.
  - name: Live Operations
    description: Deposits, withdrawals, conversions, and ramp flows.
  - name: Settlement
    description: Balance visibility, review, and operational settlement support.
  - name: Suspension
    description: Controlled deactivation, revocation, and closure flows.
  - name: Auth
    description: Token issuance for public API access.
  - name: Approvals
    description: Approval cases and decision operations.
  - name: Balances
    description: Composite owner balance views for financial accounts.
  - name: Capabilities
    description: Capability listing and client capability overrides.
  - name: Clients
    description: Downstream client resources scoped under an enterprise.
  - name: Client Accounts
    description: Financial operating accounts attached to clients.
  - name: Conversions
    description: Asset-to-asset conversion previews and execution.
  - name: Deposits
    description: Inbound transactions crediting tenant accounts.
  - name: Deposit Instructions
    description: Resolved deposit-side wiring published to senders.
  - name: Enterprises
    description: Enterprise resources and lifecycle.
  - name: Events
    description: Tenant-visible platform event log and webhook replay operations.
  - name: Fee Previews
    description: Indicative, non-binding fee calculations.
  - name: Funding Endpoints
    description: Provisioned deposit-side endpoints for supported rails.
  - name: Identity Providers
    description: Federated identity provider registration and lookup.
  - name: Internal Transfers
    description: Money movement between tenant financial accounts.
  - name: Master Accounts
    description: Enterprise and platform-operator financial operating accounts.
  - name: Prices
    description: Indicative price discovery for asset pairs.
  - name: Roles
    description: Role definitions and access control assignment.
  - name: Role Assignments
    description: Role grants bound to principals and topology scope.
  - name: Service Accounts
    description: Non-human integration actors for backend API use.
  - name: Users
    description: Human actors operating within tenant boundaries.
  - name: Webhook Subscriptions
    description: Webhook subscription configuration and delivery recovery.
  - name: Withdrawals
    description: Outbound transactions debiting tenant accounts.
  - name: Withdrawal Destinations
    description: Persistent destinations referenced when initiating a withdrawal.
  - name: User Invitations
    description: E-mail invitation flows for onboarding new users into a tenant.
  - name: On-ramp Sessions
    description: Fiat-in or crypto-in flows that convert external funds into an account balance.
  - name: Me
    description: Current-caller introspection endpoints for capabilities and navigation.
  - name: Action Tokens
    description: Short-lived action tokens for delegated approval and governed follow-up actions.
  - name: Commercial Agreements
    description: Enterprise commercial agreement lifecycle and supersession.
  - name: Conversion Pairs
    description: Supported conversion pair discovery and lookup.
  - name: Crypto Networks
    description: Crypto network listing and eligibility surfaces.
  - name: Payment Methods
    description: Payment method registration and lifecycle management.
  - name: Payout Methods
    description: Payout method registration and lifecycle management.
  - name: Policies
    description: Policy rule creation, activation, and retirement.
  - name: Operations Activity Exports
    description: Asynchronous export of operations activity data.
  - name: User Action Audit Entries
    description: Search and inspect user action audit trail entries.
  - name: User Action Audit Exports
    description: Asynchronous export of user action audit data.
  - name: Audit
    description: Cross-cutting audit trail surfaces.
  - name: Reporting
    description: Cross-cutting reporting and analytics surfaces.
  - name: Off-ramp Sessions
    description: Crypto-out or fiat-out flows that convert an account balance into external funds.
paths:
  /action-tokens:
    $ref: ./paths/action-tokens.yaml
  /approvals:
    $ref: ./paths/approvals.yaml
  /approvals/{approval_id}:
    $ref: ./paths/approval-by-id.yaml
  /approvals/{approval_id}/approve:
    $ref: ./paths/approval-approve.yaml
  /approvals/{approval_id}/cancel:
    $ref: ./paths/approval-cancel.yaml
  /approvals/{approval_id}/eligible-approvers:
    $ref: ./paths/approval-eligible-approvers.yaml
  /approvals/{approval_id}/reject:
    $ref: ./paths/approval-reject.yaml
  /available-crypto-networks:
    $ref: ./paths/available-crypto-networks.yaml
  /available-payment-methods:
    $ref: ./paths/available-payment-methods.yaml
  /capabilities:
    $ref: ./paths/capabilities.yaml
  /client-accounts:
    $ref: ./paths/client-accounts.yaml
  /client-accounts/{client_account_id}:
    $ref: ./paths/client-account-by-id.yaml
  /client-accounts/{client_account_id}/balances:
    $ref: ./paths/client-account-balances.yaml
  /client-accounts/{client_account_id}/close:
    $ref: ./paths/client-account-close.yaml
  /client-accounts/{client_account_id}/reactivate:
    $ref: ./paths/client-account-reactivate.yaml
  /client-accounts/{client_account_id}/suspend:
    $ref: ./paths/client-account-suspend.yaml
  /clients:
    $ref: ./paths/clients.yaml
  /clients/{client_id}:
    $ref: ./paths/client-by-id.yaml
  /clients/{client_id}/capabilities/{capability_name}:
    $ref: ./paths/client-capability-by-id.yaml
  /clients/{client_id}/close:
    $ref: ./paths/client-close.yaml
  /clients/{client_id}/reactivate:
    $ref: ./paths/client-reactivate.yaml
  /clients/{client_id}/suspend:
    $ref: ./paths/client-suspend.yaml
  /conversion-pairs:
    $ref: ./paths/conversion-pairs.yaml
  /conversion-pairs/{conversion_pair_id}:
    $ref: ./paths/conversion-pair-by-id.yaml
  /conversions:
    $ref: ./paths/conversions.yaml
  /conversions/{conversion_id}:
    $ref: ./paths/conversion-by-id.yaml
  /conversions/{conversion_id}/cancel:
    $ref: ./paths/conversion-cancel.yaml
  /conversions/preview:
    $ref: ./paths/conversions-preview.yaml
  /crypto-networks:
    $ref: ./paths/crypto-networks.yaml
  /deposit-instructions:
    $ref: ./paths/deposit-instructions.yaml
  /deposit-instructions/{deposit_instruction_id}:
    $ref: ./paths/deposit-instruction-by-id.yaml
  /deposits:
    $ref: ./paths/deposits.yaml
  /deposits/{deposit_id}:
    $ref: ./paths/deposit-by-id.yaml
  /eligible-crypto-networks:
    $ref: ./paths/eligible-crypto-networks.yaml
  /eligible-payout-methods:
    $ref: ./paths/eligible-payout-methods.yaml
  /enterprise-commercial-agreements:
    $ref: ./paths/enterprise-commercial-agreements.yaml
  /enterprise-commercial-agreements/{agreement_id}:
    $ref: ./paths/enterprise-commercial-agreement-by-id.yaml
  /enterprise-commercial-agreements/{agreement_id}/supersede:
    $ref: ./paths/enterprise-commercial-agreement-supersede.yaml
  /enterprises:
    $ref: ./paths/enterprises.yaml
  /enterprises/{enterprise_id}:
    $ref: ./paths/enterprise-by-id.yaml
  /enterprises/{enterprise_id}/close:
    $ref: ./paths/enterprise-close.yaml
  /enterprises/{enterprise_id}/reactivate:
    $ref: ./paths/enterprise-reactivate.yaml
  /enterprises/{enterprise_id}/suspend:
    $ref: ./paths/enterprise-suspend.yaml
  /events:
    $ref: ./paths/events.yaml
  /events/{event_id}:
    $ref: ./paths/event-by-id.yaml
  /events/{event_id}/replay:
    $ref: ./paths/event-replay.yaml
  /events/types:
    $ref: ./paths/events-types.yaml
  /fee-previews:
    $ref: ./paths/fee-previews.yaml
  /funding-endpoints:
    $ref: ./paths/funding-endpoints.yaml
  /funding-endpoints/{funding_endpoint_id}:
    $ref: ./paths/funding-endpoint-by-id.yaml
  /identity-providers:
    $ref: ./paths/identity-providers.yaml
  /identity-providers/{identity_provider_id}:
    $ref: ./paths/identity-provider-by-id.yaml
  /internal-transfers:
    $ref: ./paths/internal-transfers.yaml
  /internal-transfers/{internal_transfer_id}:
    $ref: ./paths/internal-transfer-by-id.yaml
  /internal-transfers/{internal_transfer_id}/cancel:
    $ref: ./paths/internal-transfer-cancel.yaml
  /master-accounts:
    $ref: ./paths/master-accounts.yaml
  /master-accounts/{master_account_id}:
    $ref: ./paths/master-account-by-id.yaml
  /master-accounts/{master_account_id}/balances:
    $ref: ./paths/master-account-balances.yaml
  /me/capabilities:
    $ref: ./paths/me-capabilities.yaml
  /me/navigation:
    $ref: ./paths/me-navigation.yaml
  /oauth/token:
    $ref: ./paths/oauth-token.yaml
  /off-ramp-sessions:
    $ref: ./paths/off-ramp-sessions.yaml
  /off-ramp-sessions/{session_id}:
    $ref: ./paths/off-ramp-session-by-id.yaml
  /off-ramp-sessions/{session_id}/cancel:
    $ref: ./paths/off-ramp-session-cancel.yaml
  /on-ramp-sessions:
    $ref: ./paths/on-ramp-sessions.yaml
  /on-ramp-sessions/{session_id}:
    $ref: ./paths/on-ramp-session-by-id.yaml
  /on-ramp-sessions/{session_id}/cancel:
    $ref: ./paths/on-ramp-session-cancel.yaml
  /operations-activity-exports:
    $ref: ./paths/operations-activity-exports.yaml
  /operations-activity-exports/{export_id}:
    $ref: ./paths/operations-activity-export-by-id.yaml
  /operations-activity-exports/{export_id}/download:
    $ref: ./paths/operations-activity-export-download.yaml
  /payment-methods:
    $ref: ./paths/payment-methods.yaml
  /payment-methods/{payment_method_id}:
    $ref: ./paths/payment-method-by-id.yaml
  /payout-methods:
    $ref: ./paths/payout-methods.yaml
  /payout-methods/{payout_method_id}:
    $ref: ./paths/payout-method-by-id.yaml
  /policy-rules:
    $ref: ./paths/policy-rules.yaml
  /policy-rules/{rule_id}:
    $ref: ./paths/policy-rule-by-id.yaml
  /policy-rules/{rule_id}/activate:
    $ref: ./paths/policy-rule-activate.yaml
  /policy-rules/{rule_id}/retire:
    $ref: ./paths/policy-rule-retire.yaml
  /prices/indicative:
    $ref: ./paths/prices-indicative.yaml
  /role-assignments:
    $ref: ./paths/role-assignments.yaml
  /role-assignments/{role_assignment_id}:
    $ref: ./paths/role-assignment-by-id.yaml
  /role-assignments/{role_assignment_id}/revoke:
    $ref: ./paths/role-assignment-revoke.yaml
  /roles:
    $ref: ./paths/roles.yaml
  /roles/{role_id}:
    $ref: ./paths/role-by-id.yaml
  /roles/{role_id}/retire:
    $ref: ./paths/role-retire.yaml
  /service-accounts:
    $ref: ./paths/service-accounts.yaml
  /service-accounts/{service_account_id}:
    $ref: ./paths/service-account-by-id.yaml
  /service-accounts/{service_account_id}/revoke:
    $ref: ./paths/service-account-revoke.yaml
  /service-accounts/{service_account_id}/rotate-secret:
    $ref: ./paths/service-account-rotate-secret.yaml
  /service-accounts/provision:
    $ref: ./paths/service-accounts-provision.yaml
  /user-action-audit-entries/{entry_id}:
    $ref: ./paths/user-action-audit-entry-by-id.yaml
  /user-action-audit-entries/search:
    $ref: ./paths/user-action-audit-entries-search.yaml
  /user-action-audit-exports:
    $ref: ./paths/user-action-audit-exports.yaml
  /user-action-audit-exports/{export_id}:
    $ref: ./paths/user-action-audit-export-by-id.yaml
  /user-action-audit-exports/{export_id}/download:
    $ref: ./paths/user-action-audit-export-download.yaml
  /user-invitations:
    $ref: ./paths/user-invitations.yaml
  /user-invitations/{invitation_id}:
    $ref: ./paths/user-invitation-by-id.yaml
  /user-invitations/accept:
    $ref: ./paths/user-invitations-accept.yaml
  /user-invitations/cancel:
    $ref: ./paths/user-invitations-cancel.yaml
  /users:
    $ref: ./paths/users.yaml
  /users/{user_id}:
    $ref: ./paths/user-by-id.yaml
  /users/{user_id}/deactivate:
    $ref: ./paths/user-deactivate.yaml
  /users/{user_id}/reactivate:
    $ref: ./paths/user-reactivate.yaml
  /users/{user_id}/suspend:
    $ref: ./paths/user-suspend.yaml
  /webhook-subscriptions:
    $ref: ./paths/webhook-subscriptions.yaml
  /webhook-subscriptions/{subscription_id}:
    $ref: ./paths/webhook-subscription-by-id.yaml
  /webhook-subscriptions/{subscription_id}/delete:
    $ref: ./paths/webhook-subscription-delete.yaml
  /webhook-subscriptions/{subscription_id}/deliveries:
    $ref: ./paths/webhook-subscription-deliveries.yaml
  /webhook-subscriptions/{subscription_id}/deliveries/{delivery_id}:
    $ref: ./paths/webhook-subscription-delivery-by-id.yaml
  /webhook-subscriptions/{subscription_id}/deliveries/{delivery_id}/redeliver:
    $ref: ./paths/webhook-subscription-redeliver.yaml
  /webhook-subscriptions/{subscription_id}/disable:
    $ref: ./paths/webhook-subscription-disable.yaml
  /webhook-subscriptions/{subscription_id}/enable:
    $ref: ./paths/webhook-subscription-enable.yaml
  /webhook-subscriptions/{subscription_id}/test:
    $ref: ./paths/webhook-subscription-test.yaml
  /withdrawal-destinations:
    $ref: ./paths/withdrawal-destinations.yaml
  /withdrawal-destinations/{destination_id}:
    $ref: ./paths/withdrawal-destination-by-id.yaml
  /withdrawal-destinations/{destination_id}/disable:
    $ref: ./paths/withdrawal-destination-disable.yaml
  /withdrawal-destinations/{destination_id}/enable:
    $ref: ./paths/withdrawal-destination-enable.yaml
  /withdrawal-destinations/{destination_id}/retire:
    $ref: ./paths/withdrawal-destination-retire.yaml
  /withdrawals:
    $ref: ./paths/withdrawals.yaml
  /withdrawals/{withdrawal_id}:
    $ref: ./paths/withdrawal-by-id.yaml
  /withdrawals/{withdrawal_id}/cancel:
    $ref: ./paths/withdrawal-cancel.yaml
components:
  parameters:
    IdempotencyKey:
      $ref: ./components/parameters/IdempotencyKey.yaml
    IfMatch:
      $ref: ./components/parameters/IfMatch.yaml
    PageSize:
      $ref: ./components/parameters/PageSize.yaml
    PageToken:
      $ref: ./components/parameters/PageToken.yaml
    XActionToken:
      $ref: ./components/parameters/XActionToken.yaml
  responses:
    EdgeActionTokenRequired:
      $ref: ./components/responses/EdgeActionTokenRequired.yaml
    EdgeBadGateway:
      $ref: ./components/responses/EdgeBadGateway.yaml
    EdgeBadRequest:
      $ref: ./components/responses/EdgeBadRequest.yaml
    EdgeConflict:
      $ref: ./components/responses/EdgeConflict.yaml
    EdgeForbidden:
      $ref: ./components/responses/EdgeForbidden.yaml
    EdgeGone:
      $ref: ./components/responses/EdgeGone.yaml
    EdgeNotFound:
      $ref: ./components/responses/EdgeNotFound.yaml
    EdgePreconditionFailed:
      $ref: ./components/responses/EdgePreconditionFailed.yaml
    EdgeRateLimited:
      $ref: ./components/responses/EdgeRateLimited.yaml
    EdgeUnprocessable:
      $ref: ./components/responses/EdgeUnprocessable.yaml
    ForbiddenCapabilityScope:
      $ref: ./components/responses/ForbiddenCapabilityScope.yaml
    TemporarilyUnavailable:
      $ref: ./components/responses/TemporarilyUnavailable.yaml
    Unauthorized:
      $ref: ./components/responses/Unauthorized.yaml
  securitySchemes:
    BearerAuth:
      $ref: ./components/security-schemes/BearerAuth.yaml
    OAuth2ClientCredentials:
      $ref: ./components/security-schemes/OAuth2ClientCredentials.yaml
x-tagGroups:
  - name: Workflow
    tags:
      - Activation
      - Setup
      - Distribution
      - Live Operations
      - Settlement
      - Suspension
  - name: Reference
    tags:
      - Auth
      - Me
      - Enterprises
      - Master Accounts
      - Commercial Agreements
      - Clients
      - Client Accounts
      - Users
      - Service Accounts
      - Roles
      - Role Assignments
      - Identity Providers
      - Capabilities
      - Policies
      - Action Tokens
      - Approvals
      - Balances
      - Deposits
      - Deposit Instructions
      - Funding Endpoints
      - Payment Methods
      - Payout Methods
      - Crypto Networks
      - Conversion Pairs
      - Webhook Subscriptions
      - Events
      - Withdrawals
      - Withdrawal Destinations
      - Internal Transfers
      - Conversions
      - Fee Previews
      - Prices
      - User Invitations
      - On-ramp Sessions
      - Off-ramp Sessions
      - Operations Activity Exports
      - User Action Audit Entries
      - User Action Audit Exports
      - Audit
      - Reporting