Documentation
API
Monetary System

Monetary System Operations

Can Delete Currency

Determine if a currency can be deleted.

Request:

  • requestType is canDeleteCurrency
  • account is the account ID
  • currency is the currency ID
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • canDelete (B) is true if the currency can be deleted, false otherwise
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Note: a currency can be deleted only when all units of the currency are held by account. A reservable currency that has not yet been issued can be deleted by the issuer. A mintable currency that has not completed minting cannot be deleted by a non-issuer.

Example: Refer to Can Delete Currency example.

Currency Buy / Sell

Make an exchange request to buy or sell an exchangeable currency. POST only.

Request: Refer to Create Transaction Request for common parameters.

  • requestType is currencyBuy or currencySell
  • currency is the currency ID
  • rateNQT is the exchange rate (in NQT per QNT)
  • units is the amount of the currency to buy or sell (in QNT)

Note: An exchange request is immediately executed once accepted onto the blockchain based only on currently available offers (refer to Publish Exchange Offer). The request then expires, regardless of the amount of currency exchanged; the request may be completely filled, partially filled, or expire without any exchange if no matching offers are found.

Response: Refer to Create Transaction Response.

Example: Refer to Currency Buy / Sell example.

Currency Buy

Refer to Currency Buy / Sell.

Currency Sell

Refer to Currency Buy / Sell.

Currency Mint

Submit a valid computed nonce to the blockchain in return for newly minted currency. POST only.

Request: Refer to Create Transaction Request for common parameters.

  • requestType is currencyMint
  • currency is the mintable currency ID
  • nonce is the computed nonce
  • units is the amount (in QNT) of currency to mint
  • counter (N) is the counter associated with the minting account

Note: The hash of nonce must be less than targetBytes provided by Get Minting Target for given units and counter. counter must be increased with each submission.

Response: Refer to Create Transaction Response.

Example: Refer to Currency Mint example.

Currency Reserve Claim

Claim currency reserve. POST only.

Request: Refer to Create Transaction Request for common parameters.

  • requestType is currencyReserveClaim
  • currency is the currency ID
  • units is the amount (in QNT) of reserve currency to claim

Note: Holders of a claimable currency may claim the locked NQT backing their units, thus reducing the supply of the currency.

Response: Refer to Create Transaction Response.

Example: Refer to Currency Reserve Claim example.

Currency Reserve Increase

Increase the currency reserve of an unissued reservable currency. POST only.

Request: Refer to Create Transaction Request for common parameters.

  • requestType is currencyReserveIncrease
  • currency is the currency ID
  • amountPerUnitNQT is the additional amount (in NQT per QNT of reserveSupply) to reserve (refer to Issue Currency)

Note: An additional amountPerUnitNQT * reserveSupply NQT (beyond what has previously been reserved) will be locked until the issuanceHeight is reached. Upon issuance, if the currency is claimable the NQT will remain locked until claimed; otherwise the NQT will transfer to the issuing account. Also upon issuance, a portion of the reserveSupply QNT will be transfered to each reserving account in proportion to the NQT that was contributed.

Response: Refer to Create Transaction Response.

Example: Refer to Currency Reserve Increase example.

Delete Currency

Delete a deletable currency (refer to Can Delete Currency). POST only.

Request: Refer to Create Transaction Request for common parameters.

  • requestType is deleteCurrency
  • currency is the currency ID

Response: Refer to Create Transaction Response.

Example: Refer to Delete Currency example.

Get Account Currencies

Get the currencies issued by a given account.

Request:

  • requestType is getAccountCurrencies
  • account is the account ID
  • currency is a currency ID filter (optional)
  • height is the blockchain height at which the response applies (optional, default is the current height)
  • includeCurrencyInfo is true if several currency information properties is to be included (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • accountCurrencies (A) is an array of currency objects with the following fields:
    • code (S) is the currency code
    • unconfirmedUnits (S) is the amount of unconfirmed currency units (in QNT)
    • decimals (N) is the number of currency decimal places
    • name (S) is the currency name
    • currency (S) is the currency ID
    • units (S) is the amount of currency (in QNT)
    • issuanceHeight (N) is the blockchain height of issuance for a reservable currency
    • type (N) is the currency type bitmask (refer to Get Currency)
    • issuerAccountRS (S) is the Reed-Solomon address of the issuer account
    • issuerAccount (S) is the issuer account ID
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Account Currencies example.

Get Account Currency Count

Get the number of currencies issued by a given account.

Request:

  • requestType is getAccountCurrencyCount
  • account is the account ID
  • height is the blockchain height at which the response applies (optional, default is the current height)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • numberOfCurrencies (N) is the number of currencies issued
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Account Currency Count example.

Get Account Exchange Requests

Get the exchange requests associated with a given account and/or currency in reverse chronological order (or in expected order of execution for expected requests).

Request:

  • requestType is either getAccountExchangeRequests or getExpectedExchangeRequests, where expected requests are from the unconfirmed transactions pool or are phased transactions scheduled to finish in the next block
  • account is the account ID (optional for expected requests)
  • currency is the currency ID (optional for expected requests if account provided)
  • includeCurrencyInfo is true to include the response fields code, decimals, name, issuanceHeight, type, timestamp, issuerAccountRS and issuerAccount (optional, applies only to expected requests)
  • firstIndex is a zero-based index to the first request to retrieve (optional, does not apply to expected requests)
  • lastIndex is a zero-based index to the last request to retrieve (optional, does not apply to expected requests)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • exchangeRequests (A) is an array of requests with the following fields for each request:
    • code (S) is a currency code
    • subtype (N) is 5 for buy and 6 for sell
    • decimals (N) is the number of decimal places
    • name (S) is the currency name
    • units (S) is the number of currency units to buy or sell (in QNT)
    • issuanceHeight (N) is the blockchain height of issuance for a reservable currency, zero otherwise
    • type (N) is the currency type bitmask (refer to Get Currency)
    • transaction (S) is the transaction ID
    • timestamp (N) is the timestamp (in seconds since the genesis block) of the block when the request was executed
    • rateNQT (S) is the exchange rate (in NQT per QNT)
    • issuerAccountRS (S) is the Reed-Solomon address of the issuer account
    • issuerAccount (S) is the issuer account ID
    • phased (B) is true if the transaction is phased (applies only to expected requests)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Account Exchange Requests example.

Get Expected Exchange Requests

Refer to Get Account Exchange Requests.

Get Funding Monitor

Get a funding monitor.

Request:

  • requestType is getFundingMonitor
  • secretPhrase is the secret phrase of the funding account, used to get a single monitor. (optional)
  • adminPassword is the admin password, used to get a single monitor or all monitors (optional if secretPhrase is provided)
  • includeMonitoredAccounts is true to include account info of the monitored accounts (optional)
  • property is the name of the account property (optional)
  • holdingType is a string representing the holding type (optional)
  • holding is the holding ID (optional)
  • account is the account ID (optional)

Response:

  • monitors (A) is an array of monitor objects including the following fields:
    • holding (S) is the holding ID
    • amount (S) is the amount to fund the monitored accounts with (NQT or QNT)
    • monitoredAccounts (A) is an array of monitored account objects including the following fields (only if includeMonitoredAccounts is true):
      • amount (S) is the amount to fund the monitored accounts with. Overrides amount in parent object.
      • account (S) is the monitored account ID
      • accountRS (S) is the monitored account Reed Solomon address
      • threshold (S) is the threshold. Overrides threshold in parent object.
      • interval (N) is the interval. Overrides interval in parent object.
    • holdingType (N) is the holding type
    • account (S) is the monitoring account ID
    • accountRS (S) is the Reed Solomon address of the monitoring account
    • property (S) is the account property
    • threshold (S) is the threshold
    • interval (N) is the interval
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Funding Monitor example.

Get All Currencies

Get all currencies in reverse creation order.

Request:

  • requestType is getAllCurrencies
  • firstIndex is a zero-based index to the first currency to retrieve (optional)
  • lastIndex is a zero-based index to the last currency to retrieve (optional)
  • includeCounts is true to include numberOf... fields (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • currencies (A) is an array of currency objects (refer to Get Currency for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get All Currencies example.

Get All Exchanges

Get all currency exchanges in reverse chronological order.

Request:

  • requestType is getAllExchanges
  • timestamp is the earliest timestamp to retrieve (optional)
  • firstIndex is a zero-based index to the first exchange to retrieve (optional)
  • lastIndex is a zero-based index to the last exchange to retrieve (optional)
  • includeCurrencyInfo is true to include some currency details (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • exchanges (A) is an array of exchange objects (refer to Get Exchanges for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get All Exchanges example.

Get Available To Buy

Calculates the rate required in order to completely fill an exchange request.

Request:

  • requestType is getAvailableToBuy or getAvailableToSell
  • currency is the currency ID
  • units is the number of units to buy
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • amountNQT (S) is the total amount needed to fill the exchange request
  • units (S) is the number of units
  • rateNQT (S) is the rate for the currency units
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Available To Buy example.

Get Available To Sell

Refer to Get Available To Buy.

Get Buy / Sell Offers

Get currency buy or sell offers given a currency ID and/or an account ID in order of rate (if sortByRate is true for expected offers, otherwise in the expected order of execution).

Request:

  • requestType is one of getBuyOffers, getSellOffers, getExpectedBuyOffers or getExpectedSellOffers, where expected offers are from the unconfirmed transactions pool or are phased transactions scheduled to finish in the next block
  • currency is the currency ID (optional)
  • account is the account ID (optional if currency provided)
  • availableOnly is true to include only offers with non-zero supply and limit, but is ignored when both currency and account are given (optional, does not apply to expected offers)
  • sortByRate is true to sort by rate (optional, applies only to expected offers, which are returned in expected order of execution by default)
  • firstIndex is a zero-based index to the first offer to retrieve (optional, does not apply to expected offers)
  • lastIndex is a zero-based index to the last offer to retrieve (optional, does not apply to expected offers)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • offers (A) is an array of buy or sell offer objects (refer to Get Offer for details) with the following additional field only for an expected offer:
    • phased (B) is true if the offer is phased, false otherwise
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Buy / Sell Offers example.

Get Buy Offers

Refer to Get Buy / Sell Offers.

Get Sell Offers

Refer to Get Buy / Sell Offers.

Get Expected Buy Offers

Refer to Get Buy / Sell Offers.

Get Expected Sell Offers

Refer to Get Buy / Sell Offers.

Get Currencies

Get currencies given multiple currency IDs.

Request:

  • requestType is getCurrencies
  • currencies is one of multiple currency IDs
  • currencies is one of multiple currency IDs
  • includeCounts is true to include numberOf... fields (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • currencies (A) is an array of currency objects (refer to Get Currency for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Currencies example.

Get Currencies By Issuer

Get currencies issued by multiple accounts in reverse creation order.

Request:

  • requestType is getCurrenciesByIssuer
  • account is one of multiple account IDs
  • account is one of multiple account IDs
  • firstIndex is a zero-based index to the first currency to retrieve (optional)
  • lastIndex is a zero-based index to the last currency to retrieve (optional)
  • includeCounts is true if numberOf... fields are to be included (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • currencies (A) is an array of arrays of currency objects, where the outer array is indexed by the given account IDs (refer to Get Currency for details about the currency objects)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Currencies By Issuer example.

Get Currency

Get the details of a currency.

Request:

  • requestType is getCurrency
  • currency is the currency ID (optional)
  • code is the currency code (optional if currency provided)
  • includeCounts is true if numberOf... fields are to be included (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • initialSupply (S) is the initial currency supply (in QNT)
  • currentReservePerUnitNQT (S) is the minimum currency reserve (in NQT per QNT)
  • types (A) is an array of currency types, one or more of:
    • EXCHANGEABLE
    • CONTROLLABLE
    • RESERVABLE
    • CLAIMABLE
    • MINTABLE
    • NON-SHUFFLEABLE
  • code (S) is the currency code
  • creationHeight (N) is the blockchain height of the currency creation
  • minDifficulty (N) is the minimum difficulty for a mintable currency
  • numberOfTransfers (N) is the number of currency transfers
  • description (S) is the currency description
  • minReservePerUnitNQT (S) is the minimum currency reserve (in NQT per QNT) for a reservable currency
  • currentSupply (S) is the current currency supply (in QNT)
  • issuanceHeight (N) is the blockchain height of the currency issuance for a reservable currency
  • requestProcessingTime (N) is the API request processing time (in millisec)
  • type (N) is the currency type bitmask, from least to most significant bit: exchangeable, controllable, reservable, claimable, mintable, non-shuffleable
  • reserveSupply (S) is the reserve currency supply (in NQT) for a reservable currency
  • maxDifficulty (N) is the maximum difficulty for a mintable currency
  • accountRS (S) is the Reed-Solomon address of the issuing account
  • decimals (N) is the number of decimal places used by the currency
  • name (S) is the name of the currency
  • numberOfExchanges (N) is the number of currency exchanges
  • currency (S) is the currency ID
  • maxSupply (S) is the maximum currency supply (in QNT)
  • account (S) is the account ID of the currency issuer
  • algorithm (N) is the algorithm number for a mintable currency: 2 for SHA256, 3 for SHA3, 5 for Scrypt, 25 for Keccak25
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

Example: Refer to Get Currency example.

Get Currency Account Count

Get the number of accounts that hold a given currency.

Request:

  • requestType is getCurrencyAccountCount
  • currency is the currency ID
  • height is the blockchain height at which the response applies (optional, default is the current height)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • numberOfAccounts (N) is the number of accounts that hold the currency
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Currency Account Count example.

Get Currency Accounts

Get the accounts that hold a given currency in reverse units order.

Request:

  • requestType is getCurrencyAccounts
  • currency is the currency ID
  • height is the blockchain height at which the response applies (optional, default is current height)
  • firstIndex is a zero-based index to the first account to retrieve (optional)
  • lastIndex is a zero-based index to the last account to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • accountCurrencies (A) is an array of account objects with the following fields:
    • unconfirmedUnits (S) is the amount of unconfirmed currency units (in QNT)
    • accountRS (S) is the Reed-Solomon address of the account
    • currency (S) is the currency ID
    • units (S) is the amount of currency (in QNT)
    • account (S) is the account number
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Currency Accounts example.

Get Currency Founders

Get a reservable currency's founders.

Request:

  • requestType is getCurrencyFounders
  • currency is the currency ID
  • account is an account ID (optional)
  • firstIndex is a zero-based index to the first founder to retrieve (optional)
  • lastIndex is a zero-based index to the last founder to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • founders (A) is an array of founder objects each of which has the following fields:
    • accountRS (S) is the Reed-Solomon address of the founding account
    • amountPerUnitNQT (S) is the amount (in NQT per QNT of reserveSupply) reserved by the founder
    • currency (S) is the currency ID
    • account (S) is the founding account number
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Currency Founders example.

Get Currency Ids

Get all currency IDs in reverse chronological creation order.

Request:

  • requestType is getCurrencyIds
  • firstIndex is a zero-based index to the first currency to retrieve (optional)
  • lastIndex is a zero-based index to the last currency to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • currencyIds(A) is an array of currency IDs
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Currency Ids example.

Get Currency Transfers

Get currency transfers given a currency ID and/or an account ID in reverse block height order (or in expected order of execution for expected transfers).

Request:

  • requestType is either getCurrencyTransfers or getExpectedCurrencyTransfers, where expected transfers are from the unconfirmed transactions pool or are phased transactions scheduled to finish in the next block
  • currency is the currency ID (optional)
  • account is the account ID (optional if currency provided)
  • timestamp is the earliest transfer (in seconds since the genesis block) to retrieve (optional, does not apply to expected transfers)
  • firstIndex is a zero-based index to the first transfer to retrieve (optional, does not apply to expected transfers)
  • lastIndex is a zero-based index to the last transfer to retrieve (optional, does not apply to expected transfers)
  • includeCurrencyInfo is true to include some currency fields (optional, does not apply to expected transfers)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • transfers (A) is an array of transfer objects with the following fields for each transfer:
    • code (S) is the currency code
    • units (S) is the amount (in QNT) of the transfer
    • issuanceHeight (N) is the blockchain height of the currency issuance for a reservable currency
    • type (N) is the currency type bitmask (refer to Get Currency for details)
    • issuerAccountRS (S) is the Reed-Solomon address of the issuer account
    • transfer (S) is the transfer ID
    • senderRS (S) is the Reed-Solomon address of the sender account
    • sender (S) is the account number of the sender account
    • recipientRS (S) is the Reed-Solomon address of the recipient account
    • decimals (N) is the number of decimal places used by the currency
    • recipient (S) is the account number of the recipient account
    • name (S) is the currency name
    • currency (S) is the currency ID
    • issuerAccount (S) is the issuer account ID
    • height (N) is the blockchain height of the transfer
    • timestamp (N) is the timestamp (in seconds since the genesis block) of the transfer block, does not apply to an expected transfer
    • phased (B) is true if the transaction is phased, false otherwise, applies only to an expected transfer
    • issuerAccountRS (S) is the Reed-Solomon address of the issuer account
    • issuerAccount (S) is the issuer account ID
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Currency Transfers example.

Get Expected Currency Transfers

Refer to Get Currency Transfers.

Get Exchanges

Get currency exchanges given a currency and/or an account in reverse chronological order.

Request:

  • requestType is getExchanges
  • currency is a currency ID (optional)
  • account is an account ID (optional if currency provided)
  • firstIndex is a zero-based index to the first currency exchange to retrieve (optional)
  • lastIndex is a zero-based index to the last currency exchange to retrieve (optional)
  • timestamp is the earliest block (in seconds since the genesis block) to retrieve (optional)
  • includeCurrencyInfo is true to include several currency-related fields (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • exchanges (A) is an array of exchange objects with the following fields for each exchange:
    • seller (S) is the seller account number
    • code (S) is the currency code
    • sellerRS (S) is the Reed-Solomon address of the seller account
    • units (S) is the amount of currency exchanged (in QNT)
    • issuanceHeight (N) is the blockchain height of currency issuance for a reservable currency
    • type (N) is the currency type bitmask (refer to Get Currency for details)
    • rateNQT (S) is the currency exchange rate (in NQT per QNT)
    • buyer (S) is the account number of the buyer
    • offer (S) is the offer ID
    • buyerRS (S) is the Reed-Solomon address of the buyer account
    • decimals (N) is the number of decimal places used by the currency
    • name (S) is the currency name
    • currency (S) is the currency ID
    • block (S) is the block ID of the block containing the exchange transaction
    • transaction (S) is the transaction ID of the exchange
    • timestamp (N) is the timestamp (in seconds since the genesis block) of the exchange
    • height is the blockchain height of the block containing the exchange transaction
    • issuerAccountRS (S) is the Reed-Solomon address of the issuer account
    • issuerAccount (S) is the issuer account ID
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Exchanges example.

Get Exchanges By Exchange Request

Get currency exchanges given an exchange request transaction ID in reverse chronological order.

Request:

  • requestType is getExchangesByExchangeRequest
  • transaction is the transaction ID of the exchange request
  • includeCurrencyInfo is true to include several currency-related fields (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • exchanges (A) is an array of exchange objects (refer to Get Exchanges for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Exchanges By Exchange Request example.

Get Exchanges By Offer

Get currency exchanges given a currency offer ID in reverse chronological order.

Request:

  • requestType is getExchangesByOffer
  • offer (S) is a currency offer ID
  • includeCurrencyInfo is true to include several currency-related fields (optional)
  • firstIndex is a zero-based index to the first currency exchange to retrieve (optional)
  • lastIndex is a zero-based index to the last currency exchange to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • exchanges (A) is an array of exchange objects (refer to Get Exchanges for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Exchanges By Offer example.

Get Last Exchanges

Get the last exchange of each of multiple currencies.

Request:

  • requestType is getLastExchanges
  • currencies is one of multiple currency IDs
  • currencies is one of multiple currency IDs
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • exchanges (A) is an array of exchange objects (refer to Get Exchanges without name, decimals, code, issuanceHeight, type, issuerAccountRS and issuerAccount for details)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Last Exchanges example.

Get Minting Target

Get the current minting target of a mintable currency.

Request:

  • requestType is getMintingTarget
  • currency is the mintable currency ID
  • account is the minting account ID
  • units is the amount (in QNT) of currency to mint
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Note: units cannot be greater than 1/10000 of the maxSupply (refer to Issue Currency). Increasing units decreases targetBytes.

Response:

  • difficulty (S) is the current difficulty, an estimate of the number of hashes needed to meet the target
  • targetBytes (S) is the 32-byte target (little endian), which must equal or exceed the computed hash of the nonce
  • currency (S) is the currency ID
  • counter (N) is the counter associated with the minting account, the value previously submitted to Currency Mint
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Note: If a nonce is found such that its hash is less than the target, it can be submitted to the blockchain along with counter + 1 using Currency Mint, which results in units NQT being credited to the minting account. difficulty is inversely related to the target, and so increases exponentially as maxSupply is approached because the target is defined as (2exp-1)/units, where exp decreases linearly from 256-minDifficulty to 256-maxDifficulty. (Refer to Issue Currency for maxSupply, minDifficulty and maxDifficulty.)

Example: Refer to Get Minting Target example.

Get Offer

Get offer details given an offer ID.

Request:

  • requestType is getOffer
  • offer is the offer ID
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • sellOffer and buyOffer (O) are objects with the following fields:
    • offer (S) is the offer ID
    • expirationHeight (N) is the blockchain height of offer expiration
    • accountRS (S) is the Reed-Solomon address of the offering account
    • limit (S) is the cumulative limit of currency buys or sells
    • currency (S) is the currency ID
    • supply (S) is the current currency supply
    • account (S) is the offering account number
    • height (N) is the blockchain height of offer creation
    • rateNQT (S) is the currency exchange rate (in NQT per QNT)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Offer example.

Issue Currency

Issue a new currency or re-issue an existing currency with different properties. POST only.

Request: Refer to Create Transaction Request for common parameters.

  • requestType is issueCurrency
  • name is the currency name, 3 to 10 characters and longer than the currency code
  • code is the uppercase currency code with the following fee structure: three letters 25000 BLX, four letters 1000 BLX, five letters 40 BLX, re-issue 40 BLX
  • description is the currency description
  • type is the currency type bitmask, from least to most significant bit: exchangeable, controllable, reservable, claimable, mintable, non-shuffleable
  • initialSupply is the initial currency supply (in QNT) (must match maxSupply unless mintable or claimable, must be zero for claimable)
  • reserveSupply is the reserve currency supply (in QNT) (must match maxSupply)
  • maxSupply is the maximum currency supply (in QNT)
  • issuanceHeight is the blockchain height at which a reservable currency is issued if the reserve minimum is met
  • minReservePerUnitNQT is the minimum currency reserve (in NQT per QNT of reserveSupply) for issuance of a reservable currency
  • minDifficulty is the minimum difficulty (minimum 1) for a mintable currency
  • maxDifficulty is the maximum difficulty (maximum 255 and greater than minDifficulty) for a mintable currency
  • ruleset is for future use, always set to zero
  • algorithm is an algorithm code for a mintable currency: 2 for SHA256, 3 for SHA3, 5 for Scrypt, 25 for Keccak25
  • decimals is the number of decimal places used by the currency (optional, default zero)

Notes: Reservable requires exchangeable and/or claimable, as does controllable; but mintable requires exchangeable. Claimable requires reservable, non-mintable and zero initialSupply.

Response: Refer to Create Transaction Response. The transaction ID is also the currency ID.

Example: Refer to Issue Currency example.

Publish Exchange Offer

Publish an exchange offer for an exchangeable currency. POST only.

Request: Refer to Create Transaction Request for common parameters.

  • requestType is publishExchangeOffer
  • currency is the currency ID
  • buyRateNQT is the offered buy rate (in NQT per QNT)
  • sellRateNQT is the offered sell rate (in NQT per QNT)
  • totalBuyLimit is the cumulative limit (in QNT) of currency buys
  • totalSellLimit is the cumulative limit (in QNT) of currency sells
  • initialBuySupply is the initial amount (in QNT) of currency offered to buy, cannot exceed totalBuyLimit
  • initialSellSupply is the initial amount (in QNT) of currency offered to sell, cannot exceed totalSellLimit
  • expirationHeight is the blockchain height for expiration of the offer

Notes: Each time currency is bought in response to an exchange request to sell currency (refer to Currency Sell), totalBuyLimit is reduced and the supply of currency offered to sell increases by the amount bought. When totalBuyLimit becomes zero, the buy offer is withdrawn. These same notes apply if buy and sell are interchanged. Only the most recent offer associated with an account is valid, even if an earlier offer by that account has not yet expired or reached its limits.

Response: Refer to Create Transaction Response. The transaction ID is also the offer ID.

Example: Refer to Publish Exchange Offer example.

Search Currencies

Get currencies having a code that matches a given query in reverse relevance order.

Request:

  • requestType is searchCurrencies
  • query is a full text query on the currency field code in the standard Lucene syntax (opens in a new tab)
  • firstIndex is a zero-based index to the first currency to retrieve (optional)
  • lastIndex is a zero-based index to the last currency to retrieve (optional)
  • includeCounts is true if the fields beginning with numberOf... are to be included (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • currencies (A) is an array of currency objects (refer to Get Currency for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Search Currencies example.

Transfer Currency

Transfer currency to a given recipient. POST only.

Request: Refer to Create Transaction Request for common parameters.

  • requestType is transferCurrency
  • recipient is the account ID of the transfer recipient
  • currency is the currency ID
  • units is the amount (in QNT) of the transfer

Response: Refer to Create Transaction Response.

Example: Refer to Transfer Currency example.

MessagingNetworking