api.yaml

openapi: '3.0.0'
info:
  version: 1.0.0
  title: Monerochan Merchant RPC
  description: An API to easily accept payments in Monero. Accept digital cash in 3 simple steps. Take a look at the endpoints (1),(2) and (3) first!
servers:
  - url: /v1
paths:
  /wallet/initialize:
    post:
      description: |
        Call this endpoint to create the wallet file from primary address and viewkey. \
        This is the first endpoint you need to call. Afterwards you can call the /wallet/sync endpoint. 
      summary: create the wallet file from primary address and viewkey (1)
      operationId: initialize
      x-eov-operation-handler: routes/wallet/initialize 
      tags:
       - startup tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletInitialize'
            examples:
              Testnet:
                value:
                  path: ./monerochans_testnet_stash
                  networkType: testnet
                  primaryAddress: 9uJ5JRXP3BQAGW1nHK9KzVHUifBfCAHnJKRnZ45ebYcQJrt2wprNgYoGWJvPrCW6nSiBAzmeSAGBGjM5kt2mRb3g98JJetV
                  privateViewKey: d99cca1f6794a0a856cde057421702482b8d56e36f31a939239f97e9f5a32b0d
                  restoreHeight: 0
              Stagenet:
                value:
                  path: ./monerochans_stagenet_stash
                  networkType: stagenet
                  primaryAddress: 55Py9fSwyEeQX1CydtFfPk96uHEFxSxvD9AYBy7dwnYt9cXqKDjix9rS9AWZ5GnH4B1Z7yHr3B2UH2updNw5ZNJEEnv87H1
                  privateViewKey: 1195868d30373aa9d92c1a21514de97670bcd360c209a409ea3234174892770e
                  restoreHeight: 957038
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '500':
          description: unexpected error
  /wallet/sync:
    post:
      description: |
        Call this endpoint to start syncing the wallet after the wallet file was created. \
        This is the second endpoint you need to call after creating the wallet file with /wallet/initialize. \
        Afterwards you can call the accept payments & check api health endpoints. Or shut things down orderly with the shutdown tasks. \
        \
        The monerochan merchant API will supply incoming payments as a JSON object to the url you provided in the callback variable. \
        On every new block that is received during syncing it will supply the transactions received during the last 10 blocks. \
        This way you can keep the user up to date with the numbers of confirmations as they happen (and the is_confirmed status of the transactions). \
        Please make sure to attach a long random generated string to the callback, so that your application stays secure and users cant guess where the callback is located.
      summary: start syncing the wallet after the wallet file was created (2)
      operationId: sync
      x-eov-operation-handler: routes/wallet/sync 
      tags:
       - startup tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletSync'
            examples:
              Testnet:
                value:
                  path: ./monerochans_testnet_stash
                  networkType: testnet
                  serverUri: http://localhost:28081
                  callback: http://monerochans_snickerstore.com/received/money/callback_wlhertno2l3SECRET_RANDOM_STRING

              Stagenet:
                value:
                  path: ./monerochans_stagenet_stash
                  networkType: stagenet
                  serverUri: http://stagenet.xmr-tw.org:38081
                  callback: http://monerochans_snickerstore.com/received/money/callback_wlhertno2l3SECRET_RANDOM_STRING

              Testnet with Testcallback:
                value:
                  path: ./monerochans_testnet_stash
                  networkType: testnet
                  serverUri: http://localhost:28081
                  callback: http://localhost:3001/v1/callback/console_log
           
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '500':
          description: unexpected error
  /make/invoice:
    post:
      description: |
        Supply the path of the wallet where you want to receive the money. \
        As the payment_id you can use the autoincremented_id of a payment_request SQL table for example. \
        Make sure this payment_id is unique per product and client so that you know which payment is for which product or service and which client it came from. \
        You can also use this endpoint to query just the exchange rate or just get an address. \
        It is all combined in this endpoint because these RPC calls are expensive and you will most likely need all of these things at once. The default currency is USD. Check out other supported currencies here: <a href="https://api.coingecko.com/api/v3/simple/supported_vs_currencies">https://api.coingecko.com/api/v3/simple/supported_vs_currencies</a> \
        It might seem odd that the amount is a double, but that is what the coingecko api returns as well. \
        The response amount will contain a String with a big number. This number should have a dot inserted at the place where the dot would be if it was a double that got devided by 1000000000000 \
        The trailing zeros should also be removed before presenting it to the user. The number should be saved without the dot as is so it can later be easily compared with the string that gets returned by the sync callback. \
        This api will take care of these things for you. Show the display_amount to the user and store the amount variable that gets returned by this endpoint.
        
      summary: get a unique address per client and product & the xmr exchange rate (3)
      operationId: invoice
      x-eov-operation-handler: routes/wallet/invoice
      tags:
       - accept payments & check api health
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MakeInvoice'
            examples:
              Testnet:
                value:
                  path: ./monerochans_testnet_stash
                  payment_id: 888
                  amount: 10

              Stagenet:
                value:
                  path: ./monerochans_stagenet_stash
                  payment_id: 888
                  amount: 10
              Testnet Amount in BTC:
                value:
                  path: ./monerochans_testnet_stash
                  payment_id: 888
                  amount: 10
                  currency: btc
              Testnet Amount in EURO:
                value:
                  path: ./monerochans_testnet_stash
                  payment_id: 888
                  amount: 10
                  currency: eur
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MakeInvoiceResponse'
        '500':
          description: unexpected error
  /wallets/status:
    get:
      description: |
        Call this endpoint to get the syncing status of the currently opened wallets. \
        This endpoint can also be used check general api health (if the monerochan merchant api is still running).
      summary: check sync status on individual wallets and general api health
      operationId: status
      x-eov-operation-handler: routes/wallet/status
      tags:
       - accept payments & check api health
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletStatusResponse'
        '500':
          description: unexpected error

  /convert/amount:
    post:
      description: |
        Use this endpoint to calculate conversion amount for amounts received through getTransactions or sync callbacks back to the currency of your choice.
      summary: use this endpoint to calculate conversion rates with FIAT or other coins.
      operationId: convertAmount
      x-eov-operation-handler: routes/wallet/convertAmount
      tags:
       - accept payments & check api health
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertAmount'
            examples:
              Zero point 25 XMR to usd:
                value:
                  amount: "250000000000"
                  currency: usd
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertAmountResponse'
        '500':
          description: unexpected error
  /wallets/getTransactions:
    post:
      description: |
        Use this endpoint to get transactions of a wallet. You can supply max and min height (tx height <= and >=) to limit the scope a bit. \
        Also supply the path of the wallet that you want to query.
      summary: use this endpoint to get transactions of a wallet.
      operationId: getTransactions
      x-eov-operation-handler: routes/wallet/getTransactions
      tags:
       - accept payments & check api health
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTransactions'
            examples:
              Testnet Transaction from 0 to  10000:
                value:
                  path: ./monerochans_testnet_stash
                  minHeight: 0
                  maxHeight: 10000
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsResponse'
        '500':
          description: unexpected error
  /wallets/shutdown:
    post:
      description: |
        Stop syncing and close wallets. \
        Just send the paths of the wallets you want to close as an array. 
      summary: stop syncing and close individual wallets
      operationId: shutdown
      x-eov-operation-handler: routes/wallet/shutdown
      tags:
       - shutdown tasks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletShutdown'
            examples:
              Shutdown Testnet and Stagenet :
                value:
                  - ./monerochans_testnet_stash
                  - ./monerochans_stagenet_stash
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '500':
          description: unexpected error
  /callback/console_log:
    post:
      description: |
        Convenience endpoint to test the sync callback. It will echo the received transactions to the console. \
        The fields: address, payment_id and amount should suffice for most usecases.
      summary: use this to test the sync endpoint
      operationId: testcallback
      x-eov-operation-handler: routes/wallet/testcallback
      tags:
       - testing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionsResponse'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
components:
  schemas:
    WalletInitialize:
      type: object
      properties:
        path:
          type: string
        networkType:
          type: string
          enum: 
            - stagenet
            - mainnet
            - testnet
          default: mainnet
        primaryAddress:
          type: string
        privateViewKey:
          type: string
        restoreHeight:
          type: integer
      required:
        - path
        - primaryAddress
        - privateViewKey
        - restoreHeight
    WalletSync:
      type: object
      properties:
        path:
          type: string
        networkType:
          type: string
          enum: 
            - stagenet
            - mainnet
            - testnet
          default: mainnet
        serverUri:
          type: string
        callback:
          type: string
        include_transactions_without_payment_id:
          type: boolean
          default: false
      required:
        - path
        - serverUri
        - callback
    MakeInvoice:
      type: object
      properties:
        path:
          type: string
        payment_id:
          type: integer
        amount: 
          type: number
        currency:
          type: string
          default: usd
    MakeInvoiceResponse:
      type: object
      properties:
        address:
          type: string
        address_qrcode:
          type: string
        amount:
          type: string
        display_amount:
          type: string
        payment_uri:
          type: string
        payment_uri_qrcode:
          type: string
    SuccessResponse:
      type: object
      properties:
        message:
          type: string
    WalletShutdown:
      type: array
      items:
        type: string
    WalletStatusResponse:
      type: object
      additionalProperties:
        type: object
        properties:
          path:
            type: string
          height:
            type: integer
          startHeight:
            type: integer
          endHeight:
            type: integer
          percentDone:
            type: number
          message:
            type: string
          error_message:
            type: string
        required:
          - path
    ConvertAmount:
      type: object
      properties:
        amount: 
          type: string
        currency: 
          type: string
      required:
        - amount
        - currency
    ConvertAmountResponse:
      type: object
      properties:
        amount: 
          type: string
    GetTransactions:
      type: object
      properties:
        path:
          type: string
        minHeight:
          type: number
        maxHeight:
          type: number
        include_transactions_without_payment_id:
          type: boolean
          default: false
      required:
        - path
    TransactionsResponse:
      type: object
      properties:
        transactions:
          type: array
          items:
            type: object
            properties:
              payment_id:
                type: integer
                nullable: true
              amount:
                type: string
              tx_hash:
                type: string
              height:
                type: integer
              confirmations:
                type: integer
              isConfirmed:
                type: boolean
      
tags:
  - name: startup tasks
    description: initialize & reopen & sync
  - name: accept payments & check api health
  - name: shutdown tasks 
  - name: testing