# matic.js: the JavaScript client for the Matic Network

> maticjs is Polygon's TypeScript client library for talking to the Matic chain, and it exists so that developers who are not deeply familiar with smart contract development can still move assets onto the chain and withdraw them again through the fraud proof path. It is published from a pnpm monorepo, released through changesets, and documented off the repository.

**0xPolygon/matic.js** — Javascript developer library to interact with Matic Network

- Repository: https://github.com/0xPolygon/matic.js
- Website: https://wiki.polygon.technology/docs/tools/matic-js/get-started/
- Stars: 564 · Forks: 259
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/0xpolygon-matic-js

## A client for people who are not smart contract developers

The repository contains the maticjs client library, and the README describes its purpose in one sentence: maticjs makes it easy for developers, who may not be deeply familiar with smart contract development, to interact with the various components of Matic Network.

That second clause is the design brief, and it says a lot. A library for the Matic chain could have been a thin wrapper over raw contract calls for people who already know how those calls work. This one is explicitly aimed at the developer who does not, which means the API is shaped around operations rather than around ABI encodings.

The package is published to npm as @maticnetwork/maticjs, written in TypeScript, and released under the MIT licence. The topic tags on the repository place it in the same family as ethereum, polygon, sidechain, smart-contracts, dapps and web3 tooling.

The recent releases are @maticnetwork/maticjs at 3.9.13 and 3.9.12, both on 2026-06-26, and 3.9.9 on 2026-04-27. The last push to the repository was on 2026-07-21, and the default branch is master.

It is worth noticing what the README does not contain. There is no API listing, no example call and no configuration guide, because the documentation lives somewhere else entirely, at the Polygon documentation site under tools/matic-js/get-started, with the older wiki path given as the homepage.

## Two jobs: moving assets in, and getting them out with fraud proofs

The stated purpose of the library is on the asset flows rather than on the chain. This library will help developers to move assets from Ethereum chain to Matic chain, and withdraw from Matic to Ethereum using fraud proofs.

Both halves matter and they are not symmetric. Going in is a deposit into the staking system on the Matic side, and the user needs a way to complete it. Coming out is the exit, and the exit path is the one the README singles out by name, fraud proofs. The fraud proof mechanism is what lets a withdrawal be challenged and, if it is invalid, be penalised on the L1 chain, so an exit is not simply a transaction that confirms after a fixed delay.

For a developer building a bridge interface or a wallet feature, that distinction drives the whole user experience. A deposit can be presented as a transaction to sign. An exit through the fraud proof path has a lifecycle, and the library exists so that the details of that lifecycle are handled by typed calls rather than by hand-rolled contract interaction.

The library also covers the other components of the network rather than only the asset flows, which is what the phrase the various components of Matic Network means in practice. The repository's example folder shows the shape of that surface, with separate utilities for the two network variants the ecosystem runs, a pos folder and a zkevm folder, along with utils_pos.js and utils_zkevm.js files and a shared config.js.

Those two folders are the first thing to check when you are evaluating the library, because the Polygon ecosystem has run a proof of stake chain and a zero knowledge virtual machine chain, and an integration has to pick one.

## Getting the package and the documentation

The Docs section of the README is a single link, to docs.polygon.technology/tools/matic-js/get-started, and the repository homepage points at the wiki path for the same guide under tools/matic-js. Two paths, one document, which is a small sign of how the documentation has moved over the years.

For an npm consumer the installation is the ordinary one, adding the @maticnetwork/maticjs package to your project. The README does not spell out a command for it, because the guide on the documentation site does.

The Support section points at a Discord as the best way to reach the maintainers, and the Contributors section invites pull requests through the contributing guidelines in CONTRIBUTING.md.

For anyone planning to build on this library, the practical recommendation from the repository itself is to start from the documentation site rather than from the source. The README's job here is to be a signpost, and everything a developer actually needs, the API surface, the configuration, the example flows, is on the other side of that link.

## A pnpm monorepo where one package is published

The Development section says two useful things. This is a pnpm monorepo, and the published package lives in packages/maticjs/.

That structure explains most of the repository's top-level entries. There is a packages directory, a pnpm-workspace.yaml and a pnpm-lock.yaml, an examples directory holding the sample integrations, and a manual directory that appears to hold the long-form documentation source. There are also files you would not expect in a library: MIGRATION.md for people moving between major versions, PLAN.md, and SECURITY.md for reporting vulnerabilities.

The root package.json is marked private and named maticjs-monorepo, which is the conventional way of saying that the root is not itself a published artifact:

```json
  "scripts": {
    "build": "pnpm -r run build",
    "lint": "eslint .",
    "lint:ts": "eslint .",
    "format": "prettier --write .",
    "typecheck": "pnpm -r run typecheck",
    "ci:publish": "pnpm exec changeset publish"
  },
```

The -r flag on build and typecheck is the recursive workspace flag, so a single command at the root runs the task in every workspace package. That is the standard pnpm monorepo arrangement, and it means the commands a contributor uses are the same shape as the commands a consumer uses, just at a different level.

The examples folder is worth a second look, because it carries a shared config.js, an .env.example file and the two network-specific utility modules. That is where you see what configuration the library expects in practice, which the README does not mention at all.

## Four commands to work on the library

The development instructions are four bash blocks, and they are the whole contributor workflow.

Setup is a workspace install:

```bash
pnpm install
```

Linting is:

```bash
pnpm run lint
```

Type checking is:

```bash
pnpm run typecheck
```

And the build is:

```bash
pnpm run build
```

The toolchain behind those four commands is visible in the root devDependencies, and it is a modern one. ESLint 10 with a flat config file, Prettier 3 for formatting, Husky 9 with lint-staged and a .lintstagedrc for the pre-commit hooks, Commitlint 19 with the conventional config, markdownlint-cli2 with its own configuration file, Changesets for versioning, and TypeScript 5.5.

Two entries are worth pointing out for a TypeScript library. The @tsconfig packages, @tsconfig/node24 and @tsconfig/node-ts, mean the shared compiler options come from published configurations rather than being copied into the repository, which is how you keep a set of packages on one compiler setup. And the .nvmrc file pins the Node version, which matters when the toolchain itself is moving at that rate.

For a consumer of the library none of this is visible. For a contributor it is the difference between a repository that builds on the first try and one that does not.

## Releases run through changesets, not by hand

Releases are managed via changesets, and the workflow is two commands and a sentence:

```bash
# Add a changeset describing your change
pnpm exec changeset add

# The release workflow publishes automatically on merge to master
```

That is a complete release policy in three lines. You describe your change in a changeset file, you merge to master, and the workflow publishes. The root script that does the publishing is ci:publish, which runs pnpm exec changeset publish.

The published versions in the recent releases list are tagged with the package name, @maticnetwork/maticjs at 3.9.13 and 3.9.12 on the same day, 2026-06-26, which is what changesets produces when several packages or several changesets land together: the patch numbers move but the minor version does not, so nothing in the public API changed between them.

The changesets setup has a companion, the @changesets/changelog-github package, which generates the changelog from the pull requests themselves. That is a small detail, but it means the release notes are written in the pull request descriptions, which is where the reasoning about a change already lives.

Two CI workflows back this up, a ci-trigger workflow and an npm-release-trigger workflow, both on the master branch and both with badges in the README.

## Two chain variants, one library

The examples directory is the clearest statement of what the library covers. There are two folders, pos and zkevm, two utility modules named utils_pos.js and utils_zkevm.js, a shared config.js, an .env.example and a README.

The Polygon network has run as a proof of stake sidechain and, in parallel, as a zero knowledge virtual machine chain, and a client library for the ecosystem has to handle both. Two parallel example sets with two parallel utility modules is what that looks like in practice, and it is a design decision with consequences for you as a consumer: the entry points you call and the configuration keys you set are not identical between the two, so the choice of chain is made early and shapes the code around it.

The .env.example file is the other useful artefact in there, because it is the only place in the repository where the configuration surface is visible. Anything the library reads from the environment, from a private key to an RPC endpoint to a contract address, shows up in that file, and it is a better starting point than guessing at key names from the type definitions.

The overall picture is of a mature, conventional repository: a monorepo with one published package, automated release through changesets, a strict lint and format setup, a security policy, and an examples folder that documents the two network variants side by side. The one thing a reader should notice is that the README itself is a signpost rather than documentation, and the documentation lives on the Polygon site.

## Conclusion

maticjs fits a frontend or backend team that needs to move assets between Ethereum and the Matic chain without writing contract calls by hand, especially one that already has a Polygon integration and wants typed helpers around it. It is the wrong choice if you are building a protocol that needs the raw contract interfaces, because the value here is the convenience layer rather than the primitives, and it is the wrong choice for a new project that has not yet decided on a chain. Verify first which of the two network variants your target uses, since the examples carry separate pos and zkevm utilities, and read the documentation site rather than the repository README, which is deliberately short and points elsewhere.

## FAQ

### What is maticjs?

It is the maticjs client library, a JavaScript developer library to interact with Matic Network, published to npm as @maticnetwork/maticjs. The README says it makes it easy for developers who may not be deeply familiar with smart contract development to interact with the various components of the network.

### What can I do with the Matic SDK?

The library is built around two asset flows, moving assets from the Ethereum chain to the Matic chain, and withdrawing from Matic back to Ethereum using fraud proofs.

### Where is the matic.js documentation?

The README links the documentation site at docs.polygon.technology/tools/matic-js/get-started, and the repository homepage points at the older wiki path for the same guide. The README itself deliberately stays short and holds no API reference.

### How do I build and test matic.js locally?

It is a pnpm monorepo whose published package lives in packages/maticjs. Run pnpm install, then pnpm run lint, pnpm run typecheck and pnpm run build. The root scripts use the recursive flag so they run across every workspace package.

### How are matic.js releases published?

Through changesets. You add a changeset describing your change with pnpm exec changeset add, and the release workflow publishes automatically on merge to master, with the publishing script running pnpm exec changeset publish.

## Sources

- [0xPolygon/matic.js on GitHub](https://github.com/0xPolygon/matic.js)
- [License: MIT](https://github.com/0xPolygon/matic.js/blob/master/LICENSE)
- [Project website](https://wiki.polygon.technology/docs/tools/matic-js/get-started/)
- [README](https://github.com/0xPolygon/matic.js/blob/master/README.md)
- [Releases](https://github.com/0xPolygon/matic.js/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/0xpolygon-matic-js