{"id":20096073,"url":"https://github.com/aptos-labs/aptos-ts-sdk","last_synced_at":"2026-05-14T23:02:08.692Z","repository":{"id":199532028,"uuid":"703114651","full_name":"aptos-labs/aptos-ts-sdk","owner":"aptos-labs","description":"An SDK for accessing the Aptos blockchain data, submitting transactions, and more!","archived":false,"fork":false,"pushed_at":"2025-05-02T11:07:59.000Z","size":26407,"stargazers_count":92,"open_issues_count":57,"forks_count":68,"subscribers_count":35,"default_branch":"main","last_synced_at":"2025-05-02T11:43:50.945Z","etag":null,"topics":["aptos","blockchain","javascript","sdk","typescript"],"latest_commit_sha":null,"homepage":"https://aptos-labs.github.io/aptos-ts-sdk/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aptos-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-10T16:09:57.000Z","updated_at":"2025-05-02T11:08:01.000Z","dependencies_parsed_at":"2025-04-24T21:41:31.706Z","dependency_job_id":null,"html_url":"https://github.com/aptos-labs/aptos-ts-sdk","commit_stats":{"total_commits":516,"total_committers":31,"mean_commits":16.64516129032258,"dds":0.6686046511627908,"last_synced_commit":"3c1ca688dae4b1892b1ac9d87bb7eb9aab298dee"},"previous_names":["aptos-labs/aptos-ts-sdk"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aptos-labs%2Faptos-ts-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aptos-labs%2Faptos-ts-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aptos-labs%2Faptos-ts-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aptos-labs%2Faptos-ts-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aptos-labs","download_url":"https://codeload.github.com/aptos-labs/aptos-ts-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253176434,"owners_count":21866142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aptos","blockchain","javascript","sdk","typescript"],"created_at":"2024-11-13T16:57:30.432Z","updated_at":"2026-05-14T23:02:08.685Z","avatar_url":"https://github.com/aptos-labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TypeScript SDK for Aptos\n\n[![NPM Package Version][npm-image-version]][npm-url]\n![Node Version](https://img.shields.io/node/v/%40aptos-labs%2Fts-sdk)\n[![NPM Package Downloads][npm-image-downloads]][npm-url]\n\nThe [TypeScript SDK](https://www.npmjs.com/package/@aptos-labs/ts-sdk) allows you to connect, explore, and interact with the Aptos blockchain. You can use it to request data, send transactions, set up test environments, and more!\n\n## Learn More\n\nFor comprehensive guides, tutorials, and API reference, visit [aptos.dev](https://aptos.dev):\n\n- **[Quickstart Guide](https://aptos.dev/en/build/sdks/ts-sdk/quickstart)** - Get up and running quickly\n- **[SDK Tutorials](https://aptos.dev/en/build/sdks/ts-sdk)** - Step-by-step tutorials\n- **[API Reference](https://aptos-labs.github.io/aptos-ts-sdk/)** - Complete API documentation\n- **[Examples](./examples/README.md)** - Code examples and sample applications\n\n## Installation\n\n### For use in Node.js or a web application\n\nInstall with your favorite package manager such as npm, yarn, or pnpm:\n\n```bash\npnpm install @aptos-labs/ts-sdk\n```\n\n### For use with Bun\n\nThe SDK is compatible with the [Bun](https://bun.sh/) runtime. Install the SDK using Bun's package manager:\n\n```bash\nbun add @aptos-labs/ts-sdk\n```\n\n### For use in a browser\n\nThe SDK is ESM-only and works with any modern bundler (Vite, webpack, etc.):\n\n```ts\nimport { Aptos, AptosConfig, Network } from \"@aptos-labs/ts-sdk\";\n```\n\n## Usage\n\n### Option 1: `Aptos` class (all-in-one)\n\nThe simplest way to get started. Not tree-shakeable — pulls in all sub-modules.\n\n```ts\nimport { Aptos, AptosConfig, Network } from \"@aptos-labs/ts-sdk\";\n\nconst config = new AptosConfig({ network: Network.TESTNET });\nconst aptos = new Aptos(config);\n```\n\n### Option 2: Namespace classes from sub-paths (tree-shakeable)\n\nImport only the namespaces you need for smaller bundles with full autocomplete:\n\n```ts\nimport { Network } from \"@aptos-labs/ts-sdk\";\nimport { General, AptosConfig } from \"@aptos-labs/ts-sdk/general\";\nimport { Faucet } from \"@aptos-labs/ts-sdk/faucet\";\n\nconst config = new AptosConfig({ network: Network.TESTNET });\nconst general = new General(config);\nconst faucet = new Faucet(config);\n```\n\n### Option 3: Standalone functions (maximum tree-shaking)\n\nFor the smallest possible bundles (e.g., wallet adapters), import the standalone\nfunctions from their sub-paths. `AptosConfig` / `Network` are also available\nfrom their sub-paths (`@aptos-labs/ts-sdk/general`), but importing them from the\nmain barrel is fine — the package is marked `sideEffects: false`, so modern\nbundlers still tree-shake unused exports.\n\n```ts\nimport { getLedgerInfo, AptosConfig } from \"@aptos-labs/ts-sdk/general\";\nimport { Network } from \"@aptos-labs/ts-sdk\";\n\nconst config = new AptosConfig({ network: Network.TESTNET });\nconst ledger = await getLedgerInfo({ aptosConfig: config });\n```\n\n### Reading Data From Onchain ([Guide](https://aptos.dev/en/build/sdks/ts-sdk/fetch-data-via-sdk))\n\n---\n\n```ts\nconst accountInfo = await aptos.account.getAccountInfo({ accountAddress: \"0x123\" });\nconst modules = await aptos.account.getAccountModules({ accountAddress: \"0x123\" });\nconst tokens = await aptos.account.getAccountOwnedTokens({ accountAddress: \"0x123\" });\n```\n\n### Account management (default to Ed25519)\n\n\u003e Note: We introduce a Single Sender authentication (as introduced in [AIP-55](https://github.com/aptos-foundation/AIPs/pull/263)). Generating an account defaults to Legacy Ed25519 authentication with the option to use the Single Sender unified authentication.\n\n---\n\n#### Generate new keys\n\n```ts\nconst account = Account.generate(); // defaults to Legacy Ed25519\nconst account = Account.generate({ scheme: SigningSchemeInput.Secp256k1Ecdsa }); // Single Sender Secp256k1\nconst account = Account.generate({ scheme: SigningSchemeInput.Ed25519, legacy: false }); // Single Sender Ed25519\n```\n\n#### Derive from private key\n\n```ts\n// Create a private key instance for Ed25519 scheme\nconst privateKey = new Ed25519PrivateKey(\"myEd25519privatekeystring\");\n// Or for Secp256k1 scheme\nconst privateKey = new Secp256k1PrivateKey(\"mySecp256k1privatekeystring\");\n\n// Derive an account from private key\n\n// This is used as a local calculation and therefore is used to instantiate an `Account`\n// that has not had its authentication key rotated\nconst account = Account.fromPrivateKey({ privateKey });\n\n// Also, can use this function that resolves the provided private key type and derives the public key from it\n// to support key rotation and differentiation between Legacy Ed25519 and Unified authentications\nconst aptos = new Aptos();\nconst account = await aptos.deriveAccountFromPrivateKey({ privateKey });\n```\n\n#### Derive from private key and address\n\n```ts\n// Create a private key instance for Ed25519 scheme\nconst privateKey = new Ed25519PrivateKey(\"myEd25519privatekeystring\");\n// Or for Secp256k1 scheme\nconst privateKey = new Secp256k1PrivateKey(\"mySecp256k1privatekeystring\");\n\n// Derive an account from private key and address\n\n// Create an AccountAddress instance from the account address string.\nconst address = AccountAddress.from(\"myaccountaddressstring\");\n// Derive an account from private key and address\nconst account = Account.fromPrivateKeyAndAddress({ privateKey, address });\n```\n\n#### Derive from path\n\n```ts\nconst path = \"m/44'/637'/0'/0'/1\";\nconst mnemonic = \"various float stumble...\";\nconst account = Account.fromDerivationPath({ path, mnemonic });\n```\n\n### Submit transaction ([Tutorial](https://aptos.dev/en/build/sdks/ts-sdk/building-transactions))\n\n---\n\n```ts\n/**\n * This example shows how to use the Aptos SDK to send a transaction.\n * Don't forget to install @aptos-labs/ts-sdk before running this example!\n */\n \nimport {\n    Account,\n    Aptos,\n    AptosConfig,\n    Network,\n} from \"@aptos-labs/ts-sdk\";\n \nasync function example() {\n    console.log(\"This example will create two accounts (Alice and Bob) and send a transaction transferring APT to Bob's account.\");\n \n    // 0. Setup the client and test accounts\n    const config = new AptosConfig({ network: Network.TESTNET });\n    const aptos = new Aptos(config);\n \n    let alice = Account.generate();\n    let bob = Account.generate();\n \n    console.log(\"=== Addresses ===\\n\");\n    console.log(`Alice's address is: ${alice.accountAddress}`);\n    console.log(`Bob's address is: ${bob.accountAddress}`);\n \n    console.log(\"\\n=== Funding accounts ===\\n\");\n    await aptos.faucet.fundAccount({\n        accountAddress: alice.accountAddress,\n        amount: 100_000_000,\n    });  \n    await aptos.faucet.fundAccount({\n        accountAddress: bob.accountAddress,\n        amount: 100,\n    });\n    console.log(\"Funded Alice and Bob's accounts!\")\n \n    // 1. Build\n    console.log(\"\\n=== 1. Building the transaction ===\\n\");\n    const transaction = await aptos.transaction.build.simple({\n        sender: alice.accountAddress,\n        data: {\n        // All transactions on Aptos are implemented via smart contracts.\n        function: \"0x1::aptos_account::transfer\",\n        functionArguments: [bob.accountAddress, 100],\n        },\n    });\n    console.log(\"Built the transaction!\")\n \n    // 2. Simulate (Optional)\n    console.log(\"\\n === 2. Simulating Response (Optional) === \\n\")\n    const [userTransactionResponse] = await aptos.transaction.simulate.simple({\n        signerPublicKey: alice.publicKey,\n        transaction,\n    });\n    console.log(userTransactionResponse)\n \n    // 3. Sign\n    console.log(\"\\n=== 3. Signing transaction ===\\n\");\n    const senderAuthenticator = aptos.transaction.sign({\n        signer: alice,\n        transaction,\n    });\n    console.log(\"Signed the transaction!\")\n \n    // 4. Submit\n    console.log(\"\\n=== 4. Submitting transaction ===\\n\");\n    const submittedTransaction = await aptos.transaction.submit.simple({\n        transaction,\n        senderAuthenticator,\n    });\n \n    console.log(`Submitted transaction hash: ${submittedTransaction.hash}`);\n \n    // 5. Wait for results\n    console.log(\"\\n=== 5. Waiting for result of transaction ===\\n\");\n    const executedTransaction = await aptos.transaction.waitForTransaction({ transactionHash: submittedTransaction.hash });\n    console.log(executedTransaction)\n};\n \nexample();\n```\n\n### Using Struct and Enum Arguments\n\n---\n\nThe SDK supports passing public copy structs and enums as transaction arguments. You must encode them using the `StructEnumArgumentParser` before passing to transaction building functions:\n\n```ts\nimport {\n  Aptos,\n  AptosConfig,\n  Network,\n  StructEnumArgumentParser,\n  parseTypeTag,\n  TypeTagStruct\n} from \"@aptos-labs/ts-sdk\";\n\nconst config = new AptosConfig({ network: Network.TESTNET });\nconst aptos = new Aptos(config);\nconst parser = new StructEnumArgumentParser(config);\n\n// Example 1: Simple struct argument\nconst pointType = parseTypeTag(\"0x1::shapes::Point\") as TypeTagStruct;\nconst pointArg = await parser.encodeStructArgument(pointType, { x: \"10\", y: \"20\" });\n\nconst transaction = await aptos.transaction.build.simple({\n  sender: alice.accountAddress,\n  data: {\n    function: \"0x1::shapes::draw_point\",\n    functionArguments: [pointArg],\n  },\n});\n\n// Example 2: Nested structs\nconst lineType = parseTypeTag(\"0x1::shapes::Line\") as TypeTagStruct;\nconst lineArg = await parser.encodeStructArgument(lineType, {\n  start: { x: \"0\", y: \"0\" },\n  end: { x: \"10\", y: \"10\" }\n});\n\nconst transaction2 = await aptos.transaction.build.simple({\n  sender: alice.accountAddress,\n  data: {\n    function: \"0x1::shapes::draw_line\",\n    functionArguments: [lineArg],\n  },\n});\n\n// Example 3: Enum variants\nconst colorType = parseTypeTag(\"0x1::game::Color\") as TypeTagStruct;\nconst colorArg = await parser.encodeEnumArgument(colorType, { Red: {} });\n\nconst transaction3 = await aptos.transaction.build.simple({\n  sender: alice.accountAddress,\n  data: {\n    function: \"0x1::game::set_color\",\n    functionArguments: [colorArg],\n  },\n});\n\n// Example 4: Enum with fields\nconst accountTypeTag = parseTypeTag(\"0x1::game::AccountType\") as TypeTagStruct;\nconst accountTypeArg = await parser.encodeEnumArgument(accountTypeTag, {\n  Premium: { \"0\": \"100\" }\n});\n\nconst transaction4 = await aptos.transaction.build.simple({\n  sender: alice.accountAddress,\n  data: {\n    function: \"0x1::game::create_player\",\n    functionArguments: [accountTypeArg],\n  },\n});\n```\n\n**Features:**\n- Support for nested structs/enums (up to 7 levels deep)\n- Generic type parameter substitution (T0, T1, etc.)\n- All Move primitive types (bool, u8-u256, i8-i256, address)\n- Special framework types (String, Object\u003cT\u003e, Option\u003cT\u003e)\n- Option\u003cT\u003e dual format support (vector `[]`/`[value]` or enum `{None:{}}`/`{Some:{0:value}}`)\n- Module ABI caching for performance\n\n## Troubleshooting\n\nIf you see an import error when you do this:\n\n```typescript\nimport { Aptos, AptosConfig, Network } from \"@aptos-labs/ts-sdk\";\n```\n\nMake sure your `tsconfig.json` uses a compatible `moduleResolution` setting. The SDK is ESM-only and works with `\"nodenext\"`, `\"node16\"`, or `\"bundler\"` module resolution.\n\n## Contributing\n\nIf you found a bug or would like to request a feature, please file an [issue](https://github.com/aptos-labs/aptos-ts-sdk/issues/new/choose).\nIf, based on the discussion on an issue, you would like to offer a code change, please make a [pull request](https://github.com/aptos-labs/aptos-ts-sdk/pulls).\nIf neither of these describes what you would like to contribute, check out the [contributing guide](https://github.com/aptos-labs/aptos-ts-sdk/blob/main/CONTRIBUTING.md).\n\n## Running unit tests\n\n```\npnpm test                        # Run all tests (unit + e2e)\nvitest run tests/unit            # Run unit tests only\nvitest run keyless.test.ts       # Run a specific test file\n```\n\n[npm-image-version]: https://img.shields.io/npm/v/%40aptos-labs%2Fts-sdk.svg\n[npm-image-downloads]: https://img.shields.io/npm/dm/%40aptos-labs%2Fts-sdk.svg\n[npm-url]: https://npmjs.org/package/@aptos-labs/ts-sdk\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faptos-labs%2Faptos-ts-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faptos-labs%2Faptos-ts-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faptos-labs%2Faptos-ts-sdk/lists"}