V2 User Endpoint

  • Access to the API is limited to 150 requests / minutes / ip.
  • All API responses are cached for 2 minutes.
  • All endpoints are CORS enabled.
  • Endpoint: https://api.grinmint.com
  • Dashboard

    Returns json data about a single user dashboard.

  • URL

    /v2/user/:user/dashboard

  • Method:

    GET

  • URL Params

    Required:

    user=[string]

  • Data Params:

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      status bool Response status
      last_seen string Last time the user submitted a share
      statistics []object User mining statistics
      - algorithm string Name of the algorithm stats
      - current_hashrate number Current user hashrate for this algorithm
      - average_hashrate number Current user average hashrate for this algorithm
      - valid_shares number Number of valid shares submitted for this algorithm
      - invalid_shares number Number of invalid shares submitted for this algorithm
      - stale_shares number Number of stale shares submitted for this algorithm
      workers []object Array of workers
      - name string Name of the worker
      - agent string Agent of the worker
      - last_seen string Last time the user submitted a share
      - statistics []object Array of algorithm statistics for this worker
      -- algorithm string Name of the algorithm stats
      -- current_hashrate number Current user hashrate for this algorithm
      -- average_hashrate number Current user average hashrate for this algorithm
      -- valid_shares number Number of valid shares submitted for this algorithm
      -- invalid_shares number Number of invalid shares submitted for this algorithm
      -- stale_shares number Number of stale shares submitted for this algorithm
      settings object User settings
      - monitor bool If monitoring is enabled or not
      - wallet string Anonymized user wallet address
      - limited bool Whether the account is in limited mode
      active_workers number Number of active workers
      immature_balance number Immature user balance
      unpaid_balance number Unpaid user balance
      total_paid number Total number of grins paid
      total_mined number Total number of grins mined
  • Error Response:

    • Code: 404 or 500

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/dashboard",
        dataType: "json",
        type : "GET",
        success : function(r) {
          console.log(r);
        }
      });
  • User Stats
    Returns json data containing various statistics about a specific user.
  • URL

    /v2/user/:user/userStats

  • Method:

    GET

  • URL Params

    Required:

    user=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      status bool Response status
      last_seen string Last time the user submitted a share
      statistics []object User mining statistics
      - algorithm string Name of the algorithm stats
      - current_hashrate number Current user hashrate for this algorithm
      - average_hashrate number Current user average hashrate for this algorithm
      - valid_shares number Number of valid shares submitted for this algorithm
      - invalid_shares number Number of invalid shares submitted for this algorithm
      active_workers number Number of active workers
      immature_balance number Immature user balance
      unpaid_balance number Unpaid user balance
      total_paid number Total number of grins paid
      total_mined number Total number of grins mined
  • Error Response:

    • Code: 404 or 500

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/userStats",
        dataType: "json",
        type : "GET",
        success : function(r) {
          console.log(r);
        }
      });
  • User History

    Get a list of user historical hashrates from the pool.

  • URL

    /v2/user/:user/userHistory

  • Method:

    GET

  • URL Params

    Required:

    user=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      status bool Response status
      hashrates []object Array of PoW hashrates data
      - time number Time of the data
      - hashrates number Array ([c29, c31, c32, c33]) of hashrates at that time
      - average_hashrates number Array ([c29, c31, c32, c33]) of average hashrates at that time
  • Error Response:

    • Code: 404 or 500

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/userHistory",
        dataType: "json",
        type : "GET",
        success : function(r) {
          console.log(r);
        }
      });
  • Payout Stats

    Get the list of payouts from the pool.

  • URL

    /v2/user/:user/payoutStats

  • Method:

    GET

  • URL Params

    Required:

    user=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      status bool Response status
      payouts []object List of last 100 payouts
      - paid_on number Paid on
      - amount number Amount sent
      - tx_id string Transaction ID
      - commit string Output commitment
      - status string Status of the payout
  • Error Response:

    • Code: 404 or 500

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/payoutStats",
        dataType: "json",
        type : "GET",
        success : function(r) {
          console.log(r);
        }
      });
  • Payout History

    Get the list of payouts per block from the pool.

  • URL

    /v2/user/:user/payoutHistory

  • Method:

    GET

  • URL Params

    Required:

    user=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      status bool Response status
      payouts []object List of last 100 payouts
      - height number Height of the block
      - amount number Amount paid
  • Error Response:

    • Code: 404 or 500

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/payoutHistory",
        dataType: "json",
        type : "GET",
        success : function(r) {
          console.log(r);
        }
      });
  • User Settings

    Get the user settings.

  • URL

    /v2/user/:user/userSettings

  • Method:

    GET

  • URL Params

    Required:

    user=[string]

  • Data Params

    None

  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      status bool Response status
      wallet string Anonymized user wallet address
      monitor bool Whether monitoring is enabled
  • Error Response:

    • Code: 404 or 500

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/userSettings",
        dataType: "json",
        type : "GET",
        success : function(r) {
          console.log(r);
        }
      });
  • Update User Settings

    Update user settings. Whether to enable monitoring on workers or set/update the wallet address to receive HTTP payouts. If monitoring is true, you'll receive an email every time one of your worker goes down.

  • URL

    /v2/user/:user/updateUserSettings

  • Method:

    POST

  • URL Params

    Required:

    • user=[string]
  • Data Params

    Required:

    • password=[string]
    • monitor=[bool]
    • wallet=[string]
  • Success Response:

    • Code: 200

    • Content:

      Field Type Description
      status bool Response status
      monitor bool Whether monitoring is enabled
      limited bool Whether the account is in limited mode
  • Error Response:

    • Code: 404 or 500

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      var bodyParams = {
        monitor: true,
        wallet: "192.168.1.1:3415",
        password: "iamvoldemort"
      }
      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/updateUserSettings",
        dataType: "json",
        type : "POST",
        contentType: 'application/json',
        success : function(r) {
          console.log(r);
        },
        data: JSON.stringify(bodyParams)
      });
  • Request Payout

    Request a payout from the pool. The pool will send it to you as soon as the wallet is available.
    Minimum payout is 1 grin.
    Currently two payout methods are supported:

    • Http: the pool wallet will send the transaction directly to your Grin node. Your wallet must be reachable from the internet.
    • Email: the pool wallet will send you an email with a file transaction. Then you must import the transaction in your wallet with the grin wallet receive command. Finally, you must upload the output file using our website page or using the finalizeTransaction endpoint.

  • URL

    /v2/user/:user/requestPayout

  • Method:

    POST

  • URL Params

    Required:

    user=[string]

  • Data Params

    Required:

    method=[string]

    password=[string]

  • Success Response:

    • Code: 200

    • Content:

      Field Type Value Description
      status bool true Response status
      amount number Amount sent
  • Error Response:

    • Code: 404, 500 or 503

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      var bodyParams = {
        method: "email",
        password: "iamvoldemort",
      }
      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/requestPayout",
        dataType: "json",
        contentType: 'application/json',
        type : "POST",
        success : function(r) {
          console.log(r);
        },
        data: JSON.stringify(bodyParams)
      });
  • Finalize Payout

    Finalize payout endpoint. Specifically designed for email payouts. When you receive a payout by email you have to receive it in Grin. Then you need to upload the created response transaction on Grinmint with this endpoint in order to finalize the payout.

  • URL

    /v2/user/:user/finalizePayout

  • Method:

    POST

  • URL Params

    Required:

    user=[string]

  • Data Params

    Required:

    password=[string]

    tx=[string]

    A transaction slate in JSON.

    Field Type Description
    num_participants number The number of participants intended to take part in this transaction
    id number Unique transaction ID, selected by sender
    tx object The core transaction data (inputs, outputs, kernels and kernel offset)
    - offset []number The kernel “offset” k2, excess is k1G after splitting the key k = k1 + k2
    - body object The transaction body - inputs/outputs/kernels
    - - inputs []object List of inputs spent by the transaction
    - - - features object The features of the output being spent
    - - - commit []number The commit referencing the output being spent
    - - outputs []object List of outputs the transaction produces
    - - - features object Options for an output’s structure or use
    - - - commit []number The homomorphic commitment representing the output amount
    - - - proof []number A proof that the commitment is in the right range
    - - kernels []object List of kernels that make up this transaction (usually a single kernel)
    - - - features object Options for a kernel’s structure or use
    - - - fee number Fee originally included in the transaction this proof is for
    - - - lock_height number The max lock_height of all inputs to this transaction
    - - - excess []number Remainder of the sum of all transaction commitments
    - - - excess_sig []number The signature proving the excess is a valid public key (signs the tx fee)
    amount number Base amount (excluding fee)
    fee number Fee amount
    height number Block height for the transaction
    lock_height number Lock height
    participant_data object Participant data
    - id number Id of participant in the transaction. (For now, 0=sender, 1=rec)
    - public_blind_excess []number Public key corresponding to private blinding factor
    - public_nonce []number Public key corresponding to private nonce
    - part_sig []number Public partial signature
  • Success Response:

    • Code: 200

    • Content:

      Field Type Value Description
      status bool true Response status
      amount number Amount sent
  • Error Response:

    • Code: 404, 500 or 503

    • Content:

      Field Type Description
      status bool Response status
      message string Reason for error
  • Sample Call:

      $.ajax({
        url: "/v2/user/quentin@blockcypher.com/finalizePayout",
        dataType: "json",
        contentType: 'application/json',
        type : "POST",
        success : function(r) {
          console.log(r);
        },
        data: {
          password: "iamvoldemort"
          tx: tx.response.json
        },
      });
  • Grin is an experimental coin: use at your own risk! Grinmint does not guarantee any return on mining time or hashpower. You are strongly encouraged to move your rewards off the pool as often as possible into a wallet that you control. Although Grinmint takes multiple precautions to keep our users' coins safe, we do not offer any guarantee against hacks or loss. Grinmint is not a wallet. You, the user, assume the risk for any coins left on Grinmint. 60 days after coin maturity, your coins are considered expired and you will no longer be able to request payouts for them.