swagger.yml

swagger: '2.0'
host: 127.0.0.1:9510
basePath: /api/v1
info:
  description: This is the hardware-wallet-daemon API
  version: 0.1.0
  title: Hardware Wallet Daemon API
  contact:
    email: steve@skycoin.net

  license:
    name: GPLv3
    url: https://www.gnu.org/licenses/gpl-3.0.en.html

paths:
  /csrf:
    get:
      description: Returns csrf token
      produces:
        - application/json
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/CSRFResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'

  /generate_addresses:
    post:
      description: Generate addresses for the hardware wallet seed.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: GenerateAddressesRequest
          description: GenerateAddressesRequest is request data for /api/v1/generate_addresses
          schema:
            $ref: '#/definitions/GenerateAddressesRequest'
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/GenerateAddressesResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /apply_settings:
    post:
      description: Apply hardware wallet settings.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: ApplySettingsRequest
          description: ApplySettingsRequest is request data for /api/v1/apply_settings
          schema:
            $ref: '#/definitions/ApplySettingsRequest'
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /backup:
    post:
      description: Start seed backup procedure.
      produces:
        - application/json
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /cancel:
    put:
      description: Cancels the current operation.
      produces:
        - application/json
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /check_message_signature:
    post:
      description: Check a message signature matches the given address.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: CheckMessageSignatureRequest
          description: CheckMessageSignatureRequest is request data for /api/v1/check_message_signature
          schema:
            $ref: '#/definitions/CheckMessageSignatureRequest'
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /features:
    get:
      description: Returns device information.
      produces:
        - application/json
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/FeaturesResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /firmware_update:
    put:
      description: Update firmware
      produces:
        - application/json
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /recovery:
    post:
      description: Recover existing wallet using seed.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: RecoveryRequest
          description: RecoveryRequest is request data for /api/v1/check_message_signature
          schema:
            $ref: '#/definitions/RecoveryRequest'
      responses:
        200:
          description: intermediate response
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /generate_mnemonic:
    post:
      description: Generate mnemonic can be used to initialize the device with a random seed.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: GenerateMnemonicRequest
          description: GenerateMnemonicRequest is request data for /api/v1/generate_mnemonic
          schema:
            $ref: '#/definitions/GenerateMnemonicRequest'
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /set_mnemonic:
    post:
      description: Set mnemonic can be used to initialize the device with your own seed.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: SetMnemonicRequest
          description: SetMnemonicRequest is request data for /api/v1/set_mnemonic
          schema:
            $ref: '#/definitions/SetMnemonicRequest'
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /set_pin_code:
    post:
      description: Configure a pin code on the device.
      produces:
        - application/json
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /sign_message:
    post:
      description: Sign a message using the secret key at given index.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: SignMessageRequest
          description: SignMessageRequest is request data for /api/signMessage
          schema:
            $ref: '#/definitions/SignMessageRequest'
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/SignMessageResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /transaction_sign:
    post:
      description: Sign a transaction with the hardware wallet.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: TransactionSignRequest
          description: TransactionSignRequest is request data for /api/v1/transactionSign
          schema:
            $ref: '#/definitions/TransactionSignRequest'
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/TransactionSignResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /wipe:
    delete:
      description: clean all the configurations.
      produces:
        - application/json
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /connected:
    get:
      description: check whether device is connected or not.
      produces:
        - application/json
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              data:
                type: boolean
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []


  /intermediate/pin_matrix:
    post:
      description: pin matrix ack request.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: PinMatrixRequest
          description: PinMatrixRequest is request data for /api/v1/intermediate/pin_matrix
          schema:
            $ref: '#/definitions/PinMatrixRequest'
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /intermediate/passphrase:
    post:
      description: passphrase ack request.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: PassphraseRequest
          description: PassPhraseRequest is request data for /api/v1/intermediate/passphrase
          schema:
            $ref: '#/definitions/PassphraseRequest'
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

  /intermediate/word:
    post:
      description: word ack request.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: WordRequest
          description: WordRequest is request data for /api/v1/intermediate/word
          schema:
            $ref: '#/definitions/WordRequest'
      responses:
        200:
          description: success
          schema:
            $ref: '#/definitions/HTTPSuccessResponse'
        default:
          description: error
          schema:
            $ref: '#/definitions/HTTPErrorResponse'
      security:
        - csrfAuth: []

definitions:
  GenerateAddressesRequest:
    type: object
    required:
      - address_n
    properties:
      address_n:
        type: integer
        example: 2
      start_index:
        type: integer
        example: 1
      confirm_address:
        type: boolean
        example: false

  ApplySettingsRequest:
    type: object
    properties:
      label:
        type: string
        example: "foo"
      use_passphrase:
        type: boolean
        example: false
      language:
        type: string
        example: english

  CheckMessageSignatureRequest:
    type: object
    required:
      - message
      - signature
      - address
    properties:
      message:
        type: string
        example: Hello World
      signature:
        type: string
        example: 6ebd63dd5e57cad07b6d229e96b5d2ac7d1bec1466d2a95bd200c21be6a0bf194b5ad5123f6e37c6393ee3635b38b938fcd91bbf1327fc957849a9e5736f6e4300
      address:
        type: string
        example: 2EU3JbveHdkxW6z5tdhbbB2kRAWvXC2pLzw

  RecoveryRequest:
    type: object
    required:
      - word_count
    properties:
      word_count:
        type: integer
        example: 32
      use_passphrase:
        type: boolean
        example: false
      dry_run:
        type: boolean
        example: false

  GenerateMnemonicRequest:
    type: object
    required:
      - word_count
    properties:
      word_count:
        type: integer
        example: 32
      use_passphrase:
        type: boolean
        example: false

  SetMnemonicRequest:
    type: object
    required:
      - mnemonic
    properties:
      mnemonic:
        type: string
        example: "cloud flower upset remain green metal below cup stem infant art thank"

  SignMessageRequest:
    type: object
    required:
      - address_n
      - message
    properties:
      address_n:
        type: integer
        example: 2
      message:
        type: string
        example: Hello World!

  TransactionInput:
    type: object
    required:
      - index
      - hash
    properties:
      index:
        type: integer
      hash:
        type: string

  TransactionOutput:
    type: object
    required:
      - address_index
      - address
      - coins
      - hours
    properties:
      address_index:
        type: integer
      address:
        type: string
      coins:
        type: string
      hours:
        type: string

  TransactionSignRequest:
    type: object
    required:
      - transaction_inputs
      - transaction_outputs
    properties:
      transaction_inputs:
        type: array
        items:
          $ref: '#/definitions/TransactionInput'
      transaction_outputs:
        type: array
        items:
          $ref: '#/definitions/TransactionOutput'

  PinMatrixRequest:
    type: object
    required:
      - pin
    properties:
      pin:
        type: string

  PassphraseRequest:
    type: object
    required:
      - passphrase
    properties:
      passphrase:
        type: string

  WordRequest:
    type: object
    required:
      - word
    properties:
      word:
        type: string

  GenerateAddressesResponse:
    type: object
    properties:
      data:
        type: array
        items:
          type: string

  FeaturesResponse:
    type: object
    properties:
      data:
        type: object
        required:
          - vendor
          - passphrase_protection
          - pin_protection
          - passphrase_cached
          - needs_backup
          - fw_patch
          - fw_minor
          - fw_major
          - pin_cached
          - initialized
        properties:
          vendor:
            type: string
          major_version:
            type: integer
          minor_version:
            type: integer
          patch_version:
            type: integer
          device_id:
            type: string
          pin_protection:
            type: boolean
          passphrase_protection:
            type: boolean
          label:
            type: string
          initialized:
            type: boolean
          bootloader_hash:
            type: string
          pin_cached:
            type: boolean
          passphrase_cached:
            type: boolean
          needs_backup:
            type: boolean
          model:
            type: string
          fw_major:
            type: integer
          fw_minor:
            type: integer
          fw_patch:
            type: integer

  SignMessageResponse:
    type: object
    properties:
      data:
        type: string

  TransactionSignResponse:
    type: object
    properties:
      data:
        type: array
        items:
          type: string

  CSRFResponse:
    type: object
    properties:
      data:
        type: string

  HTTPSuccessResponse:
    type: object
    properties:
      data:
        type: string

  HTTPErrorResponse:
    type: object
    properties:
      error:
        type: object
        properties:
          message:
            type: string
          code:
            type: integer

schemes:
  - http

securityDefinitions:
  csrfAuth:
    in: header
    name: X-CSRF-TOKEN
    type: apiKey