swagger.yml

openapi: 3.0.0
x-logo: true

servers:
  - url: https://api-mon.ethplorer.io
#  - url: https://--.ethplorer.io
#  - url: https://-.ethplorer.io

info:
  version: 0.5.0
  title: Bulk API Monitor Guide
  description: |
    # Introduction

    The Bulk API Monitor allows tracking unlimited number of ethereum tokens and addresses, even hundreds of thousands or millions. A minimal resources and coding is enough. Just inserting the addresses or contracts needed for monitoring into pools will return all operations related to these addresses right after any transaction in them happens.

    This tool is Ideal for wallets, address monitoring services, exchanges, airdrops and other services that work with a large number of blockchain addresses.

    *By using Ethplorer code fully or partially, API, widgets or any other service on your website or app you hereby agree with [Terms of Usage and Privacy Policy](https://ethplorer.io/privacy)*

    # Common Use Cases

    ## Track transactions for a list of addresses

    * Create a pool with your API key, save pool-id.
    * Add addresses to the pool using pool-id (you may also do it at same request with the pool creation).
    * Ask getPoolLastOperations every minute and set the period to 2-5 minutes to avoid missing any operations.
        * You will receive all ERC20 token operations for any address in the pool for the specified time period.
        * Skip operations with blocks you processed before.
        * Transaction will return token value of operation, token balance of the address and contract address of the ERC20 token.
        * Keep the block numbers or operation’s hashes to avoid duplicates.
        * Request any additional info about the address or token using general API if necessary.
        * Caching contract information is recommended.
    * If you need to also monitor ETH transactions, then ask getPoolLastTransactions every minute and set the period to 2-5 minutes to avoid missing transactions.
        * Make same steps as with ERC20 operations, but with ETH balances.
    * Add new address or delete existing one from the pool if necessary.
    * If you missed some time period of monitoring you may request a wider time range using larger period value. It’s not recommended to do it without a reason.

    ## Track a limited number of tokens

    Add the contract addresses of observed tokens to the pool using your API key and pool-id. Let’s call it General List. Once done, you will see ALL operations related to these tokens for all addresses regardless if these addresses were added to the pool.

    ## Track a large number of addresses but a limited number of tokens

    If you have a number of addresses where you want to track all their token operations (not only those from the General List), you can manually add them to the same pool where the General List is stored. (No need to add addresses included in General List). As result, you will get all operations for the General List tokens and all operations for non-General list addresses, regardless of what token they have.

    # Billing and limits for the API monitor

    ** tick = credit point*

    There are a few things to know about how your API key is billed:

    * Each transaction or operation is monitored in your pools: 10 ticks per every operation, which is found using set address, and 1 tick for each operation found using token address.
    * Calculation of the number of addresses and contracts in your pools per day: 10 ticks per every contract or 10 ticks per 100 addresses daily (whole or not)
    * Creating a pool: 1000 ticks per each (no charge at the moment).
    * Put address or contract into a pool: 10 ticks per address, 100 ticks per contract (no charge at the moment).

    Note, that adding any popular contract (USDT for example) or address (address of a popular exchange for example) to the pool will produce a lot of transactions and most likely burn your balance

    Average daily count of transaction in Ethereum blockchain is 500k. This is not the same for token operations, but it’s recommended to have this data for your future references. 


    ## Billing plans

    **Basic**: 9$/Month up to 50,000 ticks/month
    **Medium**: 99$/Month up to 1,000,000 ticks/month
    **Advanced**: 499$/Month, up to 10,000,000 ticks/month
    **Ultimate**: 999$/Month, up to 100,000,000 ticks/month

    ## Calculation examples

    **Tracking 1000 of addresses and 10 tokens** which produce about 100 transactions or operations per day (50 of these produced via tokens).
    Pool charge: 10 ticks * 10 + 10 ticks * 1000/100 = 200 ticks/day
    Transactions charge: 10 ticks * 50 + 1 tick * 50 = 550 ticks/day
    Monthly amount: 200*30+550*30 = **22,500 ticks/month**

    **Tracking 100k of addresses and 10 contracts** which produces about 1000 transactions or operations per day (500 of these produced via tokens).

    Pool charge: 10 ticks * 10 + 10 ticks * 100000/100 = 10,100 ticks/day
    Transactions charge: 10 ticks * 500 + 1 tick * 500= 5,500 ticks/day
    Monthly amount: 10100*30+5500*30 = **468,000 ticks/month**

    **Tracking 100k of addresses and 100 contracts** which produces about 50k transactions or operations per day  (40k of these produced via tokens)..

    Pool charge: 10 ticks * 100 + 10 ticks * 100000/100 = 11,000 ticks/day
    Transactions charge: 10 ticks * 10000 + 1 tick *40000 = 140,000 ticks/day
    Monthly amount: 11000*30+140000*30 =** 4,530,000 ticks/month**

    **Tracking 1000k of addresses and 1000 contracts** which produces about 500k transactions or operations per day (300k of these produced via tokens).

    Pool charge: 10 ticks * 1000 + 10 ticks * 1000000/100 = 110,000 ticks/day
    Transactions charge: 10 ticks * 200000 + 1 tick * 300000 = 2,300,000 ticks/day
    Monthly amount: 110000*30+2300000*30 =** 72,300,000 ticks/month**

    **the above fee estimations does not include creating pools and address changes within the pools.*

    # API Servers, mainnet/testnet

    Target domains:
    https://api-mon.ethplorer.io/  for mainnet;
     [https://kovan.api-mon.ethplorer.io](https://kovan.api-mon.ethplorer.io/) for testnet (Kovan).

    Pools databases are individual for each type of network.

    Each request should have a mandatory apiKey parameter.



  # termsOfService: 'http://swagger.io/terms/'
  # license:
  #   name: Apache 2.0
  #   url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

tags:
  - name: "Bulk API Monitor Endpoints"

paths:
  /createPool:
    post:
      x-code-samples:
        - lang: cURL
          source: 'curl -X POST "https://api-mon.ethplorer.io/createPool" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "apiKey=yourApiKey&addresses=0xb2930b35844a230f00e51431acae96fe543a0347%2C0xb52d3141ee731fac89927476c6a5207b37cd72ff"'
      summary: Create pool
      description: Create new pool description
      tags:
        - "Bulk API Monitor Endpoints"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                apiKey:
                  $ref: '#/components/schemas/ApiKey'
                addresses:
                  $ref: '#/components/schemas/Addresses'
              required:
                - apiKey
      responses:
        '200':
          $ref: '#/components/responses/PoolCreated'
        '400':
          description: Some shit happens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 106
                message: "Internal error"
        '403':
          $ref: '#/components/responses/Unauthorized'
  /deletePool:
    post:
      x-code-samples:
        - lang: cURL
          source: 'curl -X POST "https://api-mon.ethplorer.io/deletePool" -H "accept: */*" -H "Content-Type: application/x-www-form-urlencoded" -d "apiKey=yourApiKey&poolId=a7b87103-70a8-4804-8eb6-66314dea4ef5"'
      summary: Delete pool
      description: Delete created pool
      tags:
        - "Bulk API Monitor Endpoints"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                apiKey:
                  $ref: '#/components/schemas/ApiKey'
                poolId:
                  $ref: '#/components/schemas/PoolId'
              required:
                - apiKey
                - poolId
      responses:
        '200':
          $ref: '#/components/responses/PoolDeleted'
        '400':
          $ref: '#/components/responses/PoolResponse'
        '403':
          $ref: '#/components/responses/Unauthorized'
  /addPoolAddresses:
    post:
      x-code-samples:
        - lang: cURL
          source: 'curl -X POST "https://api-mon.ethplorer.io/addPoolAddresses" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "apiKey=yourApiKey&addresses=0xb2930b35844a230f00e51431acae96fe543a0347&poolId=a7b87103-70a8-4804-8eb6-66314dea4ef5"'
      summary: Add addresses to the pool
      description: Add new addresses to already created pool
      tags:
        - "Bulk API Monitor Endpoints"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                apiKey:
                  $ref: '#/components/schemas/ApiKey'
                addresses:
                  $ref: '#/components/schemas/Addresses'
                poolId:
                  $ref: '#/components/schemas/PoolId'
              required:
                - apiKey
                - addresses
                - poolId
      responses:
        '200':
          $ref: '#/components/responses/PoolAddressesAdded'
        '400':
          description: Responses for adding new addresses to the pool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                poolIdRequired:
                  description: Field poolId is required
                  value:
                    code: 107
                    message: "Field poolId is required"
                badRequest:
                  description: Bad request
                  value:
                    code: 109
                    message: "Bad request"
                internalError:
                  description: Internal error
                  value:
                    code: 106
                    message: "Internal error"
                poolNotFound:
                  description: Pool not found
                  value:
                    code: 114
                    message: "Pool not found"
                addressesRequired:
                  description: Field addresses is required
                  value:
                    code: 111
                    message: "Field addresses is required"
                invalidAddress:
                  description: One or more addresses is not invalid
                  value:
                    code: 112
                    message: "One or more addresses is not invalid"
                contractAddress:
                  description: You can not use contract addresses
                  value:
                    code: 115
                    message: "You can not use contract addresses"
                reachedLimit:
                  description: Pool capacity limit reached
                  value:
                    code: 116
                    message: "Pool capacity limit reached"
        '403':
          $ref: '#/components/responses/Unauthorized'
  /clearPoolAddresses:
    post:
      x-code-samples:
        - lang: cURL
          source: 'curl -X POST "https://api-mon.ethplorer.io/clearPoolAddresses" -H "accept: */*" -H "Content-Type: application/x-www-form-urlencoded" -d "apiKey=yourApiKey&poolId=a7b87103-70a8-4804-8eb6-66314dea4ef5"'
      summary: Clear pool
      description: Delete all addresses from the pool
      tags:
        - "Bulk API Monitor Endpoints"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                apiKey:
                  $ref: '#/components/schemas/ApiKey'
                poolId:
                  $ref: '#/components/schemas/PoolId'
              required:
                - apiKey
                - poolId
      responses:
        '200':
          $ref: '#/components/responses/PoolCleared'
        '400':
          $ref: '#/components/responses/PoolResponse'
        '403':
          $ref: '#/components/responses/Unauthorized'
  /deletePoolAddresses:
    post:
      x-code-samples:
        - lang: cURL
          source: 'curl -X POST "https://api-mon.ethplorer.io/deletePoolAddresses" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "apiKey=yourApiKey&addresses=0xb2930b35844a230f00e51431acae96fe543a0347&poolId=a7b87103-70a8-4804-8eb6-66314dea4ef5"'
      summary: Remove addresses from the pool
      description: Remove addresses from already created pool
      tags:
        - "Bulk API Monitor Endpoints"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                apiKey:
                  $ref: '#/components/schemas/ApiKey'
                addresses:
                  $ref: '#/components/schemas/Addresses'
                poolId:
                  $ref: '#/components/schemas/PoolId'
              required:
                - apiKey
                - addresses
                - poolId
      responses:
        '200':
          $ref: '#/components/responses/PoolAddressesDeleted'
        '400':
          description: Responses for removing addresses from the pool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                poolIdRequired:
                  description: Field poolId is required
                  value:
                    code: 107
                    message: "Field poolId is required"
                badRequest:
                  description: Bad request
                  value:
                    code: 109
                    message: "Bad request"
                internalError:
                  description: Internal error
                  value:
                    code: 106
                    message: "Internal error"
                poolNotFound:
                  description: Pool not found
                  value:
                    code: 114
                    message: "Pool not found"
                addressesRequired:
                  description: Field addresses is required
                  value:
                    code: 111
                    message: "Field addresses is required"
                invalidAddress:
                  description: One or more addresses is not invalid
                  value:
                    code: 112
                    message: "One or more addresses is not invalid"
        '403':
          $ref: '#/components/responses/Unauthorized'
  /getPoolAddresses/{poolId}:
    get:
      x-code-samples:
        - lang: cURL
          source: 'curl -X GET "https://api-mon.ethplorer.io/getPoolAddresses/a7b87103-70a8-4804-8eb6-66314dea4ef5?apiKey=yourApiKey" -H "accept: application/json"'
      summary: Get list of the pool addresses
      description: Get list of the pool addresses
      tags:
        - "Bulk API Monitor Endpoints"
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/PoolId'
      responses:
        '200':
          $ref: '#/components/responses/PoolAddresses'
        '400':
          $ref: '#/components/responses/PoolNotFound'
        '403':
          $ref: '#/components/responses/Unauthorized'
  /getPoolLastOperations/{poolId}:
    get:
      x-code-samples:
        - lang: cURL
          source: 'curl -X GET "https://api-mon.ethplorer.io/getPoolLastOperations/a7b87103-70a8-4804-8eb6-66314dea4ef5?apiKey=yourApiKey" -H "accept: application/json"'
      summary: Get pool last operations
      description: Get list of the pool last operations
      tags:
        - "Bulk API Monitor Endpoints"
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/PoolId'
      responses:
        '200':
          $ref: '#/components/responses/PoolData'
        '400':
          $ref: '#/components/responses/PoolNotFound'
        '403':
          $ref: '#/components/responses/Unauthorized'
  /getPoolLastTransactions/{poolId}:
    get:
      x-code-samples:
        - lang: cURL
          source: 'curl -X GET "https://api-mon.ethplorer.io/getPoolLastTransactions/a7b87103-70a8-4804-8eb6-66314dea4ef5?apiKey=yourApiKey" -H "accept: application/json"'
      summary: Get pool last transactions
      description: Get list of the pool last transactions
      tags:
        - "Bulk API Monitor Endpoints"
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/PoolId'
      responses:
        '200':
          $ref: '#/components/responses/PoolData'
        '400':
          $ref: '#/components/responses/PoolNotFound'
        '403':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    PoolId:
      description: Id of the created pool. Has a uuid format.
      in: path
      name: poolId
      required: true
      schema:
        type: string
        format: uuid
      example: 'a7b87103-70a8-4804-8eb6-66314dea4ef5'
    ApiKey:
      description: Api key to access the service.
      in: query
      name: apiKey
      required: true
      schema:
        type: string
      example: 'yourApiKey'
  responses:
    Unauthorized:
      description: Invalid api key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
              code: 1
              message: "Invalid API key"
    PoolResponse:
      description: Response for pool operations
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            poolIdRequired:
              description: Field poolId is required
              value:
                code: 107
                message: "Field poolId is required"
            badRequest:
              description: Bad request
              value:
                code: 109
                message: "Bad request"
            internalError:
              description: Internal error
              value:
                code: 106
                message: "Internal error"
            poolNotFound:
              description: Pool not found
              value:
                code: 114
                message: "Pool not found"
    PoolNotFound:
      description: Requested poolId not found in the database
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
              code: 114
              message: "Pool not found"
    PoolCreated:
      description: Pool created response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PoolCreatedResponse'
          examples:
            addressAdded:
              value:
                addedAddresses: 1
            addressNotAdded:
              value:
                addedAddresses: 0
    PoolAddresses:
      description: Returns list of comma-separated string with addresses of the pool.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PoolAddressesResponse'
          examples:
            poolWithAddresses:
              value:
                addedAddresses: "0xb2930b35844a230f00e51431acae96fe543a0347,0xb52d3141ee731fac89927476c6a5207b37cd72ff"
            emptyPool:
              value:
                addresses: ""
    PoolAddressesAdded:
      description: Pool addresses added successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PoolAddressesAddedResponse'
          examples:
            created:
              value:
                poolId: "a7b87103-70a8-4804-8eb6-66314dea4ef5"
            createdWithAddresses:
              value:
                poolId: "a7b87103-70a8-4804-8eb6-66314dea4ef5"
    PoolAddressesDeleted:
      description: Addresses removed from the pool successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PoolAddressesDeletedResponse'
          examples:
            address:
              value:
                address: "0xb2930b35844a230f00e51431acae96fe543a0347"
            addressesNotDeleted:
              value:
                deletedAddresses: 0
    PoolData:
      description: List of the pool data by addresses
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PoolDataResponse'
    PoolDeleted:
      description: Pool was deleted successfully
    PoolCleared:
      description: All addresses from pool was removed successfully
  schemas:
    ApiKey:
      description: Api key to access the service.
      type: string
      example: "yourApiKey"
    PoolId:
      description: Id of the created pool. Has a uuid format.
      type: string
      format: uuid
      example: 'a7b87103-70a8-4804-8eb6-66314dea4ef5'
    Addresses:
      description: A comma-separated string of addresses. Ignoring zero ethreium address, contract addresses, invalid addresses, duplicated addresses. Has a limit - 100000 addresses per one request.
      type: string
      example: "0xb2930b35844a230f00e51431acae96fe543a0347,0xb52d3141ee731fac89927476c6a5207b37cd72ff"
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
          required:
            - code
            - message
    PoolCreatedResponse:
      type: object
      properties:
        poolId:
          type: string
        createdAddresses:
          type: integer
      required:
        - poolId
        - createdAddresses
    PoolAddressesDeletedResponse:
      type: object
      properties:
        deletedAddresses:
          type: integer
      required:
        - deletedAddresses
    PoolAddressesAddedResponse:
      type: object
      properties:
        addedAddresses:
          type: integer
      required:
        - addedAddresses
    PoolAddressesResponse:
      type: object
      properties:
        addresses:
          type: string
      required:
        - addresses
    PoolDataResponse:
      type: object
      properties:
        "0xb2930b35844a230f00e51431acae96fe543a0347":
          type: array
          items:
            type: object
            properties:
              timestamp:
                type: integer
                example: 1517319693
              from:
                type: string
                example: "0xb2930b35844a230f00e51431acae96fe543a0347"
              to:
                type: string
                example: "0xb52d3141ee731fac89927476c6a5207b37cd72ff"
              hash:
                type: string
                example: "0xc3ef85864e9dd0b65c822416dc882da379cebb947deb3f01ca950a1d737d1317"
              value:
                type: string
                example: "0.11755697"
              input:
                type: string
                example: "0x"
              success:
                type: boolean
                example: true