Currency API Documentation

The Shamwari Monetary System (MS) API provides a comprehensive suite of endpoints for creating, managing, and transacting currencies on the Shamwari blockchain. All currency endpoints are served through the API servlet at /nxt and support both HTTP GET and POST request methods.

Base Configuration

Configuration	Value
Default Port	22024
SSL Port	22024
API Endpoint	/nxt
API Tag	MS (Monetary System)
Testnet Port	23023
Protocol	HTTP/HTTPS

All currency endpoints are accessed via:

http://localhost:22024/nxt?requestType=<endpointName>

API Tags

Currency endpoints span the following API tags defined in APITag.java:

Tag	Description
MS	Monetary System — Currency creation, exchange, lending, and transfers
ACCOUNTS	Account queries — Account currency holdings and balances
CREATE_TRANSACTION	Transaction creation — Submitting currency operations
PHASING	Phasing — Time-locked and voted currency transactions
PAYMENTS	Payments — Currency payment operations
LOANS	Lending — Currency loan lifecycle management
SUBSCRIPTIONS	Subscriptions — Subscription service management

Currency Response Model (JSONData.currency)

All currency endpoints return responses conforming to the JSONData.currency() structure defined in JSONData.java:

{
  "currency": "123456789",
  "issuer": "1234567890",
  "issuerRS": "NXT-abcd-efgh-ijkl",
  "name": "Currency Name",
  "code": "CNY",
  "description": "Currency Description",
  "whitelistProperty": "property_name",
  "type": 3,
  "chain": 1,
  "initialSupplyQNT": "100000000000",
  "currentSupplyQNT": "95000000000",
  "maxSupplyQNT": "100000000000",
  "transactionLimitQNT": "5000000000",
  "dailyLimitQNT": "1000000000",
  "creationHeight": 100,
  "issuanceHeight": 150,
  "minDifficulty": 1,
  "maxDifficulty": 255,
  "algorithm": 0,
  "decimals": 8,
  "types": ["EXCHANGEABLE", "CONTROLLABLE"],
  "numberOfTransfers": 1500,
  "numberOfPayments": 3200
}

Currency Response Fields

Field	Type	Description
currency	string	Unique currency ID (unsigned)
issuer	string	Issuer account ID
issuerRS	string	Issuer account in NXT format
name	string	Currency name (3-10 alphabetic characters)
code	string	Currency trading code (3-5 uppercase letters)
description	string	Free-text description (max 1000 chars)
whitelistProperty	string	Property name for whitelist control
type	int	Bitvector of currency capabilities
chain	int	Beta chain ID
initialSupplyQNT	string	Initial supply at issuance
currentSupplyQNT	string	Current circulating supply
maxSupplyQNT	string	Maximum allowable supply
transactionLimitQNT	string	Per-transaction transfer limit
dailyLimitQNT	string	Daily transfer limit
creationHeight	int	Block height of currency creation
issuanceHeight	int	Block height at which currency becomes active
minDifficulty	int	Minimum minting difficulty exponent
maxDifficulty	int	Maximum minting difficulty exponent
algorithm	byte	Hashing algorithm for minting
decimals	byte	Divisibility (decimal places)
types	array	Array of CurrencyType strings
numberOfTransfers	int	Total transfer count (when includeCounts=true)
numberOfPayments	int	Total payment count (when includeCounts=true)

CurrencyType Bitmask Values

Type	Code	Description
SHARED	1	Shared currency type
PERSONAL	2	Personal currency type
EXCHANGEABLE	4	Can be traded on the exchange
CLAIMABLE	8	Can be claimed by holders
MINTABLE	16	Supports minting of new units
CONTROLLABLE	32	Supports transaction/daily limits
RESERVABLE	64	Reserved for future use
SOVEREIGN	128	Sovereign reference currency

---

Account Currency Response Model (JSONData.accountCurrency)

Used by endpoints returning account-holding relationships:

{
  "account": "1234567890",
  "accountRS": "NXT-abcd-efgh-ijkl",
  "currency": "987654321",
  "unitsQNT": "5000000000",
  "unconfirmedUnitsQNT": "1000000000"
}

---

Currency Transfer Response Model (JSONData.currencyTransfer)

Used by transfer-related endpoints:

{
  "transferFullHash": "abc123def456...",
  "chain": 1,
  "currency": "987654321",
  "sender": "1234567890",
  "senderRS": "NXT-abcd-efgh-ijkl",
  "recipient": "0987654321",
  "recipientRS": "NXT-zyxw-vuts-rqpo",
  "unitsQNT": "1000000000",
  "taxUnitsQNT": "5000000",
  "height": 250,
  "timestamp": 123456789
}

---

Exchange Response Model (JSONData.exchange)

Used by exchange-related endpoints:

{
  "transactionFullHash": "abc123...",
  "timestamp": 123456789,
  "unitsQNT": "1000000000",
  "rateQNTPerUnit": "500",
  "currency": "987654321",
  "baseCurrency": "555555555",
  "offer": "111111111",
  "offerFullHash": "def456...",
  "seller": "1234567890",
  "buyer": "0987654321",
  "block": "50000",
  "height": 250
}

---

Error Handling

All currency endpoints return standardized error responses defined in JSONResponses.java:

Error Code	Constant	Description
ERROR_INCORRECT_CURRENCY	INCORRECT_CURRENCY	Invalid currency parameters
ERROR_INCORRECT_CURRENCY_NAME_LENGTH	INCORRECT_CURRENCY_NAME_LENGTH	Currency name outside 3-10 char range
ERROR_INCORRECT_CURRENCY_CODE_LENGTH	INCORRECT_CURRENCY_CODE_LENGTH	Currency code outside 3-5 char range
ERROR_INCORRECT_CURRENCY_DESCRIPTION_LENGTH	INCORRECT_CURRENCY_DESCRIPTION_LENGTH	Description exceeds 1000 chars
ERROR_UNKNOWN_CURRENCY	UNKNOWN_CURRENCY	Requested currency not found
ERROR_MISSING_CURRENCY	MISSING_CURRENCY	Currency parameter missing
ERROR_MISSING_CURRENCY_ACCOUNT	MISSING_CURRENCY_ACCOUNT	Both currency and account parameters missing
ERROR_CANNOT_DELETE_CURRENCY	CANNOT_DELETE_CURRENCY	Currency cannot be deleted by this account
ERROR_NOT_CURRENCY_ISSUER	NOT_CURRENCY_ISSUER	Sender is not the currency issuer
ERROR_NOT_ENOUGH_CURRENCY	NOT_ENOUGH_CURRENCY	Insufficient currency balance
ERROR_CURRENCY_NOT_LIMITED	CURRENCY_NOT_LIMITED	Currency is not controllable type
ERROR_NO_COST_ORDER	NO_COST_ORDER	Zero-value exchange order
ERROR_INCORRECT_LOAN	INCORRECT_LOAN	Invalid loan parameters

---

Complete Endpoint Index

Currency Creation & Administration

Endpoint	Request Type	Method	Tag
IssueCurrency	issueCurrency	POST	MS, CREATE_TRANSACTION
DeleteCurrency	deleteCurrency	POST	MS, CREATE_TRANSACTION
CanDeleteCurrency	canDeleteCurrency	GET	MS
AdjustCurrencyLimits	adjustCurrencyLimits	POST	MS, CREATE_TRANSACTION
GetCurrency	getCurrency	GET	MS
GetCurrencies	getCurrencies	GET	MS
GetCurrencyIds	getCurrencyIds	GET	MS
GetCurrenciesByIssuer	getCurrenciesByIssuer	GET	MS, ACCOUNTS

Currency Transfers & Payments

Endpoint	Request Type	Method	Tag
TransferCurrency	transferCurrency	POST	MS, CREATE_TRANSACTION
GetCurrencyTransfers	getCurrencyTransfers	GET	MS
GetExpectedCurrencyTransfers	getExpectedCurrencyTransfers	GET	MS
CurrencyPayment	currencyPayment	POST	MS, CREATE_TRANSACTION
GetCurrencyPayments	getCurrencyPayments	GET	MS
GetExpectedCurrencyPayments	getExpectedCurrencyPayments	GET	MS
CurrencyBulkPayment	currencyBulkPayment	POST	MS, CREATE_TRANSACTION
GetCurrencyBulkPayments	getCurrencyBulkPayments	GET	MS

Currency Trading & Exchange

Endpoint	Request Type	Method	Tag
CurrencyBuy	currencyBuy	POST	MS, CREATE_TRANSACTION
CurrencySell	currencySell	POST	MS, CREATE_TRANSACTION
CurrencyMint	currencyMint	POST	MS, CREATE_TRANSACTION
GetExchanges	getExchanges	GET	MS
GetAllExchanges	getAllExchanges	GET	MS
GetExchangesByOffer	getExchangesByOffer	GET	MS
GetExchangesByExchangeRequest	getExchangesByExchangeRequest	GET	MS
GetLastExchanges	getLastExchanges	GET	MS
PublishExchangeOffer	publishExchangeOffer	POST	MS, CREATE_TRANSACTION
GetExpectedExchangeRequests	getExpectedExchangeRequests	GET	MS
GetAccountExchangeRequests	getAccountExchangeRequests	GET	MS

Account Currency Holdings

Endpoint	Request Type	Method	Tag
GetCurrencyAccounts	getCurrencyAccounts	GET	MS
GetAccountCurrencyCount	getAccountCurrencyCount	GET	MS
GetAccountCurrencyVaults	getAccountCurrencyVaults	GET	MS
GetAccountCurrencySavings	getAccountCurrencySavings	GET	MS
GetAccountCurrencyLoans	getAccountCurrencyLoans	GET	MS

Currency Phasing & Controls

Endpoint	Request Type	Method	Tag
GetCurrencyPhasedTransactions	getCurrencyPhasedTransactions	GET	MS, PHASING
GetCurrencyTaxRecords	getCurrencyTaxRecords	GET	MS

Lending & Loans

Endpoint	Request Type	Method	Tag
LendCurrency	lendCurrency	POST	MS, CREATE_TRANSACTION
LoanApplication	loanApplication	POST	MS, CREATE_TRANSACTION
LoanRepayment	loanRepayment	POST	MS, CREATE_TRANSACTION
RescueLoan	rescueLoan	POST	MS, CREATE_TRANSACTION
GetLoan	getLoan	GET	MS
GetLoanApplications	getLoanApplications	GET	MS
GetActiveLoans	getActiveLoans	GET	MS
GetPaidLoans	getPaidLoans	GET	MS
GetOverdueLoans	getOverdueLoans	GET	MS
GetAccountCurrencyLoans	getAccountCurrencyLoans	GET	MS

Savings, Vaults & Subscriptions

Endpoint	Request Type	Method	Tag
CurrencySavings	currencySavings	POST	MS, CREATE_TRANSACTION
CurrencyVault	currencyVault	POST	MS, CREATE_TRANSACTION
CreateSubscriptionService	createSubscriptionService	POST	MS, CREATE_TRANSACTION
SubscriptionPayment	subscriptionPayment	POST	MS, CREATE_TRANSACTION
UpdateSubscriptionPlans	updateSubscriptionPlans	POST	MS, CREATE_TRANSACTION
GetSubscriptionServices	getSubscriptionServices	GET	MS
GetSubscriptionPayments	getSubscriptionPayments	GET	MS

---

Common Parameters

All currency endpoints accept the following common parameters unless explicitly overridden:

Parameter	Type	Description	Required
requestType	string	API endpoint name	Yes
secretPhrase	string	Account passphrase for signing	Yes (for POST)
publicKey	string	Account public key (hex)	No
account	string	Account ID or NXT-format address	No
adminPassword	string	Admin password for privileged ops	No
chain	int	Chain ID for multi-chain	No
firstIndex	int	Pagination start index (default: 0)	No
lastIndex	int	Pagination end index (default: MAX)	No
height	int	Blockchain height for historical queries	No
timestamp	int	Filter by timestamp	No
includeCounts	boolean	Include count fields in response	No
includeDeleted	boolean	Include deleted currencies	No
includeCurrencyInfo	boolean	Include currency metadata in response	No
includeLoans	boolean	Include loan details	No
withoutWhitelist	boolean	Exclude whitelist filter in phasing	No

Authentication & Permissions

Currency endpoints are organized by permission requirements defined in API.java:

• Read-only endpoints (GET): Public access, no authentication required
• Transaction endpoints (POST): Require secretPhrase or publicKey for account identification
• Admin endpoints: Require adminPassword parameter for administrative operations
• CORS support: Enabled when nxt.apiServerCORS=true in configuration

Rate Limiting

Endpoint Type	Limit
Public read APIs	No limit
Write APIs	10 req/s per IP
Admin APIs	Authenticated only

Related APIs

• Monetary System Overview
• Asset Exchange API
• Account API
• Phasing API
• Loan API
• Subscription API
• API Overview

Implementation Files

Component	File	Description
API Registry	API.java	Server configuration, port management, CORS
API Enum	APIEnum.java	Endpoint registry with names and handlers
Response Builder	JSONData.java	JSON response structure builders
Tags	APITag.java	Endpoint categorization tags
Parameter Parser	ParameterParser.java	Common parameter extraction utilities
Responses	JSONResponses.java	Standardized error response definitions
Base Handler	APIServlet.java	Request handler base class
Base Transaction	CreateTransaction.java	Transaction creation base class

---

Notes

• All currency IDs are unsigned 64-bit integers represented as strings to prevent overflow
• Amounts are in NQT (Nxt Quantum) — the smallest indivisible unit, with decimals determining divisibility
• The default service port is 22024 for both HTTP and HTTPS
• All responses include errorCode: 0 on success, with non-zero values indicating errors
• The API servlet is mounted at /nxt and supports /nxt-proxy for proxy requests
• JSON responses are generated by JSONData.java methods to ensure consistency across endpoints