SDK for Aptos Node API

NOTE: This is the legacy TypeScript SDK, aka the npm package aptos. For a more robust SDK and better support, we recommend upgrading to the new TypeScript SDK @aptos-labs/ts-sdk. Take a look at the documentation and the migration guide.

The Aptos TypeScript SDK provides a convenient way to interact with the Aptos blockchain using TypeScript. It offers a set of utility functions, classes, and types to simplify the integration process and enhance developer productivity.

Installation

For use in Node.js or a web application

pnpm install aptos

You can also use your preferred npm client, such as yarn or npm.

For use in a browser

<script src="https://unpkg.com/aptos@latest/dist/index.global.js" />

Then, the SDK can be accessed through window.aptosSDK.

Documentation and examples

• The Aptos documentation site provides step-by-step instructions, code snippets, and best practices to use this library.
• You can view the generated Type Doc for the latest release of the SDK.
• For in-depth examples, check out the examples folder with ready-made package.json files to get you going quickly!

Development environment setup

Setup an .env file to configure the URLs. From the root of this package, run:

rm .env
echo 'APTOS_NODE_URL="http://localhost:8080/v1"' >> .env
echo 'APTOS_FAUCET_URL="http://localhost:8081"' >> .env

Testing

To run the full SDK tests, From the root of this package, run:

pnpm test

If you see strange behavior regarding HTTP clients, try running the tests with --detectOpenHandles.

To test a single file in the SDK, From the root of this package, run:

npx jest -- <path/to/file.test.ts>

To use the local build in a local project:

// run from the root of this package
pnpm build
// run on your local project
pnpm add PATH_TO_LOCAL_SDK_PACKAGE

Working with local node

To develop in a local environment, you need to use the SDK from the main branch.

Run a local node (run from the root of the repo):

cargo run -p aptos -- node run-local-testnet --force-restart --assume-yes

Contributing

If you found a bug or would like to request a feature, please file an issue. If, based on the discussion on an issue you would like to offer a code change, please make a pull request. If neither of these describes what you would like to contribute, checkout out the contributing guide.

Aptos TS SDK Changelog

All notable changes to the Aptos Node SDK will be captured in this file. This changelog is written by hand for now. It adheres to the format set out by Keep a Changelog.

Unreleased

1.21.0 (2023-12-13)

• Fix nested type tag parsing in Object types
• Update all dependencies including @aptos-labs/aptos-client

1.20.0 (2023-09-22)

• Add current objects queries support - getAccountOwnedObjects
• Add burnObject transaction support in AptosToken

1.19.0 (2023-08-24)

• Add fungible asset queries support - getAccountCoinsData, getAccountCoinsDataCount

1.18.0 (2023-08-10)

• Fix default behavior for coin client to transfer and create account by default
• Filter amount > 0 on getTokenOwnersData
• Include missing fields for all Indexer queries

1.17.0 (2023-08-04)

• Add support for a fee payer transaction
• Return transaction message error when transaction has failed when checkSuccess is set to true

1.16.0 (2023-08-02)

• Export all remaining types and functions in TS SDK
• Add improvements for IndexerClient
  • Export indexer types - export * from "/indexer/generated/types"
  • Support for token v2 activities - getTokenActivities, response structure has changed
  • Aggregate query suports token v2 activities - getTokenActivitiesCount
  • Support for sorting indexer queries - orderBy optional argument in extraArgs arguments
  • Support for get owned tokens by token address or token data id - getOwnedTokensByTokenData
• Add support for local/custom networks without an indexer client
• Move to use account_transactions query in getAccountTransactionsData on IndexerClient
• Move to use account_transaction_aggregate query in getAccountTransactionsCount on IndexerClient
• Optional startVersion argument on getUserTransactions is not positional and part of the object param

1.15.0 (2023-07-28)

• Implementing TransactionWorker - a layer for managing and submitting as many transactions from a single account at once
• Memoize account modules by adding memoize decorator to getAccountModules

1.14.0 (2023-07-20)

• Introduce and use @aptos-labs/aptos-client package to manage and handle the client used in the SDK

1.13.3 (2023-07-19)

• Add support for null or undefined as absense of an Option
• Fix Option<LongerType> for input arguments in entry functions

1.13.2 (2023-07-12)

• Add support for Option<T> and vector<Object<T>> in the SDK

1.13.1 (2023-07-06)

• Fixed serialization of arguments like u16, u32 and u256
• Support contentType in request so custom headers would not override required headers
• Set WITH_CREDENTIALS to false on Indexer requests

1.13.0 (2023-07-05)

• Use client that is not generated by openAPI

1.12.0 (2023-06-30)

• Add token standard v2 support to getTokenOwnersData query
  • propertyVersion parameter is optional to support fetching token v2 data
• Introduce getTokenCurrentOwnerData to fetch the current owner of a token
• Add mintAptosSubdomain and setSubdomainAddress functions to AnsClient

1.11.0 (2023-06-22)

• Export bcsSerializeU256 from bcs/helper.ts
• Add examples folder to .npmignore
• Use 0x1::aptos_account::transfer in tests
• Support transfer a fungible token.
  • Add a transfer function to the AptosToken class that accepts NonFungibleTokenParameters or FungibleTokenParameters types.
• getTokenData query supports token standard v2. Return fields have changed.

1.10.0 (2023-06-07)

• Add x-aptos-client header to IndexerClient requests
• Add standardizeAddress static function to AccountAddress class to standardizes an address to the format "0x" followed by 64 lowercase hexadecimal digits.
• Change indexerUrl param on Provider class to an optional parameter
• Add getCollectionsWithOwnedTokens query to fetch all collections that an account has tokens for
• Support tokenStandard param in getOwnedTokens and getTokenOwnedFromCollectionAddress queries
• Add FungibleAssetClient plugin to support fungible assets
• Support fungible assets in CoinClient class operations

1.9.1 (2023-05-24)

• Add x-aptos-client header to AptosClient requests

1.9.0 (2023-05-17)

• Fix get number of delegators Indexer query
• Include static methods from AptosClient and IndexerClient classes in the Provider class
• Add Indexer queries for tokens - getOwnedTokens, getTokenOwnedFromCollectionAddress, getTokenOwnedFromCollectionNameAndCreatorAddress, getCollectionData, getCollectionAddress

1.8.5 (2023-04-29)

• Add local tests for AnsClient
• Add AptosToken plugin to support tokenv2
• Add generic support to input params in move entry functions
• Add signature verification method to AptosAccount.

1.8.4 (2023-04-13)

• Move TypeTagParser from builder_utils.ts to type_tag.ts
• Update StructTag.fromString() to use and relies on TypeTagParser

1.8.3 (2023-04-10)

• Add publish-ans-contract script and pnpm command for tests
• Revert User-Agent header from both AptosClient and IndexerClient due to a browser error

1.8.2 (2023-04-06)

• Introduce AnsClient class to support ANS (Aptos Names Service) data fetching queries
• Add User-Agent header to AptosClient and IndexerClient queries
• Add Indexer queries to IndexerClient - getAccountCoinsData, getAccountTokensCount, getAccountTransactionsCount, getAccountTransactionsData, getCurrentDelegatorBalancesCount, getDelegatedStakingActivities, getTokensActivitiesCount, getTokenData, getTokenOwnersData, getTopUserTransactions, getUserTransactions
• Add convertion layer to IndexerClient queries to handle missing 0x
• Add validation layer to IndexerClient to validate queried account address is in the long format, i.e 66 chars long (0x<64 chars>)
• Change queryIndexer function in IndexerClient class visibility to public
• Add mint Aptos Name function mintAptosName() to AnsClient class

1.7.2 (2023-03-13)

• CoinClient and TokenClient to use remote ABI instead of local ABIs
• Reorganize SDK files structure for a better readability and maintainability
• Add getIndexerLedgerInfo query to IndexerClient

1.7.1 (2023-03-02)

• Fix IndexerClient error parsing using JSON.stringify() to display the error message correctly on the console

1.7.0 (2023-03-01)

• Add Indexer support. We introduce a new class IndexerClient that queries our Indexer to support data shaping fetching and providing users with a seamless experience.
• Introduces a Provider class we can initialize and query our blockchain by hiding the underlying implementation (fullnode vs indexer)

1.6.0 (2023-01-20)

• Add support to Move view functions

1.5.0 (2023-01-05)

• Export classes from property_map_serde
• User can specify token string property type using "string", "String" or "0x1::string::String" to serde the string token property on-chain
• Use getAccountResource to replace getAccountResources in CoinClient#checkBalance, which can reduce network load.

1.4.0 (2022-11-30)

• Add missing fields to TokenData class
• Add PropertyMap and PropertyValue type to match on-chain data
• Support token property map deseralizer to read the property map in the original data format.
• Allow checkBalance in CoinClient to take in a MaybeHexString as well as AptosAccount, since users might want to check the balance of accounts they don't own (which is generally how you use AptosAccount).
• Similar to checkBalance, allow transfer in CoinClient to take in a MaybeHexString for the receiver argument.
• Add a new createReceiverIfMissing argument to transfer in CoinClient. If set, the 0x1::aptos_account::transfer function will be called instead of 0x1::coin::transfer, which will create the account on chain if it doesn't exist instead of failing.

1.3.17 (2022-11-08)

• Support computing resource account address based off a source address and a seed
• Exported ABI types
• getAccountModules and getAccountResources now use pagination under the hood. This addresses the issue raised here: https://github.com/aptos-labs/aptos-core/issues/5298. The changes are non-breaking, if you use these functions with an older node that hasn't updated to include the relevant support in its API service, it will still work as it did before.
• To support the above, the generated client has been updated to attach the headers to the response object, as per the changes here: https://github.com/aptos-labs/openapi-typescript-codegen/compare/v0.23.0...aptos-labs:openapi-typescript-codegen:0.24.0?expand=1. Consider this an implementation detail, not a supported part of the SDK interface.
• Add functions to token client support
  • direct transfer with opt-in
  • burn token by owner
  • burn token by creator
  • mutate token properties
• Add property map serializer to serialize input to BCS encode

1.3.16 (2022-10-12)

• Add estimatePrioritizedGasUnitPrice to the simulation interface. If set to true, the estimated gas unit price is higher than the original estimate. Therefore, transactions have a higher chance to be executed during congestion period.
• esitmateGasPrice now returns deprioritized_gas_estimate and prioritized_gas_estimate along with gas_estimate. deprioritized_gas_estimate is a conservative price estimate. Users might end up paying less gas eventually, but the transaction execution is deprioritized by the block chain. On the other hand, prioritized_gas_estimate is a higher price esitmate. Transactions need to be executed sooner could use prioritized_gas_estimate.

1.3.15 (2022-09-30)

• [Breaking Changes] Following the deprecation notice in the release notes of 1.3.13, the following breaking changes have landed in this release. Please see the notes from last release for information on the new endpoints you must migrate to:
  • The getEventsByEventKey function has been removed.
  • The key field in the Event struct has been removed.
• Turn on strict in tsconfig

1.3.14 (2022-09-20)

• Enable SDK axios client to carry cookies for both the browser and node environments.
• Added new functions getBlockByHeight and getBlockByVersion.

1.3.13 (2022-09-15)

• Increase the default wait time for waitForTransactionWithResult to 20s.
• A new function called getEventsByCreationNumber has been added, corresponding to the new endpoint on the API. For more information on this change, see the API changelog for API version 1.1.0.
• [Deprecated] The getEventsByEventKey function is now deprecated. In the next release it will be removed entirely. You must migrate to the new function, getEventsByCreationNumber, by then.
• Included in the Event struct (which is what the events endpoints return) is a new field called guid. This is a more easily interpretable representation of an event identifier than the key field. See the API changelog for an example of the new field.
• [Deprecated] The key field in the Event struct is now deprecated. In the next release it will be removed entirely. You must migrate to using the guid field by then.
• Removed NPM dependencies ed25519-hd-key and typescript-memoize.
• Added IIFE bundle that can be served from CDN. No NPM is required to use the SDK in browser environment.

1.3.12 (2022-09-08)

• Feature to rotate auth key for single signature account

1.3.11 (2022-08-31)

• Upgraded typescript version from 4.7.4 to 4.8.2, as well as linter package versions.
• [Breaking Change] ModuleBundle transaction support is removed. Instead, SDK users should use AptosClient.publishPackage to publish Move packages.
• Expose detailed API errors.
• Accept stringified values as transaction payload parameters.

1.3.10 (2022-08-26)

• Fix the bug in waitForTransactionWithResult. When API returns 404, the function should continue waiting rather than returning early. The reason is that the txn might not be committed promptly. waitForTransactionWithResult should either timeout or get an error in such case.

1.3.9 (2022-08-25)

• [Breaking Change] Reimplemented the JSON transaction submission interfaces with BCS. This is a breaking change. createSigningMessage is removed. Before the changes, the transaction payloads take string aruguments. But now, Typescript payload arguments have to match the smart contract arugment types. e.g. number matches u8, number | bigint matches u64 and u128, etc.
• [Breaking Change] getTokenBalance and getTokenBalanceForAccount have been renamed to getToken and getTokenForAccount, since they were never getting just the balance, but the full token.
• Added CoinClient to help working with coins. This contains common operations such as transfer, checkBalance, etc.
• Added generateSignSubmitWaitForTransaction, a function that provides a simple way to execute the full end to end transaction submission flow. You may also leverage generateSignSubmit, a helper that does the same but without waiting, instead returning teh transaction hash.
• Added fromDerivePath to AptosAccount. You can use this to create an AptosAccount (which is a local representation of an account) using a bip44 path and mnemonics.

1.3.7 (2022-08-17)

• Add a transaction builder that is able to serialize transaction arguments with remote ABIs. Remote ABIs are fetchable through REST APIs. With the remote ABI transaction builder, developers can build BCS transactions by only providing the native JS values.
• Make all functions that accept BigInt parameters accept BigInt | number instead.

1.3.6 (2022-08-10)

• Switch back to representing certain move types (MoveModuleId, MoveStructTag, ScriptFunctionId) as strings, for both requests and responses. This reverts the change made in 1.3.2. See #2663 for more.
• Represent certain fields with slightly different snake casing, e.g. ed25519_signature now instead of ed_25519_signature.
• Add generated types for healthcheck endpoint.
• If the given URL is missing /v1, the AptosClient constructor will add it for you. You can opt out of this behavior by setting doNotFixNodeUrl to true when calling the constructor.

1.3.5 (2022-08-08)

• Re-expose BCS and items from transaction_builder/builder from the root of the module.

1.3.4 (2022-08-07)

• Downscaled default value for max_gas.

1.3.3 (2022-08-05)

• Update the token clients to submit transactions through BCS interface. The new token client doesn't hex-code "name", "decription" and "uri" any more. String properties are passed and saved just as strings.
• Expose buildTransactionPayload from ABI transaction builder. In some scenarios, developers just want to get a TransactionPayload rather than a RawTransaction.

1.3.2 (2022-08-04)

This special entry does not conform to the format set out by Keep a Changelog as there are noteworthy breaking changes with necessary rationale. Future entries will follow this format.

This release updates the SDK to work with V1 of the Aptos Node API. There are some key changes between V0 and V1 that you can read about in the API changelog, refer to the notes for version 1.0.0. Accordingly, this SDK version represents breaking changes compared to 1.2.1.

• The SDK now communicates by default with the /v1 path of the API. It will not work correctly with the v0 API. If you provide a path yourself when instantiating a client, make sure you include /v1, e.g. http://fullnode.devnet.aptoslabs.com/v1.
• As of this release, the API, API spec, client generated from that spec, SDK wrapper, and examples are all tested together in CI. Previously it was possible for these to be out of sync, or in some cases, they would test against a different deployment entirely, such as devnet. Now we make the guarantee that all these pieces from the same commit work together. Notably this means exactly that; there is no guarantee that the latest version of the SDK will work with a particular Aptos network, such as devnet, except for a network built from the same commit as the SDK.
• The generated client within the SDK is generated using a different tool, openapi-typescript-codegen. Most of these changes are transparent to the user, as we continue to wrap the generated client, but some of the generated types are different, which we mention here.
• Token types are no longer exposed from the generated client (under Types) as they are no longer part of the API (indeed, they never truly were). Instead you can find these definitions exposed at TokenTypes.
• Some functions, such as for getting account resources and events, no longer accept resource types as concatenated strings. For example:

# Before:
const aptosCoin = "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>";
# After
const aptosCoin = const aptosCoin = {
    address: "0x1",
    module: "coin",
    name: "CoinStore",
    generic_type_params: ["0x1::aptos_coin::AptosCoin"],
};

• Similarly, some endpoints no longer return this data as a string, but in a structured format, e.g. MoveStructTag. Remember to use something like lodash.isEqual to do equality checks with these structs.
• To help work with these different formats, functions for converting between them have been added to utils.
• A new function, waitForTransactionWithResult, has been added to help wait for a transaction and then get access to the response from the server once the function exits.

For help with migration, we recommend you see the updated examples under examples/, they demonstrate how to deal with some of these changes, such as the more structured responses. We are also available to assist in the Aptos Discord.

Deprecation Notice: On September 1st we will remove the v0 API from the running nodes. As a user of the TS SDK, the best way you can migrate prior to this is by upgrading to version 1.3.2 or higher of the SDK. We will repeatedly remind developers of this upcoming deprecation as we approach that date.

1.3.1 (2022-08-04)

See release notes for 1.3.2.

1.3.0 (2022-08-03)

See release notes for 1.3.2.

1.2.1 (2022-07-23)

Note: This entry and earlier do not conform to the format set out by Keep a Changelog.

Features

• Deprecate getTokenBalance api in SDK (2ec554e)
• Memoize chain id in aptos client (#1589) (4a6453b)
• Multiagent: Support multiagent transaction submission (#1543) (0f0c70e)
• Support retrieving token balance for any account (7f93c21)

Bug Fixes

• Get rid of "natual" calls (#1678) (54601f7)

1.2.0 (2022-06-28)

Features

• Vector tests for transaction signing (6210c10)
• Add royalty support for NFT tokens (93a2cd0)
• Add transaction builder examples (a710a50)
• Support transaction simulation (93073bf)

Bug Fixes

• Fix a typo, natual now becomes natural (1b7d295), closes #1526
• Fix Javascript example (5781fee), closes #1405