openapi: 3.0.0
info:
  title: API documentation
  version: 1.1.0
components:
  schemas:
    VaraTestnetRequest:
      type: object
      properties:
        token:
          type: string
          description: hCaptcha token
        payload:
          type: object
          description: Balance payload
          properties:
            address:
              type: string
              description: Public wallet address
            genesis:
              type: string
              description: Genesis block hash
      required:
        - token
        - payload
    VaraBridgeRequest:
      type: object
      properties:
        token:
          type: string
          description: hCaptcha token
        address:
          type: string
          description: Account address
        contract:
          type: string
          description: Address of the ERC20 contract
      required:
        - token
        - address
        - contract

    AgentChallengeRequest:
      type: object
      properties:
        address:
          type: string
          description: Vara account address (SS58 or hex)
      required:
        - address
    AgentClaimRequest:
      type: object
      properties:
        address:
          type: string
          description: Vara account address (SS58 or hex)
        genesis:
          type: string
          description: Genesis block hash
        signature:
          type: string
          description: sr25519 signature of the challenge nonce
        nonce:
          type: string
          description: Challenge nonce from /agent/challenge
      required:
        - address
        - genesis
        - signature
        - nonce

paths:
  /balance:
    post:
      summary: Request test balance on Vara Testnet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaraTestnetRequest'
            example:
              payload:
                address: 'account address'
                genesis: 'network genesis'
              token: 'hCaptcha token'
      responses:
        '200':
          description: Request submitted succesfully
        '400':
          description: Bad request, missing or invalid parameters
          content:
            application/json:
              examples:
                MissingParameters: { error: 'Address and genesis are required' }
                InvalidAddress: { error: 'Invalid account address' }
                UnsupportedNetwork: { error: '0x<genesis> is not supported' }

        '403':
          description: Forbidden, transfer limit reached
          content:
            application/json:
              example: { error: 'The limit for requesting test balance has been reached.' }
        '500':
          description: A server internal error
          content:
            application/json:
              example: { error: 'InternalError' }
  /agent/challenge:
    post:
      summary: Request a challenge nonce for agent authentication
      description: Returns a one-time nonce that must be signed by the agent's sr25519 key. Nonce expires in 60 seconds.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentChallengeRequest'
            example:
              address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
      responses:
        '200':
          description: Challenge created
          content:
            application/json:
              example: { nonce: '0xabcdef...', expiresIn: 60 }
        '400':
          description: Invalid address
        '429':
          description: Rate limited
  /agent/vara-testnet/request:
    post:
      summary: Request testnet TVARA tokens (agent authentication via signed challenge)
      description: Submit a signed challenge nonce to prove address ownership and request test tokens.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentClaimRequest'
            example:
              address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
              genesis: '0x525639f713f397dcf839bd022cd821f367ebcf179de7b9253531f8adbe5436d6'
              signature: '0x...'
              nonce: '0xabcdef...'
      responses:
        '200':
          description: Request submitted successfully
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                MissingFields: { error: 'Address, signature, and nonce are required' }
                InvalidAddress: { error: 'Invalid account address' }
        '401':
          description: Authentication failed
          content:
            application/json:
              examples:
                ExpiredChallenge: { error: 'Invalid or expired challenge' }
                BadSignature: { error: 'Invalid signature' }
        '403':
          description: Faucet limit reached
          content:
            application/json:
              example: { error: 'The limit for requesting test balance has been reached.' }
        '429':
          description: Rate limited or daily cap reached
        '500':
          description: Server error
  /bridge/request:
    post:
      summary: Request test tokens on ERC20 contracts used by Vara bridge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaraBridgeRequest'
            example:
              address: '0x<public_key>'
              contract: '0x<erc20_address>'
              token: 'hCaptcha token'
      responses:
        '200':
          description: Request submitted succesfully
        '400':
          description: Bad request, missing or invalid parameters
          content:
            application/json:
              examples:
                MissingParameters: { error: 'Address and genesis are required' }
                InvalidAddress: { error: 'Invalid account address' }
                UnsupportedContract: { error: '0x<contract_address> is not supported' }

        '403':
          description: Forbidden, transfer limit reached
          content:
            application/json:
              example: { error: 'The limit for requesting test balance has been reached.' }
        '500':
          description: A server internal error
          content:
            application/json:
              example: { error: 'InternalError' }