openapi: 3.1.0
info:
  title: Stay Liquid Yield-as-a-Service API
  version: 0.3.0
  description: >
    Securely earn DeFi yield on your idle stablecoin reserves. This API helps
    businesses automate allocation, rebalancing, and execution across secure,
    risk-evaluated pools using Stay Liquid's Risk Engine.


    You configure your security preferences, and we provide pool recommendations
    and transaction payloads to join/exit pools. No need to build DeFi
    infrastructure.
  contact:
    name: Stay Liquid Support
    email: support@stayliquid.co
security:
  - bearerAuth: []
servers:
  - url: https://api.stayliquid.co
paths:
  /supported-pools:
    get:
      summary: Get all supported yield pools
      description: >-
        Retrieve details about available yield pools, including supported
        stablecoins and security scores. Useful for identifying suitable pools
        based on your risk criteria.
      responses:
        '200':
          description: List of supported pools
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupportedPool'
  /pool-security-score:
    get:
      summary: Get security score for a given pool
      description: >-
        Fetch the security score of a specified yield pool to evaluate risk
        before investing. Helps in making informed decisions about pool
        selection.
      parameters:
        - in: query
          name: pool_name
          required: true
          description: Name of the pool (e.g., 'curve-arb-eusd-usdc')
          schema:
            type: string
      responses:
        '200':
          description: Security score of the pool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoolSecurityScore'
  /portfolio-recommendation:
    get:
      summary: Get optimal stablecoin portfolio allocation
      description: >-
        Get a personalized recommendation for stablecoin allocations based on
        your organization's configured security preferences. Ideal for
        automating yield optimization.
      parameters:
        - in: query
          name: organization_id
          required: true
          description: Unique identifier for your organization
          schema:
            type: string
      responses:
        '200':
          description: Recommended portfolio
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioRecommendation'
  /auto-rebalance:
    get:
      summary: Get rebalancing suggestions
      description: >-
        Use this endpoint to explicitly retrieve rebalancing suggestions and
        payloads if you opted out of automatic webhook notifications. Receive
        actionable suggestions and transaction payloads for rebalancing your
        portfolio according to your set security, yield goals, and rebalancing
        frequency settings. Simplifies the rebalancing process.
      parameters:
        - in: query
          name: organization_id
          required: true
          description: Unique identifier for your organization
          schema:
            type: string
      responses:
        '200':
          description: Rebalancing action and payloads
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoRebalanceResponse'
  /security-preferences:
    post:
      summary: Set or update security and rebalancing preferences
      description: >-
        Configure or update your organization's security, yield, and rebalancing
        preferences. Essential for tailoring portfolio management to your
        specific risk tolerance.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityPreferencesRequest'
      responses:
        '200':
          description: Preferences updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /transaction-payload:
    post:
      summary: Get raw transaction payloads to join or exit pools
      description: >-
        Obtain encoded raw transaction payloads for joining or exiting yield
        pools. Streamlines integration by directly providing ready-to-send
        blockchain transactions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionPayloadRequest'
      responses:
        '200':
          description: Transaction payloads
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPayloadResponse'
  /submit-signed-payloads:
    post:
      summary: Submit signed transaction payloads
      description: >-
        This endpoint is for submitting signed transaction payloads received via
        rebalance webhook.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  chain:
                    type: string
                    description: Target chain for the transaction
                  to:
                    type: string
                    description: Smart contract address
                  signed_data:
                    type: string
                    description: Encoded signed transaction data
                  value:
                    type: string
                    description: Value to send with transaction (in wei)
                required:
                  - chain
                  - to
                  - signed_data
                  - value
      responses:
        '200':
          description: Successful submission
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
webhooks:
  rebalance-webhook:
    post:
      summary: Notify user about rebalance actions
      description: >
        Payload sent by Stay Liquid to the customer's webhook endpoint
        containing suggested portfolio rebalancing actions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RebalanceNotification'
      responses:
        '200':
          description: User successfully received rebalance notification
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token for authorization
  schemas:
    SupportedPool:
      type: object
      properties:
        pool_id:
          type: string
          description: Unique pool identifier
          example: curve-arb-eusd-usdc
        protocol:
          type: string
          description: Protocol providing the yield pool
          example: curve
        chain:
          type: string
          description: Blockchain network name
          example: arbitrum
        stablecoins:
          type: array
          items:
            type: string
          description: List of stablecoins in the pool
          example:
            - eUSD
            - USDC
        security_score:
          type: integer
          description: Security score from 0 (low) to 100 (high)
          example: 86
    PoolSecurityScore:
      type: object
      properties:
        exchange_name:
          type: string
          description: Name of the pool
          example: curve-arb-eusd-usdc
        security_score:
          type: integer
          description: Security score from 0 (low security) to 100 (high security)
          example: 85
    SecurityPreferencesRequest:
      type: object
      properties:
        organization_id:
          type: string
          description: Organization's unique ID
          example: org-123
        min_security_score:
          type: integer
          description: >-
            Minimum acceptable security score (0–100, higher score means better
            security)
          example: 40
        rebalance_frequency_days:
          type: integer
          description: How often do you want to rebalance your portfolio in days
          example: 7
        rebalance_webhook_url:
          type: string
          format: uri
          description: The webhook URL where rebalancing notifications should be sent.
          example: https://customer-webhook-url.com/stayliquid-rebalance
        min_yield:
          type: integer
          description: >-
            Minimum acceptable yield in percent in basis points (0–10000). 1% =
            100 basis points
          example: 500
        allowed_pools:
          type: array
          description: A list of allowed pools (format protocol-chain-poolname-stables)
          items:
            type: string
      required:
        - organization_id
        - min_security_score
        - rebalance_frequency_days
        - rebalance_webhook_url
    PortfolioRecommendation:
      type: object
      properties:
        portfolio_id:
          type: string
          description: Unique ID for recommended portfolio
          example: portfolio_abc123
          readOnly: true
        allocation:
          type: array
          items:
            $ref: '#/components/schemas/PoolAllocation'
    PoolAllocation:
      type: object
      properties:
        pool_id:
          type: string
          description: Pool identifier
          example: curve-arb-eusd-usdc
          readOnly: true
        chain:
          type: string
          description: Blockchain network name
          example: arbitrum
          readOnly: true
        protocol:
          type: string
          description: Protocol providing the yield pool
          example: curve
          readOnly: true
        stablecoin:
          type: array
          items:
            type: string
          description: List of stablecoins used in pool
          example:
            - USDC
            - eUSD
          readOnly: true
        allocation_percent:
          type: integer
          description: >-
            Percent of total allocation in basis points (0–10000). 1% = 100
            basis points
          example: 2500
          readOnly: true
    TransactionPayloadRequest:
      type: object
      properties:
        portfolio_id:
          type: string
          description: ID of the portfolio to apply action on
          example: portfolio_abc123
          readOnly: false
        action:
          type: string
          description: Action to perform on pools
          example: join
          readOnly: false
          enum:
            - join
            - exit
        target_pools:
          type: array
          items:
            type: string
          description: List of pool IDs to act on
          example:
            - curve_usdc_pool
          readOnly: false
      required:
        - portfolio_id
        - action
        - target_pools
    TransactionPayloadResponse:
      type: object
      properties:
        payloads:
          type: array
          items:
            $ref: '#/components/schemas/RawPayload'
    AutoRebalanceResponse:
      type: object
      properties:
        rebalancing:
          type: object
          properties:
            exit_pools:
              type: array
              items:
                type: string
              example:
                - aura-arb-ausdc-gusdc
                - pancake-cow-arb-usdt+-usd+
            enter_pools:
              type: array
              items:
                type: string
              example:
                - uniswap-cow-arb-usdc-dai-vault
            adjust_allocations:
              type: array
              items:
                $ref: '#/components/schemas/PoolAllocation'
              description: >-
                Pools to adjust allocation (increase or decrease) instead of
                full exit/join
          required:
            - exit_pools
            - enter_pools
            - adjust_allocations
        payloads:
          type: array
          items:
            $ref: '#/components/schemas/RawPayload'
    RawPayload:
      type: object
      properties:
        chain:
          type: string
          description: Target chain for the transaction
          example: ethereum
        to:
          type: string
          description: Smart contract address
          example: 0xabc123...
        data:
          type: string
          description: Encoded calldata for the transaction
          example: 0xdeadbeef...
        value:
          type: string
          description: Value to send with transaction (in wei)
          example: '0'
      required:
        - chain
        - to
        - data
        - value
    Portfolio:
      type: object
      properties:
        portfolio_id:
          type: string
          example: portfolio_abc123
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/PoolAllocation'
        total_value_usd:
          type: number
          description: Total value of the portfolio in USD
          example: 100000
    RebalanceAction:
      type: object
      properties:
        action_type:
          type: string
          enum:
            - join
            - exit
            - adjust
          description: Type of rebalancing action
          example: join
        pool_id:
          type: string
          description: Target pool ID
          example: curve-arb-eusd-usdc
        allocation_change_bps:
          type: integer
          description: >-
            Change in allocation percentage in basis points (negative for
            decrease)
          example: 500
        payload:
          $ref: '#/components/schemas/RawPayload'
    RebalanceNotification:
      type: object
      properties:
        account_id:
          type: string
        portfolio_snapshot:
          $ref: '#/components/schemas/Portfolio'
        suggested_actions:
          type: array
          items:
            $ref: '#/components/schemas/RebalanceAction'
        timestamp:
          type: string
          format: date-time
      required:
        - account_id
        - portfolio_snapshot
        - suggested_actions
        - timestamp
