Skip to content

API Specification

Jump to bottom
martiliones edited this page Dec 17, 2023 · 31 revisions

get

Performs a GET request to ADAMANT blockchain endpoints.

  • Typing

    function get(endpoint: string, params: unknown): Promise<unknown>;

  • Parameters

    • endpoint — Node's endpoint, e.g., accounts/getPublicKey.
    • params — Endpoint parameters object, filters and options.

  • Returns

    Promise of formatted request results.

  • Example

    const publicKey = await api.get('accounts/getPublicKey', {
  address: 'U6386412615727665758',
});

post

Performs a POST request to ADAMANT blockchain endpoints.

  • Typing

    function post(endpoint: string, params: unknown): Promise<unknown>;

  • Parameters

    • endpoint — Node's endpoint, e.g., accounts/getPublicKey.
    • params — Endpoint parameters object.

  • Returns

    Promise of formatted request results.

  • Example

    // ...
const transaction = createDelegateTransaction({
  keyPair,
  username: 'delegate_name',
});

const response = await api.post('delegates', transaction);

getPublicKey

Convenient method for retrieving an account's public key, caching the results.

  • Typing

    function getPublicKey(address: string): Promise<string>;

  • Parameters

    • address — ADAMANT address.

  • Returns

    Promise of public key, string. Returns empty string if unable to retrieve the public key.

  • Example

    const publicKey = await api.getPublicKey('U6386412615727665758');

sendTokens

Creates and broadcasts a Token Transfer transaction to the ADAMANT network.

  • Typing

    function sendTokens(
  passphrase: string,
  addressOrPublicKey: string,
  amount: number,
  isAmountInADM: boolean = true
): Promise<unknown>;

  • Parameters

    • passphrase — Sender's passphrase, used to derive the sender's address.
    • addressOrPublicKey — Recipient's ADAMANT address or public key. If a public key is provided, the address is derived from it.
    • amount — Amount to send, in number format.
    • isAmountInADM — Set to false if the amount is in SATs (10^-8 ADM).

  • Returns

    Promise of formatted request results.

  • Example

    const transaction = await api.sendTokens(
  'apple banana...',
  'U12345678934',
  10.09876543
);

sendMessage

Encrypts and sends a message via a transaction on the ADAMANT network, optionally transferring ADM tokens.

  • Typing

    function sendMessage(
  passphrase: string,
  addressOrPublicKey: string,
  message: string,
  type = MessageType.Chat,
  amount?: number,
  isAmountInADM?: boolean = true
): Promise<unknown>;

  • Parameters

    • passphrase — Sender's passphrase, used to derive the sender's address.
    • addressOrPublicKey — Recipient's ADAMANT address or public key.
    • message — Message text (plain text for basic messages, stringified JSON for rich or signal messages).
    • messageType — Type of the message: 1 (basic chat message), 2 (Rich message), or 3 (Signal message).
    • amount — Amount of ADM tokens to send with the message, in number format.
    • isAmountInADM — Set to false if the amount is in SATs (10^-8 ADM).

  • Returns

    Promise of formatted request results.

  • Examples

    Basic message:

    api.sendMessage('apple banana...', 'U6386412615727665758', 'Hi, Joe Doe!');

    Token transfer with a comment:

    import {MessageType} from 'adamant-api';
import {api} from './api.js';

api.sendMessage(
  'apple banana...',
  'U6386412615727665758',
  'Here is a comment for a transfer',
  MessageType.Chat,
  10.09876543
);

    Rich message for Ether in-chat transfer:

    const message = JSON.stringify({
  type: 'eth_transaction',
  amount: '0.002',
  hash: '0xfa46d2b3c99878f1f9863fcbdb0bc27d220d7065c6528543cbb83ced84487deb',
  comments: 'I like to send it, send it',
});

api.sendMessage(
  'apple banana...',
  'U6386412615727665758',
  richMessage,
  MessageType.Rich
);

newDelegate

Registers a user account as a delegate in the ADAMANT network.

  • Typing

    function newDelegate(passphrase: string, username: string): Promise<unknown>;

  • Parameters

    • passphrase — Account's passphrase.
    • username — Desired delegate name, unique within the ADAMANT blockchain. Should not resemble an ADAMANT address. Can contain alphanumeric characters and symbols !@$&_.

  • Returns

    Promise of formatted request results.

  • Example

    const response = await api.newDelegate('apple banana...', 'delegate_name');

voteForDelegate

Creates and broadcasts a Vote For Delegate transaction in the ADAMANT network.

  • Typing

    function voteForDelegate(
  passphrase: string,
  votes: Array<string>
): Promise<unknown>;

  • Parameters

    • passphrase — Sender's passphrase, used to derive the sender's address.
    • votes — Array of votes. Use + prefix for upvotes and - for downvotes. Public keys, ADM addresses, or delegate names can be used. Using public keys is more efficient to avoid additional queries.

  • Returns

    Promise of formatted request results.

  • Example

    const response = await api.voteForDelegate('apple banana...', [
  '+lynx',
  '+U777355171330060015',
  '-a9407418dafb3c8aeee28f3263fd55bae0f528a5697a9df0e77e6568b19dfe34',
]);

getAccountInfo

Retrieves account information by ADAMANT address or Public Key.

  • Typing

    function getAccountInfo(
  options: AddressOrPublicKeyObject
): Promise<AdamantApiResult<GetAccountInfoResponseDto>>;

  • Parameters

    • options — Object containing ADAMANT address or public key.

  • Returns

    Promise with account information.

  • Example

    const accountInfo = await getAccountInfo({address: 'U1234567890'});

getAccountBalance

Gets the account balance.

  • Typing

    function getAccountBalance(
  address: string
): Promise<GetAccountBalanceResponseDto>;

  • Parameters

    • address — ADAMANT address for balance inquiry.

  • Returns

    Promise with account balance information.

  • Example

    const balance = await getAccountBalance('U1234567890');

getBlock

Retrieves block information by ID.

  • Typing

    function getBlock(id: string): Promise<GetBlockInfoResponseDto>;

  • Parameters

    • id — Block ID.

  • Returns

    Promise with block information.

  • Example

    const blockInfo = await getBlock('Block_ID');

getBlocks

Gets a list of blocks.

  • Typing

    function getBlocks(options?: GetBlocksOptions): Promise<GetBlocksResponseDto>;

  • Parameters

    • options — Optional parameters for block query.

  • Returns

    Promise with a list of blocks.

  • Example

    const blocks = await getBlocks(options);

getChats

Retrieves a list of chatrooms for an address.

  • Typing

    function getChats(
  address: string,
  options?: TransactionQuery<ChatroomsOptions>
): Promise<GetChatRoomsResponseDto>;

  • Parameters

    • address — ADAMANT address.
    • options — Optional chatroom query parameters.

  • Returns

    Promise with a list of chatrooms.

  • Example

    const chats = await getChats('U1234567890', options);

getChatMessages

Gets messages between two accounts.

  • Typing

    function getChatMessages(
  address1: string,
  address2: string,
  query?: TransactionQuery<ChatroomsOptions>
): Promise<GetChatMessagesResponseDto>;

  • Parameters

    • address1 — First ADAMANT address.
    • address2 — Second ADAMANT address.
    • query — Optional query parameters.

  • Returns

    Promise with chat messages between two accounts.

  • Example

    const messages = await getChatMessages('U1234567890', 'U0987654321', query);

getDelegates

Retrieves a list of registered ADAMANT delegates.

  • Typing

    function getDelegates(
  options: GetDelegatesOptions
): Promise<GetDelegatesResponseDto>;

  • Parameters

    • options — Options for delegate query.

  • Returns

    Promise with a list of delegates.

  • Example

    const delegates = await getDelegates(options);

getDelegate

Gets delegate information by username or publicKey.

  • Typing

    function getDelegate(
  options: UsernameOrPublicKeyObject
): Promise<GetDelegateResponseDto>;

  • Parameters

    • options — Object containing either a delegate username or publicKey.

  • Returns

    Promise with delegate information.

  • Example

    const delegateInfo = await getDelegate({username: 'delegate_username'});

searchDelegates

Searches delegates by username.

  • Typing

    function searchDelegates(q: string): Promise<SearchDelegateResponseDto>;

  • Parameters

    • q — Delegate username query.

  • Returns

    Promise with search results for delegates.

  • Example

    const searchResults = await searchDelegates('usernameQuery');

getDelegatesCount

Gets the total count of delegates.

  • Typing

    function getDelegatesCount(): Promise<GetDelegatesCountResponseDto>;

  • Returns

    Promise with the total count of delegates.

  • Example

    const delegatesCount = await getDelegatesCount();

getDelegateStats

Gets forging activity of a delegate.

  • Typing

    function getDelegateStats(
  generatorPublicKey: string
): Promise<GetDelegateStatsResponseDto>;

  • Parameters

    • generatorPublicKey — Delegate's public key.

  • Returns

    Promise with delegate's forging statistics.

  • Example

    const delegateStats = await getDelegateStats(
  '134a5de88c7da1ec71e75b5250d24168c6c6e3965ff16bd71497bd015d40ea6a'
);

getNextForgers

Returns a list of next forgers.

  • Typing

    function getNextForgers(limit?: number): Promise<GetNextForgersResponseDto>;

  • Parameters

    • limit — Optional count to retrieve.

  • Returns

    Promise with a list of next forgers.

  • Example

    const nextForgers = await getNextForgers(10);

getVoters

Gets a list of a delegate's voters.

  • Typing

    function getVoters(publicKey: string): Promise<GetVotersResponseDto>;

  • Parameters

    • publicKey — Delegate's public key.

  • Returns

    Promise with a list of voters for the specified delegate.

  • Example

    const voters = await getVoters(
  'ec48de9b438ae9f12e271ba28d56eb0b3f3bba7b120df7685eddda97c9f79160'
);

getVoteData

Retrieves current votes of a specific ADAMANT account.

  • Typing

    function getVoteData(address: string): Promise<GetAccountVotesResponseDto>;

  • Parameters

    • address — Address of the account to get vote data.

  • Returns

    Promise with the account's current votes.

  • Example

    const voteData = await getVoteData('U1234567890');

    getPeers

Retrieves a list of connected peer nodes.

  • Typing

    function getPeers(): Promise<GetPeersResponseDto>;

  • Returns

    Promise with a list of connected peers.

  • Example

    const peers = await getPeers();

getLoadingStatus

Gets the loading status of the node.

  • Typing

    function getLoadingStatus(): Promise<GetLoadingStatusResponseDto>;

  • Returns

    Promise with the loading status.

  • Example

    const loadingStatus = await getLoadingStatus();

getSyncStatus

Provides information on the node's sync process with other peers.

  • Typing

    function getSyncStatus(): Promise<GetSyncStatusResponseDto>;

  • Returns

    Promise with sync status.

  • Example

    const syncStatus = await getSyncStatus();

getPingStatus

Checks if the connected node is alive.

  • Typing

    function getPingStatus(): Promise<GetPingStatusResponseDto>;

  • Returns

    Promise with the ping status.

  • Example

    const pingStatus = await getPingStatus();

getNodeVersion

Gets the software version of the node.

  • Typing

    function getNodeVersion(): Promise<GetNodeVersionResponseDto>;

  • Returns

    Promise with the node's software version.

  • Example

    const nodeVersion = await getNodeVersion();

getBroadhash

Retrieves the broadhash, an aggregated rolling hash of the past five blocks.

  • Typing

    function getBroadhash(): Promise<GetBroadhashResponseDto>;

  • Returns

    Promise with the broadhash.

  • Example

    const broadhash = await getBroadhash();

getEpoch

Returns the start time of the blockchain epoch.

  • Typing

    function getEpoch(): Promise<GetEpochResponseDto>;

  • Returns

    Promise with the epoch start time.

  • Example

    const epoch = await getEpoch();

getHeight

Retrieves the current blockchain height of the node.

  • Typing

    function getHeight(): Promise<GetHeightResponseDto>;

  • Returns

    Promise with the current blockchain height.

  • Example

    const height = await getHeight();

getFee

Returns the current fee value for type 0 transactions (token transfers).

  • Typing

    function getFee(): Promise<GetTokenTransferFeeResponseDto>;

  • Returns

    Promise with the current fee for token transfers.

  • Example

    const fee = await getFee();

getFees

Provides current fee values for different transaction types.

  • Typing

    function getFees(): Promise<GetTransactionTypesFeesResponseDto>;

  • Returns

    Promise with the current fee values for various transaction types.

  • Example

    const fees = await getFees();

getNethash

Retrieves the nethash, identifying the Mainnet or Testnet the node connects to.

  • Typing

    function getNethash(): Promise<GetNethashResponseDto>;

  • Returns

    Promise with the nethash.

  • Example

    const nethash = await getNethash();

getMilestone

Returns the current slot height, determining the reward for forging a block.

  • Typing

    function getMilestone(): Promise<GetMilestoneResponseDto>;

  • Returns

    Promise with the current slot height.

  • Example

    const milestone = await getMilestone();

getReward

Provides the reward amount a delegate gets for forging a block.

  • Typing

    function getReward(): Promise<GetRewardResponseDto>;

  • Returns

    Promise with the block forging reward.

  • Example

    const reward = await getReward();

getSupply

Returns the total current supply of ADM tokens in the network.

  • Typing

    function getSupply(): Promise<GetTokensTotalSupplyResponseDto>;

  • Returns

    Promise with the total current ADM token supply.

  • Example

    const supply = await getSupply();

getStatus

Retrieves blockchain network information in a single request.

  • Typing

    function getStatus(): Promise<GetNetworkInfoResponseDto>;

  • Returns

    Promise with blockchain network information.

  • Example

    const status = await getStatus();

getNodeStatus

Returns both ADAMANT blockchain network and Node information in one request.

  • Typing

    function getNodeStatus(): Promise<GetNodeStatusResponseDto>;

  • Returns

    Promise with ADAMANT blockchain network and Node information.

  • Example

    const nodeStatus = await getNodeStatus();

getTransactions

Returns a list of transactions based on provided query options.

  • Typing

    function getTransactions(
  options?: TransactionQuery<TransactionsOptions>
): Promise<GetTransactionsResponseDto>;

  • Parameters

    • options — Optional transaction query parameters.

  • Returns

    Promise with a list of transactions.

  • Example

    const transactions = await getTransactions(options);

getTransaction

Retrieves a transaction by its ID.

  • Typing

    function getTransaction(
  id: number,
  options?: TransactionQuery<TransactionsOptions>
): Promise<GetTransactionByIdResponseDto>;

  • Parameters

    • id — Transaction ID.
    • options — Optional transaction query parameters.

  • Returns

    Promise with the transaction information.

  • Example

    const transaction = await getTransaction(transactionId, options);

getTransactionsCount

Gets the count of confirmed, unconfirmed, and queued transactions.

  • Typing

    function getTransactionsCount(): Promise<GetTransactionsCountResponseDto>;

  • Returns

    Promise with the counts of different types of transactions.

  • Example

    const transactionsCount = await getTransactionsCount();

getQueuedTransactions

Retrieves the count of queued transactions.

  • Typing

    function getQueuedTransactions(): Promise<GetQueuedTransactionsResponseDto>;

  • Returns

    Promise with the count of queued transactions.

  • Example

    const queuedTransactions = await getQueuedTransactions();

getQueuedTransaction

Retrieves a specific queued transaction by its ID.

  • Typing

    function getQueuedTransaction(
  id: number
): Promise<GetQueuedTransactionsResponseDto>;

  • Parameters

    • id — Queued transaction ID.

  • Returns

    Promise with the queued transaction information.

  • Example

    const queuedTransaction = await getQueuedTransaction(transactionId);

getUnconfirmedTransactions

Retrieves unconfirmed transactions.

  • Typing

    function getUnconfirmedTransactions(): Promise<GetUnconfirmedTransactionsResponseDto>;

  • Returns

    Promise with a list of unconfirmed transactions.

  • Example

    const unconfirmedTransactions = await getUnconfirmedTransactions();

getUnconfirmedTransaction

Gets a specific unconfirmed transaction by its ID.

  • Typing

    function getUnconfirmedTransaction(
  id: number
): Promise<GetUnconfirmedTransactionByIdResponseDto>;

  • Parameters

    • id — Unconfirmed transaction ID.

  • Returns

    Promise with the unconfirmed transaction information.

  • Example

    const unconfirmedTransaction = await getUnconfirmedTransaction(transactionId);

Formatted Request Results

Definition of the result object structure for the get and post requests.

  • Typing

    type AdamantApiResult<T> =
  | (Omit<T, 'success'> & {success: true})
  | {
      success: false;
      errorMessage: string;
    };

  • Structure

    • success — true if the HTTP request was successful and the node replied with success; otherwise false.
    • data — Contains the node's reply if the HTTP request was successful; otherwise undefined.
    • errorMessage — Contains an error message if success is false. If success is true, errorMessage is undefined.

  • Examples

    // Successful response
{
  "success": true,
  "data": {
    // ... node's reply data
  }
}
    // Node processed request, but with an error
{
  "success": false,
  "data": {
    "success": false,
    // ... error details
  },
  "errorMessage": "Node's reply: <error message>"
}
    // Unsuccessful HTTP request
{
  "success": false,
  "data": undefined,
  "errorMessage": "Error: Request failed with status code <code>. Message: <error message>"
}
Clone this wiki locally