openapi: 3.1.0
info:
  title: DeFi Service API
  description: API for the DeFi Service
  version: v2026_01_14
servers:
  - url: http://localhost:7072
    description: Local server
paths:
  /v1/defi/core/balances:
    get:
      summary: Get authenticated user balances
      description: Returns balances for all wallets associated with the authenticated user
      security:
        - bearerAuth: []
      parameters:
        - name: evm
          in: query
          description: Include EVM chain balances
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: A list of balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/quote:
    post:
      summary: Fetch a quote
      security:
        - bearerAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: A quote response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          description: Invalid request payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/trade:
    post:
      summary: Execute a trade
      security:
        - bearerAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TradeRequest'
      responses:
        '201':
          description: The trade response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          description: Invalid request payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/transfer/prepare:
    post:
      summary: Prepare a transfer
      security:
        - bearerAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferPrepareRequest'
      responses:
        '200':
          description: The transfer prepare response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferPrepareResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          description: Invalid request payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/transfer/execute:
    post:
      summary: Execute a transfer
      security:
        - bearerAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferExecuteRequest'
      responses:
        '200':
          description: The transfer execute response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferExecuteResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Transfer not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          description: Invalid request payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/create-wallet:
    post:
      summary: Create a new wallet
      security:
        - bearerAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWalletRequest'
      responses:
        '201':
          description: Wallet created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWalletResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/wallet/export/prepare:
    post:
      summary: Prepare a wallet export payload
      security:
        - bearerAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportWalletPrepareRequest'
      responses:
        '200':
          description: Export payload created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportWalletPrepareResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Wallet not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          description: Invalid request payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Failed to prepare wallet export
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/wallet/export/execute:
    post:
      summary: Execute a wallet private key export
      security:
        - bearerAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportWalletExecuteRequest'
      responses:
        '200':
          description: Export bundle created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportWalletExecuteResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Wallet not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '422':
          description: Invalid request payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Failed to export wallet
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/profile/me:
    get:
      summary: Get the authenticated user profile
      security:
        - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: The authenticated user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        '400':
          description: Bad request (invalid version format)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/assets:
    get:
      summary: Get all active assets
      security: []
      parameters:
        - name: evm
          in: query
          description: Include EVM chain assets
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: A list of active assets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Asset'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/asset/{chain}/{address}:
    get:
      summary: Get asset by chain and address
      security: []
      parameters:
        - name: chain
          in: path
          description: Blockchain chain
          required: true
          schema:
            type: string
        - name: address
          in: path
          description: Asset contract address
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Asset details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '404':
          description: Asset not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/watchlists:
    get:
      summary: Get all watchlists
      description: Returns all global/public watchlists.
      security: []
      responses:
        '200':
          description: A list of watchlists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Watchlist'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
      parameters: []
  /v1/defi/core/watchlists/{id}:
    get:
      summary: Get watchlist by ID
      description: Returns a specific global/public watchlist with all its assets.
      security: []
      parameters:
        - name: id
          in: path
          description: Watchlist UUID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Watchlist with assets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistWithAssets'
        '400':
          description: Invalid watchlist ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Watchlist not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/history:
    get:
      summary: Get transaction history
      description: >-
        Returns a unified view of all user transactions including trades,
        transfers, and onramps
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          description: Maximum number of transactions to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          description: RFC3339 timestamp cursor for pagination
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Transaction history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionHistoryResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: History not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/onramp:
    post:
      summary: Create an onramp transaction
      description: Initiates a Coinbase onramp flow for purchasing crypto with fiat
      security:
        - bearerAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOnrampRequest'
      responses:
        '200':
          description: Onramp transaction created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOnrampResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Wallet not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  /v1/defi/core/onramp/transactions/{id}/status:
    get:
      summary: Get onramp transaction status
      description: Returns the status of a specific onramp transaction
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Transaction ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnrampStatusResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Balance:
      type: object
      description: Balance object with essential fields
      properties:
        id:
          type: string
          format: uuid
        chain:
          type: string
        asset:
          type: string
        symbol:
          type: string
        name:
          type: string
        decimals:
          type: integer
        icon:
          type: string
          nullable: true
        tradeable:
          type: boolean
        stable:
          type: boolean
        balance:
          type: string
    BalanceResponse:
      type: object
      description: Aggregated balance response
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/Balance'
    QuoteRequest:
      type: object
      required:
        - chain
        - base_asset
        - quote_asset
        - order_side
        - qty
      properties:
        chain:
          type: string
        base_asset:
          type: string
        quote_asset:
          type: string
        order_side:
          type: string
          enum:
            - buy
            - sell
        qty:
          type: string
    UnsignedPayload:
      type: object
      required:
        - digest
        - payload
      properties:
        digest:
          type: string
        payload:
          type: string
    QuoteResponse:
      type: object
      properties:
        quote_id:
          type: string
        base_asset:
          type: string
        quote_asset:
          type: string
        order_side:
          type: string
        amount:
          type: string
        fee:
          type: string
        payloads:
          type: array
          items:
            $ref: '#/components/schemas/UnsignedPayload'
        issues:
          type: array
          items:
            type: string
    TradeRequest:
      type: object
      description: Trade request for v1 API supporting multiple signed payloads
      required:
        - signed_payloads
      properties:
        signed_payloads:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/StampedAction'
    StampedAction:
      type: object
      required:
        - payload
        - signature
        - auth_type
      properties:
        payload:
          type: string
          description: The unsigned payload to execute
        signature:
          type: string
          description: The cryptographic signature for the payload
        auth_type:
          type: string
          enum:
            - web_authn
            - api_key
          description: The authentication type used for signing
    TradeResponse:
      type: object
      properties:
        order_id:
          type: string
          format: uuid
    TransferPrepareRequest:
      type: object
      required:
        - chain
        - asset
        - to
        - qty
        - qty_unit
      properties:
        chain:
          type: string
          description: Blockchain chain (e.g., solana, base)
        asset:
          type: string
          description: Asset contract address
        to:
          type: string
          description: Recipient address
        qty:
          type: string
          description: Transfer quantity
        qty_unit:
          type: string
          enum:
            - base
            - quote
          description: Unit of quantity (base for token amount, quote for USD)
    TransferExecuteRequest:
      type: object
      required:
        - transfer_id
        - signatures
        - auth_type
      properties:
        transfer_id:
          type: string
          format: uuid
        signatures:
          type: array
          items:
            type: string
        auth_type:
          type: string
          enum:
            - web_authn
            - api_key
          description: The authentication type used for signing
    TransferPrepareResponse:
      type: object
      properties:
        transfer_id:
          type: string
          format: uuid
        payloads:
          type: array
          items:
            $ref: '#/components/schemas/UnsignedPayload'
    TransferExecuteResponse:
      type: object
      properties:
        tx_hash:
          type: string
        chain:
          type: string
        asset:
          type: string
        from:
          type: string
        to:
          type: string
        sent:
          type: string
        fee:
          type: string
        received:
          type: string
    CreateWalletRequest:
      type: object
      description: Request to create a wallet. Either passkey or api_key must be provided.
      properties:
        passkey:
          type: object
          description: Passkey authentication data (for passkey wallets)
          required:
            - challenge
            - credential_id
            - client_data
            - attestation
          properties:
            challenge:
              type: string
              description: WebAuthn challenge string
            credential_id:
              type: string
              description: WebAuthn credential ID
            client_data:
              type: string
              description: WebAuthn client data JSON
            attestation:
              type: string
              description: WebAuthn attestation object
        api_key:
          type: object
          description: API key data (for API key wallets)
          required:
            - public_key
          properties:
            public_key:
              type: string
              description: API key public key in Turnkey format
    CreateWalletResponse:
      type: object
      description: Response with wallet details
      properties:
        wallets:
          type: array
          description: Detailed wallet information
          items:
            type: object
            properties:
              wallet_id:
                type: string
                description: Turnkey wallet ID
              wallet_account_id:
                type: string
                description: Turnkey wallet account ID
              address:
                type: string
                description: Wallet address
              address_type:
                type: string
                description: Blockchain type (e.g., SOLANA, EVM)
    ExportWalletPrepareRequest:
      type: object
      required:
        - address
        - target_public_key
      properties:
        address:
          type: string
          description: Wallet address to export
        target_public_key:
          type: string
          description: Client-side public key that will receive the encrypted bundle
    ExportWalletExecuteRequest:
      type: object
      required:
        - address
        - target_public_key
        - payload
      properties:
        address:
          type: string
          description: Wallet address to export
        target_public_key:
          type: string
          description: Client-side public key that will receive the encrypted bundle
        payload:
          type: string
          description: Signed Turnkey activity payload authorizing the export
    ExportWalletPrepareResponse:
      type: object
      description: Response with wallet details
      properties:
        payload:
          type: string
          description: Turnkey payload clients must sign to authorize export
    ExportWalletExecuteResponse:
      type: object
      description: Response with wallet details
      properties:
        export_bundle:
          type: string
          description: Encrypted export bundle
    ProfileResponse:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        wallets:
          type: array
          items:
            $ref: '#/components/schemas/Wallet'
    Wallet:
      type: object
      properties:
        chain:
          type: string
        address:
          type: string
    AssetImage:
      type: object
      properties:
        thumb:
          type: string
        small:
          type: string
        large:
          type: string
    AssetMarketData:
      type: object
      properties:
        circulating_supply:
          type: integer
          format: int64
        total_supply:
          type: integer
          format: int64
        max_supply:
          type: integer
          format: int64
    AssetSocials:
      type: object
      properties:
        x_username:
          type: string
        facebook_username:
          type: string
        subreddit_url:
          type: string
        official_forum_url:
          type: string
    Asset:
      type: object
      description: Asset with full metadata including market data and socials
      properties:
        id:
          type: string
          format: uuid
        chain:
          type: string
        address:
          type: string
        symbol:
          type: string
        name:
          type: string
        slug:
          type: string
        decimals:
          type: integer
        description:
          type: string
        website:
          type: string
        icon:
          type: string
          nullable: true
        is_active:
          type: boolean
        tradeable:
          type: boolean
        stable:
          type: boolean
        image:
          $ref: '#/components/schemas/AssetImage'
        market_data:
          $ref: '#/components/schemas/AssetMarketData'
        socials:
          $ref: '#/components/schemas/AssetSocials'
    Watchlist:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the watchlist
        user_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            User ID if this is a user-specific watchlist, null for global
            watchlists
        title:
          type: string
          description: Watchlist title
        description:
          type: string
          nullable: true
          description: Watchlist description
    WatchlistAsset:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the watchlist asset entry
        watchlist_id:
          type: string
          format: uuid
          description: ID of the watchlist this asset belongs to
        asset_id:
          type: string
          format: uuid
          description: ID of the asset
        highlighted:
          type: boolean
          description: Whether this asset is highlighted in the watchlist
        asset:
          $ref: '#/components/schemas/Asset'
          nullable: true
          description: Asset details
    WatchlistWithAssets:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the watchlist
        user_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            User ID if this is a user-specific watchlist, null for global
            watchlists
        title:
          type: string
          description: Watchlist title
        description:
          type: string
          nullable: true
          description: Watchlist description
        assets:
          type: array
          items:
            $ref: '#/components/schemas/WatchlistAsset'
          description: List of assets in this watchlist
    TransactionHistoryResponse:
      type: object
      description: Transaction history response
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/HistoryEntry'
        next_cursor:
          type: string
          format: date-time
          nullable: true
          description: RFC3339 timestamp cursor for pagination
    HistoryEntry:
      type: object
      description: Transaction history entry
      properties:
        id:
          type: string
          description: Unique transaction identifier
        submitted_date:
          type: string
          format: date-time
          description: When the transaction was submitted
        settled_date:
          type: string
          format: date-time
          nullable: true
          description: When the transaction was settled (if applicable)
        status:
          type: string
          enum:
            - PENDING
            - FAILED
            - CANCELLED
            - SUCCESS
            - APPROVED
            - REJECTED
            - CREATED
            - IN_PROGRESS
          description: Current status of the transaction
        errors:
          type: array
          items:
            type: string
          nullable: true
          description: Error messages if transaction failed
        tx_hash:
          type: string
          nullable: true
          description: Blockchain transaction hash
        amount:
          type: string
          description: Transaction amount
        to_asset:
          type: string
          description: Destination asset symbol
        action:
          type: string
          enum:
            - WITHDRAW
            - DEPOSIT
            - BUY
            - SELL
            - SEND
            - RECEIVE
          description: Type of action performed
        from_asset:
          type: string
          description: Source asset symbol
        sender:
          type: string
          description: Sender address
        recipient:
          type: string
          description: Recipient address
    CreateOnrampRequest:
      type: object
      description: Create onramp request
      required:
        - chain
        - amount
        - payment_method
      properties:
        chain:
          type: string
          description: The blockchain to onramp to (e.g., "solana", "base")
          enum:
            - solana
            - base
        amount:
          type: string
          description: The amount to purchase in USD
        payment_method:
          type: string
          description: The payment method to use
    CreateOnrampResponse:
      type: object
      description: Create onramp response
      properties:
        url:
          type: string
          description: The Coinbase onramp URL to redirect the user to
        tx_id:
          type: string
          description: The transaction ID for tracking
    OnrampStatusResponse:
      type: object
      properties:
        tx_status:
          type: string
          description: The current status of the onramp transaction
