Skip to main content

Python port of matic.js - library to interact with Polygon blockchain

Project description

PyPi Version Python Versions Read the Docs pre-commit Code style: black

Matic - Python SDK to assist developers on Polygon blockchain.

Disclaimer: this package is not officialy maintained by Polygon affiliates.

Read our documentation on ReadTheDocs.

This project is a direct python port of matic.js library. It includes also maticjs-web3 port.

This library is very new, so documentation improvement is currently in progress. Please refer to official js SDK docs for more comprehensive tutorials.


Install with pip:

pip install -U matic

Install from source:

git clone
cd pymatic
pip install .

Supported extras:

  • test: install test and development dependencies (pip install matic[test])
  • docs: dependencies for building documentation (pip install matic[docs])

Obtaining tokens: initial setup

To proceed woth testing, you'll need environment configuration based on the following template:

USER1_FROM=  # 0x...
USER1_PRIVATE_KEY=  # Without prefix
USER2_FROM=  # 0x...
USER2_PRIVATE_KEY=  # Without prefix


The RPC provided can be used as-is for testnet (Mumbai - child chain, Goerli - parent chain).

To run any of test examples, you'll need two addresses. Don't use real addresses on testnet!

Then, to execute any transactions you'll need some MATIC tokens. You can obtain them via the polygon faucet (better - for both addresses, so you don't think later how to transfer something back).

To power transactions originating from parent chain, you'll need some Goerli ETH. You can obtain them via this faucet.

If you want to experiment with dummy tokens, read the following sections on how to obtain them.


ERC20 token used in this tutorial is "Dummy ERC20 (DERC20)".

Mapped contracts:

You can obtain them via the polygon faucet. To avoid resolving unexpected "insufficient balance" errors in future, get this token both on Mumbai and Goerli testnets.


We use "Test ERC721 (DERC721)" as a ERC721 token example.

Mapped contracts:

This is perhaps the most difficult token to obtain.

  • First, mint them on Goerli (you can do it directly from explorer, if you're using browser-syncable wallet like metamask, or by interacting with contract by any convenient tool of your choice). They are not divisible, so every transaction uses 1 or more tokens, and you mint 1 at a time. Mint as many as you need.
  • Then, deposit these tokens to Mumbai testnet. You can use the following script to do so:
#!/usr/bin/env python

import os

from dotenv import load_dotenv
from matic import POSClient
from web3 import Web3


from_ = os.getenv('USER1_FROM')
from_pk = os.getenv('USER1_PRIVATE_KEY')

parent_contract = '0x02C869F27B0D09004107818B1150e354d38Cb189'
rpc_parent = os.getenv('ROOT_RPC', '')
rpc_child = os.getenv('MATIC_RPC', '')

pos_client = POSClient({
    'network': 'testnet',
    'version': 'mumbai',
    'parent': {
        'provider': Web3.HTTPProvider(rpc_parent),
        'default_config': {'from': from_},
    'child': {
        'provider': Web3.HTTPProvider(rpc_child),
        'default_config': {'from': from_},

erc_721_parent = pos_client.erc_721(parent_contract, True)

tokens = erc_721_parent.get_all_tokens(from_)

approve_tx = erc_721_parent.approve_all(from_pk)
assert approve_tx.receipt

# You can use only some of the tokens here to preserve something on parent chain too.
deposit_tx = erc_721_parent.deposit_many(tokens, from_, from_pk)
assert deposit_tx.receipt

You can wait for these tokens to be added with pos_client.is_deposited(transaction_hash) or just monitor your balance with your wallet or an explorer.

If you've spent all of the tokens, you can mint a couple more.


We use "Test ERC1155 (DERC1155)" as a ERC1155 token example.

Mapped contracts:

You can obtain tokens on both testnets via the polygon faucet.


If you feel like something is going wrong with RPC, try waiting first. Although JS SDK claims to provide low timeouts, sometimes checkpoint event takes 2 hours to complete (see CI tests run time - it's waiting for 3 checkpoint events), StateSync - up to 20 minutes. If transactions are lost or pending for a long time, try sending zero MATIC to your address - sometimes it resolves this issue.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matic-0.1.0b2.tar.gz (72.7 kB view hashes)

Uploaded Source

Built Distribution

matic-0.1.0b2-py3-none-any.whl (69.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page