Averray Accounts API

openapi: 3.2.0
info:
  title: Averray HTTP Accounts API
  version: 0.2.0
  description: Public discovery, standalone Verify, and wallet-authenticated buyer and worker operations. Work and accounts settle on Polkadot Hub mainnet; paid Verify uses Base USDC. Operator/admin and session-settlement verifier operations are intentionally excluded. Read live discovery for availability and payment terms.
servers:
- url: https://api.averray.com
  description: Public mainnet API
tags:
- name: Accounts
  description: Wallet-scoped account reads and treasury mutations.
paths:
  /account:
    get:
      tags:
      - Accounts
      operationId: getAccountSummary
      summary: Get the signed-in wallet's account summary
      description: Returns wallet-scoped liquid, reserved, strategy, collateral, job-stake, debt, and treasury activity fields. When the blockchain gateway is enabled, `walletBalance` is the worker EOA balance and remains separate from the in-platform `liquid` position.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Account summary for the authenticated wallet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /account/position:
    get:
      tags:
      - Accounts
      operationId: getAccountPosition
      summary: Read the signed-in earnings account
      description: Available balance, job stake, statement and withdrawal door. Asset defaults to USDC.
      security:
      - bearerAuth: []
      parameters:
      - name: asset
        in: query
        required: false
        description: Asset symbol (default USDC).
        schema:
          type: string
      responses:
        '200':
          description: Read the signed-in earnings account
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/borrow-capacity:
    get:
      tags:
      - Accounts
      operationId: getBorrowCapacity
      summary: Read signed-in borrowing capacity
      description: Current collateral-based capacity; no credit or funds move.
      security:
      - bearerAuth: []
      parameters:
      - name: asset
        in: query
        required: false
        description: Asset symbol.
        schema:
          type: string
      responses:
        '200':
          description: Read signed-in borrowing capacity
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /me:
    get:
      tags:
      - Accounts
      operationId: getMe
      summary: Read the signed-in worker's standing
      description: Identity, claim tier, reputation tier, progression and account position.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Read the signed-in worker's standing
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /reputation:
    get:
      tags:
      - Accounts
      operationId: getReputation
      summary: Read the signed-in reputation
      description: Public reputation ladder and scores, not the claim-tier ladder.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Read the signed-in reputation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /account/{path}:
    get:
      tags:
      - Accounts
      operationId: getAccountSubresource
      summary: Read a wallet-scoped account subresource
      description: Compatibility path for supported authenticated account reads. Prefer /account/position (USDC by default) or /account/borrow-capacity.
      security:
      - bearerAuth: []
      parameters:
      - name: path
        in: path
        required: true
        description: Supported read-only account subresource.
        schema:
          type: string
          enum:
          - position
          - borrow-capacity
      - name: asset
        in: query
        required: false
        description: Asset symbol; position defaults to USDC.
        schema:
          type: string
        example: USDC
      responses:
        '200':
          description: The requested account subresource.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: A required query parameter is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The account subresource is not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /account/deposit/transactions:
    post:
      tags:
      - Accounts
      operationId: buildAccountDepositTransactions
      summary: Build unsigned Hub USDC self-deposit templates; the account owner pays DOT gas
      description: Build unsigned Hub USDC self-deposit templates; the account owner pays DOT gas.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              properties:
                asset:
                  const: USDC
                amount:
                  type: string
                  pattern: ^[0-9]+$
                  description: Exact positive integer base units, not a decimal or floating-point number.
              additionalProperties: false
      responses:
        '200':
          description: Wallet-bound unsigned transaction templates. The wallet signs and broadcasts; no relay.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Malformed input or insufficient available balance.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          description: The required chain capability is unavailable.
  /account/withdraw/transactions:
    post:
      tags:
      - Accounts
      operationId: buildWithdrawTransactions
      summary: Build unsigned withdrawal templates; an eligible wallet may request its…
      description: Build unsigned withdrawal templates; an eligible wallet may request its one-time DOT gas grant.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              properties:
                asset:
                  type: string
                amount:
                  type: string
                  pattern: ^[0-9]+$
                  description: Exact positive integer base units, not a decimal or floating-point number.
                destination:
                  type: string
                requestGasGrant:
                  type: boolean
              additionalProperties: false
      responses:
        '200':
          description: Wallet-bound unsigned transaction templates. The wallet signs and broadcasts; no relay.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Malformed input or insufficient available balance.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          description: The required chain capability is unavailable.
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        status:
          type: string
        code:
          type: string
          description: Compatibility error-code field used by a small number of conflict responses.
        message:
          type: string
        details:
          description: Optional structured context for validation, authentication, or conflict failures.
        requestId:
          type: string
      additionalProperties: true
    AssetAmountMap:
      type: object
      additionalProperties:
        type: number
      example:
        USDC: 2
    AccountSummary:
      type: object
      required:
      - wallet
      - liquid
      - reserved
      - strategyAllocated
      - collateralLocked
      - jobStakeLocked
      - debtOutstanding
      properties:
        wallet:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        liquid:
          $ref: '#/components/schemas/AssetAmountMap'
        walletBalance:
          $ref: '#/components/schemas/AssetAmountMap'
        reserved:
          $ref: '#/components/schemas/AssetAmountMap'
        strategyAllocated:
          $ref: '#/components/schemas/AssetAmountMap'
        strategyShares:
          type: object
          additionalProperties: true
        strategyActivity:
          type: object
          additionalProperties: true
        strategyAccounting:
          type: object
          additionalProperties: true
        treasuryTimeline:
          type: array
          items:
            type: object
            additionalProperties: true
        collateralLocked:
          $ref: '#/components/schemas/AssetAmountMap'
        jobStakeLocked:
          $ref: '#/components/schemas/AssetAmountMap'
        debtOutstanding:
          $ref: '#/components/schemas/AssetAmountMap'
        raw:
          type: object
          additionalProperties: true
      additionalProperties: true
  responses:
    Unauthorized:
      description: Authentication is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingToken:
              value:
                error: missing_token
                message: Authentication required.
                requestId: f865d489-2400-469a-945a-3c54e74e5b9e
    Forbidden:
      description: The authenticated wallet does not have the required role.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT