openapi: 3.2.0
info:
  title: aelf Agent Gateway Transfers API
  version: 0.1.0
  description: Secure aelf execution gateway exposed to NyxID as typed MCP tools. Agent-facing operations never return private keys, mnemonics, raw keystores, wallet passwords, Authorization headers, or NyxID delegation tokens.
servers:
- url: http://localhost:8787
security:
- GatewayBearerAuth: []
tags:
- name: Transfers
paths:
  /transfers/prepare:
    post:
      tags:
      - Transfers
      operationId: prepareAelfTransfer
      summary: Validate and prepare an aelf token transfer without signing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferPrepareRequest'
      responses:
        '200':
          description: Transfer intent requiring approval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferIntent'
  /transfers/send:
    post:
      tags:
      - Transfers
      operationId: sendAelfTransfer
      summary: Send a previously approved transfer intent
      description: This operation accepts only prepareId and never accepts replacement transfer parameters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prepareId
              additionalProperties: false
              properties:
                prepareId:
                  type: string
      responses:
        '200':
          description: Broadcast result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferSendResult'
components:
  schemas:
    TransferIntent:
      type: object
      required:
      - prepareId
      - status
      - from
      - to
      - symbol
      - amount
      - rawAmount
      - chainId
      - riskLevel
      - approvalRequired
      - expiresAt
      properties:
        prepareId:
          type: string
        status:
          type: string
          enum:
          - PENDING_APPROVAL
          - APPROVED
          - DENIED
          - EXPIRED
          - SENT
          - FAILED
        from:
          type: string
        to:
          type: string
        symbol:
          type: string
        amount:
          type: string
        rawAmount:
          type: string
        chainId:
          $ref: '#/components/schemas/ChainId'
        estimatedFee:
          type: object
          additionalProperties: true
        riskLevel:
          $ref: '#/components/schemas/RiskLevel'
        approvalRequired:
          type: boolean
        approvalUrl:
          type: string
        expiresAt:
          type: string
          format: date-time
    RiskLevel:
      type: string
      enum:
      - LOW
      - MEDIUM
      - HIGH
      - CRITICAL
      - FORBIDDEN
    TransferPrepareRequest:
      type: object
      required:
      - fromWalletId
      - to
      - symbol
      - amount
      - chainId
      properties:
        fromWalletId:
          type: string
        to:
          type: string
        symbol:
          type: string
          default: ELF
        amount:
          type: string
          description: Human amount, e.g. "1.25".
        chainId:
          $ref: '#/components/schemas/ChainId'
        memo:
          type: string
        idempotencyKey:
          type: string
    ChainId:
      type: string
      enum:
      - AELF
      - tDVV
    TransferSendResult:
      type: object
      required:
      - prepareId
      - status
      properties:
        prepareId:
          type: string
        txId:
          type: string
        status:
          type: string
          enum:
          - SENT
          - TX_PENDING
          - CONFIRMED
          - FAILED
        chainId:
          $ref: '#/components/schemas/ChainId'
  securitySchemes:
    GatewayBearerAuth:
      type: http
      scheme: bearer