openapi: 3.0.0
servers:
  - url: 'https://api-eul.tatum.io'
info:
  version: 1.0.0
  title: Tatum Algorand API
tags:
  - description: |
      <p>Algorand is a decentralized blockchain technology network. Algorand is enabling the simple creation of next generation financial products, protocols and exchange of value across defi, financial institutions and governments.<br/>
      Tatum supports 2 chains:
      <ul><li>Mainnet - a regular live chain
      <li>Testnet - a chain used for testing purposes. Coins on the test chain have no value and can be obtained from
      a faucet, e.g. <a target="_blank" href="https://bank.testnet.algorand.network/">https://bank.testnet.algorand.network/</a></li></ul></p>
    name: Blockchain / Algorand (ALGO)
paths:
  /v3/algorand/wallet:
    get:
      description: |
        <h4>1 credit per API call.</h4><br/><p>Tatum supports Algorand wallets.</p>
      operationId: AlgorandGenerateWallet
      parameters:
        - description: "Mnemonic to use for generation of extended public and private keys."
          in: query
          name: mnemonic
          required: false
          schema:
            type: string
            maxLength: 500
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlgoWallet"
          description: OK
        400: &API400
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error400"
          description: Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
        401: &API401
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Error401NotActive"
                  - $ref: "#/components/schemas/Error401Invalid"
          description: Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
        500: &API500
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error500"
          description: Internal server error. There was an error on the server during the processing of the request.
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Generate Algorand wallet
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/address/{priv}:
    get:
      description: |
        <h4>1 credit per API call.</h4><br/>
        <p>Generate Algorand account deposit address from private key.</p>
      operationId: AlgorandGenerateAddress
      parameters:
        - description: "private key of wallet."
          in: path
          name: priv
          required: true
          schema:
            type: string
            example: "NBYMCVEEDFYV3TPWVRE6APE7PKHUJD4XAKXCKNCLKGUXOC3LFNJGZQCJCRA53HB7ZAHF6NFJH2QIVQ5USQNWG35QCJLD4KZ5IWMB24Q"
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                    description: Algorand address
                    example: "NTAESFCB3WOD7SAOL42KSPVARLB3JFA3MNX3AESWHYVT2RMYDVZI6YLG4Y"
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Generate Algorand account address from private key
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/node/indexer/{xApiKey}/**:
    get:
      description: |
        <h4>1 credit per API call.</h4><br/>
        <p>Use this endpoint URL as a http-based url to connect directly to the Algorand node provided by Tatum.
        You can check al available APIs here - <a href="https://developer.algorand.org/docs/rest-apis/indexer/" target="_blank">https://developer.algorand.org/docs/rest-apis/indexer/</a>.
        <br/>
        Example call for Get Tx By ID is described in the response. <a href="https://developer.algorand.org/docs/rest-apis/indexer/#get-v2transactionstxid" target="_blank">https://developer.algorand.org/docs/rest-apis/indexer/#get-v2transactionstxid</a>.
        <br/>
        URL used for this call would be <pre>https://api-eu1.tatum.io/v3/algorand/node/indexer/YOUR_API_KEY/v2/transactions/HNIQ76UTJYPOLZP5FWODYABBJPYPGJNEM2QEJSMDMQRWEKHEYJHQ</pre>
        </p>
      operationId: AlgoNodeIndexerGetDriver
      parameters:
        - description: "Tatum X-API-Key used for authorization."
          in: path
          name: xApiKey
          required: true
          schema:
            type: string
            example: asdlkfjnqunalkwjfnq2oi303294857k
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlgoTx"
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Access Algorand Indexer GET node endpoints
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/node/algod/{xApiKey}/**:
    get:
      description: |
        <h4>1 credit per API call.</h4><br/>
        <p>Use this endpoint URL as a http-based url to connect directly to the Algorand node provided by Tatum.
        You can check al available APIs here - <a href="https://developer.algorand.org/docs/rest-apis/algod/v2/" target="_blank">https://developer.algorand.org/docs/rest-apis/algod/v2/</a>.
        <br/>
        Example call for Get Block is described in the response. <a href="https://developer.algorand.org/docs/rest-apis/algod/v2/#get-v2blocksround" target="_blank">https://developer.algorand.org/docs/rest-apis/algod/v2/#get-v2blocksround</a>.
        <br/>
        URL used for this call would be <pre>https://api-eu1.tatum.io/v3/algorand/node/algod/YOUR_API_KEY/v2/blocks/16775567</pre>
        </p>
      operationId: AlgoNodeGetDriver
      parameters:
        - description: "Tatum X-API-Key used for authorization."
          in: path
          name: xApiKey
          required: true
          schema:
            type: string
            example: asdlkfjnqunalkwjfnq2oi303294857k
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlgoBlock"
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Access Algorand Algod GET node endpoints
      tags:
        - Blockchain / Algorand (ALGO)
    post:
      description: |
        <h4>2 credits per API call.</h4><br/>
        <p>Use this endpoint URL as a http-based url to connect directly to the Algorand node provided by Tatum.
         You can check al available APIs here - <a href="https://developer.algorand.org/docs/rest-apis/algod/v2/" target="_blank">https://developer.algorand.org/docs/rest-apis/algod/v2/</a>.
         <br/>
         Example call for Broadcast a raw transaction is described in the response. <a href="https://developer.algorand.org/docs/rest-apis/algod/v2/#post-v2transactions" target="_blank">https://developer.algorand.org/docs/rest-apis/algod/v2/#post-v2transactions</a>.
         <br/>
         URL used for this call would be <pre>https://api-eu1.tatum.io/v3/algorand/node/algod/YOUR_API_KEY/v2/transactions</pre>
         </p>
      operationId: AlgoNodePostDriver
      parameters:
        - description: "Tatum X-API-Key used for authorization."
          in: path
          name: xApiKey
          required: true
          schema:
            type: string
            example: asdlkfjnqunalkwjfnq2oi303294857k
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rawtxn:
                  type: string
                  description: Check here - <a href="https://developer.algorand.org/docs/rest-apis/algod/v2/#post-v2transactions" target="_blank">https://developer.algorand.org/docs/rest-apis/algod/v2/#post-v2transactions</a>
        required: true
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  txId:
                    type: string
                    description: Check here - <a href="https://developer.algorand.org/docs/rest-apis/algod/v2/#rawtransaction-response-200" target="_blank">https://developer.algorand.org/docs/rest-apis/algod/v2/#rawtransaction-response-200</a>
                    example: X4VI2Q3SHG4RC3T2RNDCFHNPUL6WYX2ONWHJGLKNMBA4SVE5M4KQ
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Access Algorand Algod POST node endpoints
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/account/balance/{address}:
    get:
      description: |
        <h4>1 credit per API call.</h4><br/>
        <p>Get Algorand account balance in ALGO.</p>
      operationId: AlgorandGetBalance
      parameters:
        - description: "Account address"
          in: path
          name: address
          required: true
          schema:
            type: string
            example: "TMETT6BXL3QUH7AH5TS6IONU7LVTLKIGG54CFCNPMQXWGRIZFIESZBYWP4"
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: number
                    description: Balance in ALGO
                    example: 1000
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Get Algorand Account balance
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/block/current:
    get:
      description: "<h4>1 credit per API call.</h4><br/><p>Get Algorand current block number. This is the number of the latest block in the blockchain.</p>"
      operationId: AlgorandGetCurrentBlock
      responses:
        200:
          content:
            application/json:
              schema:
                type: number
                description: Current block number
                example: 16775567
          description: OK
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Get current block number
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/block/{roundNumber}:
    get:
      description: "<h4>1 credit per API call.</h4><br/><p>Get Algorand block by block round number.</p>"
      operationId: AlgorandGetBlock
      parameters:
        - description: "Block round number"
          in: path
          name: roundNumber
          required: true
          schema:
            type: number
            example: 16775567
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlgoBlock"
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Get Algorand block by block round number
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/transaction:
    post:
      description: |
        <h4>2 credits per API call.</h4><br/>
        <p>Send ALGO from account to account.<br/><br/>
        This operation needs the private key of the blockchain address.
        No one should ever send it's own private keys to the internet because there is a strong possibility of stealing keys and loss of funds. In this method, it is possible to enter privateKey
        or signatureId. PrivateKey should be used only for quick development on testnet versions of blockchain when there is no risk of losing funds. In production,
        <a href="https://github.com/tatumio/tatum-kms" target="_blank">Tatum KMS</a> should be used for the highest security standards, and signatureId should be present in the request.
        Alternatively, using the Tatum client library for supported languages.
        </p>
      operationId: AlgorandBlockchainTransfer
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/TransferAlgorandBlockchain"
                - $ref: "#/components/schemas/TransferAlgorandBlockchainKMS"
        required: true
      responses:
        200:
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/TransactionHashKMS"
                  - $ref: "#/components/schemas/SignatureId"
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Send ALGO from account to account
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/transaction/{txid}:
    get:
      description: "<h4>1 credit per API call.</h4><br/><p>Get Algorand transaction by transaction id.</p>"
      operationId: AlgorandGetTransaction
      parameters:
        - description: "Transaction id"
          in: path
          name: txid
          required: true
          schema:
            type: string
            example: "LXEBXIBDAIF72NRI76SU252QSOGFCKEHTG7AI4P6W25V35PETU3Q"
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlgoTx"
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Get Algorand Transaction
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/transactions/{from}/{to}:
    get:
      description: "<h4>1 credit per API call.</h4><br/><p>Get Algorand transaction by specified period of time.</p>"
      operationId: AlgorandGetPayTransactionsByFromTo
      parameters:
        - description: "Start timestamp in specified period of time"
          in: path
          name: from
          required: true
          schema:
            type: string
            example: "2021-05-01T20:44:39Z"
        - description: "End timestamp in specified period of time"
          in: path
          name: to
          required: true
          schema:
            type: string
            example: "2021-06-01T20:44:39Z"
        - description: "page size for pagination"
          in: query
          name: limit
          required: false
          schema:
            type: string
            example: "5"
        - description: "Algorand Next Token for getting the next page results"
          in: query
          name: next
          required: false
          schema:
            type: string
            example: "ywAAAAAAAAAAAAAA"
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlgoTxsWithPagination"
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Get Algorand Transactions between from and to
      tags:
        - Blockchain / Algorand (ALGO)
  /v3/algorand/broadcast:
    post:
      description: |
        <h4>2 credits per API call.</h4><br/>
        <p>Broadcast signed transaction to Algorand blockchain. This method is used internally from Tatum KMS or Tatum client libraries.
        It is possible to create custom signing mechanism and use this method only for broadcasting data to the blockchian.</p>
      operationId: AlgoandBroadcast
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BroadcastKMS"
        required: true
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionHashKMS"
          description: OK
        400:
          <<: *API400
        401:
          <<: *API401
        500:
          <<: *API500
      security:
        - X-Api-Key: [ ]
      x-code-samples:
      summary: Broadcast signed Algorand transaction
      tags:
        - Blockchain / Algorand (ALGO)
components:
  schemas:
    AlgoWallet:
      type: object
      properties:
        address:
          maxLength: 58
          minLength: 58
          description: address of Algorand account.
          example: "NTAESFCB3WOD7SAOL42KSPVARLB3JFA3MNX3AESWHYVT2RMYDVZI6YLG4Y"
          type: string
        secret:
          maxLength: 103
          minLength: 103
          description: secretKey can generate Mnemonic, similar to private Key.
          type: string
          example: NBYMCVEEDFYV3TPWVRE6APE7PKHUJD4XAKXCKNCLKGUXOC3LFNJGZQCJCRA53HB7ZAHF6NFJH2QIVQ5USQNWG35QCJLD4KZ5IWMB24Q
    AlgoBlock:
      type: object
      properties:
        genesisHash:
          description: hash to which this block belongs
          type: string
          example: "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="
        genesisId:
          description: ID to which this block belongs
          type: string
          example: "testnet-v1.0"
        previousBlockHash:
          description: Previous block hash
          type: string
          example: "JeLGQTbqnBsD3NXE8Bf1TpPFMFadEVVyHhkcD61ljAU="
        rewards:
          description: rewards
          type: object
          example: {
            'fee-sink': 'A7NMWS3NT3IUDMLVO26ULGXGIIOUQ3ND2TXSER6EBGRZNOBOUIQXHIBGDE',
            'rewards-calculation-round': 17000000,
            'rewards-level': 27521,
            'rewards-pool': '7777777777777777777777777777777777777777777777777774MSJUVU',
            'rewards-rate': 0,
            'rewards-residue': 2020197303
          }
        round:
          description: Current round on which this block was appended to the chain
          type: number
          example: 16775567
        seed:
          description: Sortition seed.
          type: string
          example: "VPBpyrHyqbfqrHqJ3l39LXGN4qgEdNnE5kpJfk3vJtA="
        timestamp:
          description: Block creation timestamp in seconds since eposh
          type: number
          example: 1632167753
        txns:
          description: Array of transactions
          type: array
          items:
            $ref: "#/components/schemas/AlgoTx"
        txn:
          description: TransactionsRoot authenticates the set of transactions appearing in the block.
          type: string
          example: ++MWW82yIvYQ0AEoPP0aDGGHGk/dSp5WHlbkf9SVU1U=
        txnc:
          description: TxnCounter counts the number of transations committed in the ledger
          type: number
          example: 27814470
        upgradeState:
          description: upgrade state
          type: object
          example: {
            'current-protocol': 'https://github.com/algorandfoundation/specs/tree/abc54f79f9ad679d2d22f0fb9909fb005c16f8a1',
            'next-protocol-approvals': 0,
            'next-protocol-switch-on': 0,
            'next-protocol-vote-before': 0
          }
        upgradeVote:
          description: upgrade vote
          type: object
          example: { 'upgrade-approve': false, 'upgrade-delay': 0 }
    AlgoTx:
      type: object
      properties:
        closeRewards:
          description: rewards applied to close-remainder-to account.
          type: number
          example: 0
        closingAmount:
          description: closing amount for transaction.
          type: number
          example: 0
        confirmedRound:
          description: Round when the transaction was confirmed.
          type: number
          example: 16775567
        fee:
          description: Transaction fee
          type: number
          example: 0.001
        firstValid:
          description: First valid round for this transaction.
          type: number
          example: 16775565
        genesisHash:
          description: Hash of genesis block
          type: string
          example: 'SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI='
        genesisId:
          description: genesis block ID.
          type: string
          example: 'testnet-v1.0'
        id:
          description: transaction ID
          type: string
          example: 'HNIQ76UTJYPOLZP5FWODYABBJPYPGJNEM2QEJSMDMQRWEKHEYJHQ'
        intraRoundOffset:
          description: Offset into the round where this transaction was confirmed.
          type: number
          example: 1
        lastValid:
          description: Last valid round for this transaction.
          type: number
          example: 16775571
        note:
          description: Free form data
          type: string
          example: 'cGluZ3Bvbmf0Jyl21QrtLw=='
        paymentTransaction:
          description: payment Transaction
          type: object
        receiverRewards:
          description: rewards applied to receiver account.
          type: number
          example: 0
        roundTime:
          description: Time when the block this transaction is in was confirmed.
          type: number
          example: 1632167753
        sender:
          description: Sender's address
          type: string
          example: "U6QEM4KM7KKGCLH4FELZBGJEVVSF556ELXHUOZC4ESPFS4O4V4VQXKQRXQ"
        senderRewards:
          description: rewards applied to sender account.
          type: number
          example: 0
        signature:
          description: signature
          type: object
        txType:
          description: indicates what type of transaction this is. Different types have differnet fields.
          type: string
          example: 'pay'
    AlgoTxsWithPagination:
      type: object
      properties:
        nextToken:
          description: Used for pagination, when making another request provide this token with the next parameter.
          type: string
          example: "ywAAAAAAAAAAAAAA"
        transactions:
          description: Array of transactions.
          type: array
          items:
            $ref: "#/components/schemas/AlgoTx"
    TransferAlgorandBlockchain:
      type: object
      properties:
        from:
          description: Blockchain sender address.
          type: string
          example: "TMETT6BXL3QUH7AH5TS6IONU7LVTLKIGG54CFCNPMQXWGRIZFIESZBYWP4"
        to:
          description: Blockchain address to send algo
          type: string
          example: "NTAESFCB3WOD7SAOL42KSPVARLB3JFA3MNX3AESWHYVT2RMYDVZI6YLG4Y"
        fee:
          description: Transaction fee in Algos.
          type: string
          example: "0.001"
        amount:
          description: Amount to be sent in Algos.
          type: string
          example: "1"
        note:
          description: "Helloworld"
          type: string
        fromPrivateKey:
          description: Private key of sender address. Private key, or signature Id must be present.
          type: string
          example: "72TCV5BRQPBMSAFPYO3CPWVDBYWNGAYNMTW5QHENOMQF7I6QLNMJWCJZ7A3V5YKD7QD6ZZPEHG2PV2ZVVEDDO6BCRGXWIL3DIUMSUCI"
      required:
        - from
        - to
        - amount
        - fromPrivateKey
    TransferAlgorandBlockchainKMS:
      type: object
      properties:
        from:
          description: Blockchain sender address.
          type: string
          example: "TMETT6BXL3QUH7AH5TS6IONU7LVTLKIGG54CFCNPMQXWGRIZFIESZBYWP4"
        to:
          description: Blockchain address to send algo
          type: string
          example: "NTAESFCB3WOD7SAOL42KSPVARLB3JFA3MNX3AESWHYVT2RMYDVZI6YLG4Y"
        fee:
          description: Transaction fee in MicroAlgos.
          type: string
          example: "1000"
        amount:
          description: Amount to be sent in MicroAlgos.
          type: string
          example: "100000"
        note:
          description: "Helloworld"
          type: string
        index:
          type: number
          minimum: 0
          description: If signatureId is mnemonic-based, this is the index to the specific address from that mnemonic.
        signatureId:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
          example: 26d3883e-4e17-48b3-a0ee-09a3e484ac83
          description: Identifier of the private key associated in signing application. Private key, or signature Id must be present.
      required:
        - from
        - to
        - amount
        - signatureId