API Evangelist conversational phrasing for REST Derivatives API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for REST Derivatives API
  version: 1.0.0
extends: openapi/gemini-trust-derivatives-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/v1/margin'].post
  update:
    x-apievangelist-phrasing:
      intent: Get account margin for a perpetuals symbol
      effect: read
      questions:
      - How much margin am I using on my perpetuals account for a given pair?
      - Where do I see my derivatives margin balance and available collateral?
      instructions:
      - text: Show my derivatives account margin for {symbol}.
        slots:
          symbol: requestBody.symbol
      - text: Get perpetuals margin for {symbol} on account {account}.
        slots:
          symbol: requestBody.symbol
          account: requestBody.account
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/perpetuals/fundingPayment'].post
  update:
    x-apievangelist-phrasing:
      intent: List perpetual funding payments
      effect: read
      questions:
      - Which funding payments have I paid or received on my perpetual positions?
      - Can I limit funding payments to a time range?
      instructions:
      - text: List my perpetual funding payments since {since}.
        slots:
          since: query.since
      - text: Show funding payments for account {account} between {since} and {to}.
        slots:
          account: requestBody.account
          since: query.since
          to: query.to
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/perpetuals/fundingpaymentreport/records.xlsx'].get
  update:
    x-apievangelist-phrasing:
      intent: Download funding payment report as Excel
      effect: read
      questions:
      - Can I export my funding payment history as a spreadsheet?
      - What happens if I request the xlsx funding report without a date range?
      instructions:
      - text: Download my funding payment report as an xlsx file from {fromDate} to {toDate}.
        slots:
          fromDate: query.fromDate
          toDate: query.toDate
      - text: Export the last {numRows} funding payment records to Excel.
        slots:
          numRows: query.numRows
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/perpetuals/fundingpaymentreport/records.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Get funding payment report as JSON
      effect: read
      questions:
      - Is there a JSON version of the funding payment report I can parse in code?
      - How are the date range and row count combined when fetching funding payment records?
      instructions:
      - text: Fetch my funding payment report as JSON from {fromDate} to {toDate}.
        slots:
          fromDate: query.fromDate
          toDate: query.toDate
      - text: Return the latest {numRows} funding payment records in JSON.
        slots:
          numRows: query.numRows
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/positions'].post
  update:
    x-apievangelist-phrasing:
      intent: List open derivatives positions
      effect: read
      questions:
      - What perpetual positions do I currently have open?
      - Can I see the open positions of one sub-account from a Master key?
      instructions:
      - text: Show my open perpetuals positions.
      - text: List open positions on account {account}.
        slots:
          account: requestBody.account
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/riskstats/{symbol}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get risk stats for a perpetual contract
      effect: read
      questions:
      - What are the current risk statistics for the BTC perpetual?
      - Can I look up risk data for a single perps symbol before sizing a position?
      instructions:
      - text: Get the risk stats for perpetual {symbol}.
        slots:
          symbol: path.symbol
      - text: Show risk statistics for {symbol}.
        slots:
          symbol: path.symbol
      method: generated
      generated: '2026-10-01'