Skip to content

API


new Matic(options)

Creates Matic SDK instance with give options. It returns a MaticSDK object.

import Matic from "maticjs"

const matic = new Matic(options)
  • options is simple Javascript object which can have following fields:
  • maticProvider can be string or Web3.providers instance. This provider must connect to Matic chain. Value can be anyone of following:
  • parentProvider can be string or Web3.providers instance. This provider must connect to Ethereum chain (testnet or mainchain). Value can be anyone of following:
  • rootChainAddress must be valid Ethereum contract address.
  • syncerUrl must be valid API host. MaticSDK uses this value to fetch receipt/tx proofs instead of getting whole block to client side.
  • watcherUrl must be valid API host. MaticSDK uses this value to fetch headerBlock info from mainchain and to find appropriate headerBlock for given blockNumber.
  • withdrawManagerAddress must be valid Ethereum contract address.
  • depositManagerAddress must be valid Ethereum contract address.

matic.getMappedTokenAddress(tokenAddress)

get matic token address mapped with mainchain tokenAddress.

  • tokenAddress must be valid token address

This returns matic address.

Example:

matic
  .getMappedTokenAddress("0x670568761764f53E6C10cd63b71024c31551c9EC")
  .then(address => {
    console.log("matic address", address)
  })

matic.balanceOfERC721(address, token, options)

get balance of ERC721 token for address.

  • token must be valid token address
  • address must be valid user address

This returns matic balance.

Example:

matic
  .balanceOfERC721("0xfeb14bc6aaf5d39fa43ff51ed94e6c260539e296")
  .then(address => {
    console.log("matic address", address)
  })

matic.tokenOfOwnerByIndexERC721(address, token, index, options)

get ERC721 tokenId at index for token and for address.

  • token must be valid token address
  • address must be valid user address
  • index index of tokenId

This returns matic tokenId.

Example:

matic
  .tokenOfOwnerByIndexERC721("0xfeb14b...", "21", 0, {
    from: "0xABc578455..."
  })
  .then(tokenID => {
    console.log("Token ID", tokenID)
  })

matic.approveERC20TokensForDeposit(token, amount, options)

Approves given amount of token to rootChainContract.

  • token must be valid ERC20 token address
  • amount must be token amount in wei (string, not in Number)
  • options (optional) must be valid javascript object containing from, gasPrice, gasLimit, nonce, value, onTransactionHash, onReceipt or onError
  • from must be valid account address(required)
  • gasPrice same as Ethereum sendTransaction
  • gasLimit same as Ethereum sendTransaction
  • nonce same as Ethereum sendTransaction
  • nonce same as Ethereum sendTransaction
  • value contains ETH value. Same as Ethereum sendTransaction.
  • onTransactionHash must be function. This function will be called when transaction will be broadcasted.
  • onReceipt must be function. This function will be called when transaction will be included in block (when transaction gets confirmed)
  • onError must be function. This function will be called when sending transaction fails.

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

matic
  .approveERC20TokensForDeposit("0x718Ca123...", "1000000000000000000", {
    from: "0xABc578455..."
  })
  .on("onTransactionHash", txHash => {
    console.log("New transaction", txHash)
  })

matic.depositERC20Tokens(token, user, amount, options)

Deposit given amount of token with user user.

  • token must be valid ERC20 token address
  • user must be value account address
  • amount must be token amount in wei (string, not in Number)
  • options see more infomation here

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

const user = <your-address> or <any-account-address>

matic.depositToken('0x718Ca123...', user, '1000000000000000000', {
  from: '0xABc578455...'
})

matic.safeTransferFrom(token, tokenId, options)

Deposit given tokenId of token.

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

matic.safeTransferFrom('0x718Ca123...', '21', {
  from: '0xABc578455...'
})

matic.approveERC721TokenForDeposit(token, tokenId, options)

Approves given amount of token to rootChainContract.

  • token must be valid ERC721 token address
  • tokenId must be tokenId (string, not in Number)
  • options (optional) must be valid javascript object containing from, gasPrice, gasLimit, nonce, value, onTransactionHash, onReceipt or onError
  • from must be valid account address(required)
  • gasPrice same as Ethereum sendTransaction
  • gasLimit same as Ethereum sendTransaction
  • nonce same as Ethereum sendTransaction
  • nonce same as Ethereum sendTransaction
  • value contains ETH value. Same as Ethereum sendTransaction.
  • onTransactionHash must be function. This function will be called when transaction will be broadcasted.
  • onReceipt must be function. This function will be called when transaction will be included in block (when transaction gets confirmed)
  • onError must be function. This function will be called when sending transaction fails.

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

matic
  .approveERC721TokenForDeposit("0x718Ca123...", "21", {
    from: "0xABc578455..."
  })
  .on("onTransactionHash", txHash => {
    console.log("New transaction", txHash)
  })

matic.depositERC721Tokens(token, user, tokenId, options)

Deposit given tokenId of token with user user.

  • token must be valid ERC721 token address
  • user must be value account address
  • tokenId must be valid tokenId
  • options see more infomation here

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

const user = <your-address> or <any-account-address>

matic.depositERC721Tokens('0x718Ca123...', user, tokenId, {
  from: '0xABc578455...'
})

matic.depositEthers(options)

Deposit options.value

  • options see more infomation here.
  • value amount of ethers.
  • from must be valid account address(required)

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

matic.depositEthers({
  from: '0xABc578455...',
  value: '1000000000000000000'
})

matic.transferTokens(token, user, amount, options)

Transfer given amount of token to user.

  • token must be valid ERC20 token address
  • user must be value account address
  • amount must be token amount in wei (string, not in Number)
  • options see more infomation here
  • parent must be boolean value. For token transfer on Main chain, use parent: true

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

const user = <your-address> or <any-account-address>

matic.transferERC20Tokens('0x718Ca123...', user, '1000000000000000000', {
  from: '0xABc578455...',

  // For token transfer on Main network
  // parent: true
})

matic.transferERC721Tokens(token, user, tokenId, options)

Transfer ownership tokenId of token to user.

  • token must be valid ERC721 token address
  • user must be value account address
  • tokenId tokenId
  • options see more infomation here
  • parent must be boolean value. For token transfer on Main chain, use parent: true

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

const user = <your-address> or <any-account-address>

matic.transferERC721Tokens('0x718Ca123...', user, tokenId, {
  from: '0xABc578455...',

  // For token transfer on Main network
  // parent: true
})

matic.transferEthers(user, amount, options)

Transfer given amount of ethers to user.

  • user must be value account address
  • amount must be ethers amount in wei (string, not in Number)
  • options see more infomation here
  • parent must be boolean value. For ether transfer on Main chain, use parent: true

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

const user = <your-address> or <any-account-address>

matic.transferEthers(user, '1000000000000000000', {
  from: '0xABc578455...',

  // For token transfer on Main network
  // parent: true
})

matic.startWithdraw(token, amount, options)

Start withdraw process with given amount for token.

  • token must be valid ERC20 token address
  • amount must be token amount in wei (string, not in Number)
  • options see more infomation here

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

matic
  .startWithdraw("0x718Ca123...", "1000000000000000000", {
    from: "0xABc578455..."
  })
  .on("onTransactionHash", txHash => {
    console.log("Started withdraw process with txId", txHash)
  })

matic.startERC721Withdraw(token, tokenId, options)

Start withdraw process with given tokenId for token.

  • token must be valid ERC721 token address
  • tokenId must be token tokenId in wei (string, not in Number)
  • options see more infomation here

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

matic
  .startERC721Withdraw("0x718Ca123...", "21", {
    from: "0xABc578455..."
  })
  .on("onTransactionHash", txHash => {
    console.log("Started withdraw process with txId", txHash)
  })

matic.getHeaderObject(blockNumber)

Fetch header/checkpoint corresponding to blockNumber

  • blockNumber must be valid Matic's sidechain block number

This returns Promise object, which will be fulfilled when header/checkpoint is found corresponding to blockNumber.

Example:

matic.getHeaderObject(673874).then(header => {
  // header.start
  // header.end
  // header.proposer
  // header.number
})

matic.withdraw(txId, options)

Withdraw tokens on mainchain using txId from startWithdraw method after header has been submitted to mainchain.

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

matic.withdraw("0xabcd...789", {
  from: "0xABc578455..."
})

matic.processExits(rootTokenAddress, options)

Call processExits after completion of challenge period, after that withdrawn funds get transfered to your account on mainchain

This returns Promise object, which will be fulfilled when transaction gets confirmed (when receipt is generated).

Example:

matic.processExits("0xabcd...789", {
  from: "0xABc578455..."
})

matic.getTx(txId)

Get transaction object using txId from Matic chain.

  • txId must be valid tx id

This returns Promise object.

Example:

matic
  .getTx("0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b")
  .then(txObject => {
    console.log(txObject)
  })

matic.getReceipt(txId)

Get receipt object using txId from Matic chain.

  • txId must be valid tx id

This returns Promise object.

Example:

matic
  .getReceipt(
    "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b"
  )
  .then(obj => {
    console.log(obj)
  })

Support

Please post your queries to https://stack.matic.network for integration support. If you have any queries, feedback or feature requests, feel free to reach out to us on telegram: t.me/maticnetwork

License

MIT