Skip to content

API Specification

Jump to bottom
martiliones edited this page Jan 26, 2024 · 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/new.
    • 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...",
  "U3716604363012166999",
  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:

    const transaction = await api.sendMessage(
  "apple banana...",
  "U6386412615727665758",
  "Hi, Joe Doe!"
);

    Token transfer with a comment:

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

const transaction = await api.sendMessage(
  "apple banana...",
  "U6386412615727665758",
  "Here is a comment for a transfer",
  MessageType.Chat,
  10.09876543,
  true // Amount is in ADM
);

    Rich message for Ether in-chat transfer:

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

const transaction = await 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 api.getAccountInfo({
  address: "U3716604363012166999",
});

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 api.getAccountBalance("U3716604363012166999");

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 api.getBlock("16391508373936326027");

getBlocks

Gets a list of blocks.

  • Typing

    interface GetBlocksOptions {
  limit?: number;
  offset?: number;
  generatorPublicKey?: string;
  height?: number;
}

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

  • Parameters

    • options — Optional parameters for block query.

  • Returns

    Promise with a list of blocks.

  • Example

    const blocks = await api.getBlocks({
  offset: 1000,
  limit: 2,
});

getChats

Retrieves a list of chatrooms for an address.

  • Typing

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

  • Parameters

    • address — ADAMANT address to get chat with.
    • options — Optional chatroom query parameters.

  • Returns

    Promise with a list of chatrooms.

  • Example

    const { chats } = await api.getChats("U3716604363012166999", {
  type: 2,
  withoutDirectTransfers: true,
});

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 api.getChatMessages(
  "U3716604363012166999",
  "U1304250577100348027",
  {
    type: 2,
    withoutDirectTransfers: true,
  }
);

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 api.getDelegates({
  limit: 2,
  offset: 100,
});

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 { delegate } = await api.getDelegate({ username: "bank" });

searchDelegates

Searches delegates that include the query in their username.

  • Typing

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

  • Parameters

    • q — Delegate username query.

  • Returns

    Promise with search results for delegates.

  • Example

    const { delegates } = await api.searchDelegates("sys");

getDelegatesCount

Gets the total count of delegates.

  • Typing

    function getDelegatesCount(): Promise<GetDelegatesCountResponseDto>;

  • Returns

    Promise with the total count of delegates.

  • Example

    const { count } = await api.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 api.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 nextForgersInfo = await api.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 { accounts } = await api.getVoters(
  "15c505088bcbe4c57d92d43db5399863e0d10cad93c88af1ed337fbde00fa072"
);

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 { delegates } = await api.getVoteData("U383062845755309748");

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 api.getPeers();

getLoadingStatus

Gets the loading status of the node.

  • Typing

    function getLoadingStatus(): Promise<GetLoadingStatusResponseDto>;

  • Returns

    Promise with the loading status.

  • Example

    const loadingStatus = await api.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 api.getSyncStatus();

getPingStatus

Checks if the connected node is alive.

  • Typing

    function getPingStatus(): Promise<GetPingStatusResponseDto>;

  • Returns

    Promise with the object that includes success property.

  • Example

    const { success } = await api.getPingStatus();

getNodeVersion

Gets the software version of the node.

  • Typing

    function getNodeVersion(): Promise<GetNodeVersionResponseDto>;

  • Returns

    Promise with the node's software version.

  • Example

    const { version } = await api.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 api.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 api.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 api.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 api.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 api.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 api.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 api.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 api.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 api.getSupply();

getStatus

Retrieves blockchain network information (broadhash, epoch, height, fee, milestone, nethash, reward, supply) in a single request.

  • Typing

    function getStatus(): Promise<GetNetworkInfoResponseDto>;

  • Returns

    Promise with blockchain network information.

  • Example

    const status = await api.getStatus();

getNodeStatus

Returns both ADAMANT blockchain Node's network and version in one request.

  • Typing

    function getNodeStatus(): Promise<GetNodeStatusResponseDto>;

  • Returns

    Promise with ADAMANT blockchain network and Node information.

  • Example

    const nodeStatus = await api.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. NOTE: Options for the /api/transactions endpoint are combined using or by default. Place your parameters inside and property object to override this behavior.

  • Returns

    Promise with a list of transactions.

  • Examples

    To get transactions from height period:

    const transactions = await api.getTransactions({
  fromHeight: 7585271,
  and: {
    toHeight: 7586280,
  },
});

// or

const transactions = await api.getTransactions({
  and: {
    fromHeight: 7585271,
    toHeight: 7586280,
  },
});

    To get transactions with amount range and from a specific height:

    const transactions = await api.getTransactions({
  and: {
    minAmount: 204921300000000,
    maxAmount: 205021300000000,
    fromHeight: 7585271,
  },
});

    To get transactions from a specific height by sender IDs:

    const transactions = await api.getTransactions({
  fromHeight: 5022044,
  and: {
    senderIds: ["U7047165086065693428", "U11420099101614271169"],
  },
});

    To get "delegate registration" or "vote for delegate" transactions with asset details sent from or received by specified address:

    const transactions = await api.getTransactions({
  types: [2, 3],
  and: {
    inId: "U3716604363012166999",
  },
  returnAsset: 1,
});

getTransaction

Retrieves a transaction by its ID.

  • Typing

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

  • Parameters

  • Returns

    Promise with the transaction information.

  • Example

    const { transaction } = await api.getTransaction("13616514419605573351", {
  returnAsset: 1,
});

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 api.getTransactionsCount();

getQueuedTransactions

Retrieves the count of queued transactions.

  • Typing

    function getQueuedTransactions(): Promise<GetQueuedTransactionsResponseDto>;

  • Returns

    Promise with the count of queued transactions.

  • Example

    const { transactions: queuedTransactions } =
  await api.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 response = await api.getQueuedTransaction("13616514419605573351");

getUnconfirmedTransactions

Retrieves unconfirmed transactions.

  • Typing

    function getUnconfirmedTransactions(): Promise<GetUnconfirmedTransactionsResponseDto>;

  • Returns

    Promise with a list of unconfirmed transactions.

  • Example

    const unconfirmedTransactions = await api.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 response = await api.getUnconfirmedTransaction("13616514419605573351");

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