api.yml

openapi: 3.0.1
info:
  contact:
    email: hello@mainnet.cash
  description: |
    A developer friendly bitcoin cash wallet api

    This API is currently in active development, breaking changes may
    be made prior to official release of version 1.

    **Important:** This library is in active development
  license:
    name: MIT Licence
    url: https://github.com/mainnet-cash/mainnet-js/blob/master/LICENSE
  termsOfService: https://mainnet.cash/terms/
  title: Mainnet Cash
  version: 0.2.6
externalDocs:
  description: Find out more about mainnet-js
  url: https://mainnet.cash
servers:
  - url: https://rest-unstable.mainnet.cash/
    description: unstable service (for development)
  - url: http://localhost:3000/
    description: local development server via `yarn api:serve`
tags:
  - name: contract
    description: Interact with contracts
    externalDocs:
      description: Find out more
      url: https://rest-unstable.mainnet.cash/api-docs/#/contract/
  - name: mine
    description: Mine regtest coins
    externalDocs:
      description: Find out more
      url: https://rest-unstable.mainnet.cash/api-docs/#/mine/
  - name: util
    description: Stateless convenience utilities
    externalDocs:
      description: Find out more
      url: https://rest-unstable.mainnet.cash/api-docs/#/util/
  - name: wallet
    description: Interact with wallets
    externalDocs:
      description: Find out more
      url: https://rest-unstable.mainnet.cash/api-docs/#/wallet/
  - name: webhook
    description: Create webhooks
    externalDocs:
      description: Find out more
      url: https://rest-unstable.mainnet.cash/api-docs/#/webhook/
paths:
  /webhook/watch_address:
    post:
      operationId: watchAddress
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WatchAddressRequest"
        description: |
          Based on the 'type' parameter the webhook will be triggered to either post balance or raw transactions to the 'url' -
          'transaction:in' for incoming only, 'transaction:out' for outgoing only and 'transaction:in,out' both for incoming and outgoing transactions.
          'balance' will post the object according to 'BalanceResponse' schema
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WatchAddressResponse"
          description: Successful operation
        "405":
          content: {}
          description: Invalid input
      summary: |
        Create a webhook to watch cashaddress balance and transactions.
      tags:
        - webhook
  /contract/escrow/create:
    post:
      operationId: createEscrow
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EscrowRequest"
        description: Request a new escrow contract
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractResponse"
          description: successful operation
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Error
      summary: Create an escrow contract
      tags:
        - contract
  /contract/escrow/utxos:
    post:
      operationId: escrowUtxos
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Contract"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UtxoResponse"
          description: successful operation
        "405":
          content: {}
          description: Invalid input
      summary: List specific utxos in a contract
      description: |
        Returns all UTXOs that can be spent by the
        contract. Both confirmed and unconfirmed UTXOs are included.
      tags:
        - contract
  /contract/escrow/call:
    post:
      operationId: escrowFn
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractFnRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractFnResponse"
              example:
                - contractId: "escrow:bchreg:qrc3vd0guh7mn9c9vl58rx6wcv92ld57aquqrre62e:bchreg:qpttdv3qg2usm4nm7talhxhl05mlhms3ys43u76rn0:bchreg:qznjmr5de89zv850lta6jeg5a6ftps4lyu58j8qcp8"
                - walletId: "wif:regtest:cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6"
                - action: "spend"
          description: successful operation
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Error
      summary: Finalize an escrow contract
      tags:
        - contract
  /mine:
    post:
      summary: Mine regtest coins to a specified address
      operationId: mine
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MineRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: a list of block hashes
          description: request accepted
        "400":
          content: {}
          description: Invalid Request
      tags:
        - mine
  /util/convert:
    post:
      operationId: convert
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConvertRequest"
      responses:
        "200":
          content:
            text/plain:
              schema:
                type: number
                description: If a unit of account is passed, a plain number is returned.
          description: successful operation
        "405":
          content: {}
          description: Invalid input
      summary: create a new wallet
      tags:
        - util
  /wallet/create:
    post:
      operationId: createWallet
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WalletRequest"
        description: Request a new new random wallet
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletResponse"
          description: successful operation
        "405":
          content: {}
          description: Invalid input
      summary: create a new wallet
      tags:
        - wallet
  /wallet/balance:
    post:
      operationId: balance
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BalanceRequest"
        description: |
          Request for a wallet balance
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
            text/plain:
              schema:
                type: number
                description: If a unit of account is passed, a plain number is returned.
          description: successful operation
      summary: Get total balance for wallet
      tags:
        - wallet
  /wallet/deposit_address:
    post:
      operationId: depositAddress
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SerializedWallet"
        description: |
          Request for a deposit address given a wallet
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DepositAddressResponse"
          description: successful operation
      summary: Get a deposit address in cash address format
      tags:
        - wallet
  /wallet/deposit_qr:
    post:
      operationId: depositQr
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SerializedWallet"
        description: |
          Request for a deposit cash address as a Quick Response code (qrcode)
        required: true
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScalableVectorGraphic"
          description: |
            A Qr code image data encoded string in the src field suitable for inclusion in html using:
               - \<img src\=\"{response.src}"\>
      summary: Get receiving cash address as a qrcode
      tags:
        - wallet
  /wallet/info:
    post:
      operationId: info
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SerializedWallet"
        description: |
          The wallet to request information about, in serialized form.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletInfo"
          description: |
            Information about the wallet network, type, and keys
      summary: Get information about a wallet
      tags:
        - wallet
  /wallet/max_amount_to_send:
    post:
      operationId: maxAmountToSend
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MaxAmountToSendRequest"
        description: get amount that will be spend with a spend max request. If a unit type is specified, a numeric value will be returned.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BalanceResponse"
          description: transaction accepted
        "400":
          content: {}
          description: Invalid Request
        "418":
          content: {}
          description: Invalid network for given address
      summary: Get maximum spendable amount
      tags:
        - wallet
  /wallet/utxo:
    post:
      operationId: utxos
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SerializedWallet"
        description: |
          Request detailed list of unspent transaction outputs
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UtxoResponse"
          description: successful operation
      summary: Get detailed information about unspent outputs (utxos)
      tags:
        - wallet
  /wallet/send:
    post:
      operationId: send
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendRequest"
        description: place a send request
        required: true
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResponse"
          description: transaction accepted
        "400":
          content: {}
          description: Invalid Request
        "418":
          content: {}
          description: Invalid network for given address
      summary: Send some amount to a given address
      tags:
        - wallet
  /wallet/send_max:
    post:
      operationId: sendMax
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendMaxRequest"
        description: Request to all available funds to a given address
        required: true
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendMaxResponse"
          description: transaction accepted
        "400":
          content: {}
          description: Invalid Request
      summary: Send all available funds to a given address
      tags:
        - wallet
components:
  schemas:
    Utxo:
      properties:
        index:
          type: number
        txId:
          type: string
          example: "1e6442a0d3548bb4f917721184ac1cb163ddf324e2c09f55c46ff0ba521cb89f"
          description: The hash of a transaction
        value:
          type: number
          example: 100
        utxoId:
          type: string
          example: "1e6442a0d3548bb4f917721184ac1cb163ddf324e2c09f55c46ff0ba521cb89f:0"
          description: serialized outpoint
      allOf:
        - $ref: "#/components/schemas/UnitType"
      required:
        - amount
        - txId
        - utxoId
    BalanceRequest:
      properties:
        walletId:
          type: string
          example: "wif:testnet:cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6"
          description: |
            ID that is returned in `wallet` field of /wallet call
      allOf:
        - $ref: "#/components/schemas/UnitType"
      required:
        - walletId
    BalanceResponse:
      properties:
        bch:
          type: number
          format: float
          example: 1
          description: Amount in whole Bitcoin Cash
        sat:
          type: integer
          example: 100000000
          description: Amount in satoshis
        usd:
          type: number
          example: 438.02
          description: Amount in United States Dollars
    Error:
      properties:
        message:
          type: string
        stack:
          type: string
    WatchAddressRequest:
      properties:
        cashaddr:
          type: string
          example: "bchtest:qzd0tv75gx6y0zspzwqpgkwkq0n72g8fsq2zch26s2"
          description: |
            Cash address to watch
        url:
          description:
            Url to be called when configured action is triggered
          type: string
          example: http://example.com/webhook
        type:
          description:
            Type of watch operation
          type: string
          enum:
            - transaction:in
            - transaction:out
            - transaction:in,out
            - balance
          example: transaction:in,out
          default: transaction:in,out
        recurrence:
          description:
            Action recurrence. Indicates if webhook should be triggered recurrently until expire or only once
          type: string
          enum:
            - once
            - recurrent
          example: recurrent
          default: once
        duration_sec:
          description:
            Duration of the webhook lifetime in seconds before it will expire.
          type: number
          example: 86400
          default: 86400
      required:
        - cashaddr
        - url
        - type
    WatchAddressResponse:
      properties:
        id:
          type: number
          format: integer
          example: 1
          description: Webhook Id created in the system
    ZeroBalanceResponse:
      properties:
        bch:
          type: number
          format: float
          example: 0
          description: Amount in whole Bitcoin Cash
        sat:
          type: integer
          example: 0
          description: Amount in satoshis
        usd:
          type: number
          example: 0
          description: Amount in United States Dollars
    Contract:
      properties:
        contractId:
          type: string
          description:  |
            serialized contract
      required:
        - contractId
    EscrowRequest:
      properties:
        buyerAddr:
          example: "bchtest:qrnluuge56ahxsy6pplq43rva7k6s9dknu4p5278ah"
          description: The cashaddress of the buyer
        arbiterAddr:
          example: "bchtest:qzspcywxmm4fqhf9kjrknrc3grsv2vukeqyjqla0nt"
          description: The cashaddress of the arbiter
        sellerAddr:
          example: "bchtest:qz00pk9lfs0k9f5vf3j8h66qfmqagk8nc56elq4dv2"
          description: The cashaddress of the seller
        amount:
          description: Numeric amount to be transferred by the contract in satoshi, amount must be less than 21 BCH.
          type: number
          example: 10000
        nonce:
          description: A unique value added to the contract, which allows the contract to be different from an otherwise identical contract, i.e. two monthly orders.
          type: number
      required:
        - buyerAddr
        - arbiterAddr
        - sellerAddr
        - amount
    ContractResponse:
      properties:
        contractId:
            type: string
            description:  |
              serialized contract
        cashaddr:
          example: "bchtest:qpttdv3qg2usm4nm7talhxhl05mlhms3ys43u76rn0"
          description: The funding address for the contract
    ContractFnRequest:
      properties:
        contractId:
            type: string
            description:  |
              serialized contract
        walletId:
          type: string
          example: "wif:testnet:cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6"
          description: |
            ID that is returned in `wallet` field of /wallet call
        action:
          description: Action for finalization of contract.
          enum:
            - spend
            - refund
          example: spend
          type: string
        to:
          description: output for the transaction
          type: string
          example: "bchtest:qpttdv3qg2usm4nm7talhxhl05mlhms3ys43u76rn0"
        getHexOnly:
          type: boolean
          description: |
            getHexOnly (default:false), if true, will cause only the transaction hex to be returned; if false, the transaction will be sent to the network
        utxoIds:
          type: array
          items:
              type: string
              example: "1e6442a0d3548bb4f917721184ac1cb163ddf324e2c09f55c46ff0ba521cb89f:0:1000"
              description: The hash of a transaction and index of the utxo and amount in satoshi
        
      required:
        - contractId
        - walletId
        - action
    ContractFnResponse:
      properties:
        contractId:
            type: string
            description:  |
              serialized contract
        txId:
          type: string
          example: "1e6442a0d3548bb4f917721184ac1cb163ddf324e2c09f55c46ff0ba521cb89f"
          description: The hash of a transaction
        hex:
          type: string
          example: "0200000001f6d804c0a2f33936dd8b535d1... bdf0e43b30135be5251"
          description: The transaction as bitcoin encoded hex, if getHexOnly is true
    ScalableVectorGraphic:
      properties:
        src:
          type: string
          example: "data:image/svg+xml;base64,PD94bWwgdm... ==**"
          description: |
            A Qr code image data in svg format as utf-8 encoded string.
            Suitable for inclusion in html using:
                - \<img src\=\"**data:image/svg+xml;base64,PD94bWwgdm... ==**"\>
        title:
          example: "bitcoincash:qpttdv3qg2usm4nm7talhxhl05mlhms3ys43u76rn0"
          type: string
          description: hover text for graphic
        alt:
          example: "A Bitcoin Cash Qr Code"
          type: string
          description: assistive text
    SendMaxRequest:
      properties:
        walletId:
          type: string
          example: "wif:testnet:cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6"
          description: |
            ID that is returned in `wallet` field of /wallet call
        cashaddr:
           type: string
           example: bchtest:qpalhxhl05mlhms3ys43u76rn0ttdv3qg2usm4nm7t
      required:
        - walletId
        - cashaddr
    MaxAmountToSendRequest:
      properties:
        walletId:
          type: string
          example: "wif:testnet:cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6"
          description: |
            ID that is returned in `wallet` field of /wallet call
        output_count:
          type: integer
          format: int32
          description: |
            (optional) if sending all funds to multiple addresses, the
            count of the number of address funds will be sent
            to may be included.
      required:
        - walletId
    SerializedWallet:
      properties:
        walletId:
          type: string
          example: "wif:testnet:cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6"
          description: |
            ID that is returned in `wallet` field of /wallet call
      required:
        - walletId
      discriminator:
        propertyName: walletId
    DepositAddressResponse:
      properties:
        cashaddr:
           type: string
           example: bchtest:qpttdv3qg2usm4nm7talhxhl05mlhms3ys43u76rn0
    UtxoResponse:
      properties:
        utxos:
          type: "array"
          items:
            $ref: "#/components/schemas/Utxo"
    WalletResponse:
      properties:
        walletId:
          type: string
          example: "wif:testnet:cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6"
          description: |
            ID that is returned in `wallet` field of /wallet call
        name:
          description: User defined string for wallet
          example: username1
          type: string
        cashaddr:
          description: |
            The address in cashaddr format.
          example: bchtest:qpttdv3qg2usm4nm7talhxhl05mlhms3ys43u76rn0
          type: string
      type: object
      oneOf:
       - $ref: "#/components/schemas/Wif"
       - $ref: "#/components/schemas/WalletMnemonic"
      allOf:
       - $ref: "#/components/schemas/NetworkEnum"
    MineRequest:
      example:
        cashaddr: "bchreg:qpttdv3qg2usm4nm7talhxhl05mlhms3ys43u76rn0"
        blocks: 105
      properties:
        cashaddr:
           type: string
           example: bchreg:qpttdv3qg2usm4nm7talhxhl05mlhms3ys43u76rn0
        blocks:
          type: number
          description: the number of blocks to mine
          example: 105
    ConvertRequest:
      properties:
        value:
          type: number
          example: 100
        from:
          description:
            Provided value unit of account.
          enum:
            - bch
            - BCH
            - usd
            - USD
            - bit
            - bits
            - sat
            - SAT
            - sats
            - satoshi
            - satoshis
          example: bch
          type: string
        to:
          description:
            Unit of account to be returned
          enum:
            - bch
            - BCH
            - usd
            - USD
            - bit
            - bits
            - sat
            - SAT
            - sats
            - satoshi
            - satoshis
          example: usd
          type: string
      required:
        - value
        - from
        - to                
    WalletRequest:
      example:
        type: seed
        network: testnet
        name: username1
      properties:
        name:
          description: User defined string for wallet
          example: username1
          type: string
      type: object
      allOf:
       - $ref: "#/components/schemas/NetworkEnum"
       - $ref: "#/components/schemas/WalletType"
    SendRequest:
      properties:
        walletId:
          type: string
          example: "wif:testnet:cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6"
          description: |
            ID that is returned in `wallet` field of /wallet call
        to:
          type: array
          items:
            $ref: "#/components/schemas/SendRequestItem"
      type: object
    SendRequestItem:
      properties:
        cashaddr:
           type: string
           example: bchtest:qpalhxhl05mlhms3ys43u76rn0ttdv3qg2usm4nm7t
        value:
          type: number
          example: 100
      allOf:
        - $ref: "#/components/schemas/UnitType"
      required:
        - cashaddr
        - value
        - unit
      type: object
    SendMaxResponse:
      properties:
        txId:
          type: string
          example: "1e6442a0d3548bb4f917721184ac1cb163ddf324e2c09f55c46ff0ba521cb89f"
          description: The hash of a transaction
        balance:
          $ref: "#/components/schemas/ZeroBalanceResponse"
      type: object
    SendResponse:
      properties:
        txId:
          type: string
          example: "1e6442a0d3548bb4f917721184ac1cb163ddf324e2c09f55c46ff0ba521cb89f"
          description: The hash of a transaction
        balance:
          $ref: "#/components/schemas/BalanceResponse"
      type: object
    NetworkEnum:
      properties:
        network:
            description: network type
            enum:
              - mainnet
              - testnet
              - regtest
            example: testnet
            type: string
      discriminator:
        propertyName: network
    UnitType:
      properties:
        unit:
          description:
            Unit of account.
          enum:
            - bch
            - BCH
            - usd
            - USD
            - bit
            - bits
            - sat
            - SAT
            - sats
            - satoshi
            - satoshis
          example: sat
          type: string
      discriminator:
        propertyName: unit_type
    WalletType:
      properties:
        type:
            description:
              Wallet type, either a mnemonic seed single address wallet, a simple private key (wif)
              or a Hierarchical Deterministic wallet determined from a seed.
            enum:
              - wif
              - hd
              - seed
              - watch
            example: seed
            type: string
      discriminator:
        propertyName: wallet_type
    WalletInfo:
      properties:
        cashaddr:
          type: string
        isTestnet:
          type: boolean
        name:
          type: string
        publicKey:
          type: string
        publicKeyHash:
          type: string
        privateKey:
          type: string
        privateKeyWif:
          type: string
        seed:
          type: string
        derivationPath:
          type: string
        walletId:
          type: string
        walletDbEntry:
          type: string
      allOf:
       - $ref: "#/components/schemas/NetworkEnum"
    WalletMnemonic:
      properties:
        seed:
          type: string
        derivationPath:
          type: string
      discriminator:
        propertyName: seed
    Wif:
      properties:
        wif:
          description: |
            The wallet in Wallet Import Format (WIF)
          example: cNfsPtqN2bMRS7vH5qd8tR8GMvgXyL5BjnGAKgZ8DYEiCrCCQcP6
          type: string