Getting Started With Cargo JS

Cargo JS

Cargo JS can be used as a module within your app, or can be added directly to the browser using a script tag.

View the source on GitHub.

Supported wallets

Cargo JS has been tested with MetaMask for desktop, MetaMask for mobile, and the Coinbase Wallet app. It will work with any other wallet. If you have issues please email


yarn add @cargo-eth/js
import Cargo from '@cargo-eth/js';

Script Tag

When used in the browser Cargo JS will be added to the window and will be available at window.Cargo .

<script src=""></script>

The Cargo Class

new Cargo(options);

Use the Cargo class to create a class instance.


This method takes one argument which is an object with the following keys and values:



network - optional

Valid values: development, production

Defaults to development. Development connects to the Rinkeby network and production will connect to the main Ethereum network.


An instance of the Cargo class.


See below

Initializing Cargo

After installing Cargo you will need to create a new instance and initialize it. This will get the required information required for the library to interact with the Cargo smart contracts.Here is an example of initialization:

import Cargo from '@cargo-eth/js';
// Create a new instance of the Cargo class
const cargo = new Cargo({ network: 'development' });
// Add a listener that will tell us if the user has a provider, but
// it's not enabled
cargo.on('has-provider-but-not-enabled', () => {
// We can surface some UI saying the user needs to
// call the cargo.enable() method. If the user is using
// meta mask this event also tells us the user needs to connect
// meta mask to cargo - which will be done within the cargo.enable()
// method.
cargo.init().then(() => {
// Now that cargo is initialized we can call
// cargo.enable().

Enabling Cargo

After Cargo JS has been initialized you can call the enable function. If the user is using MetaMask they will be prompted to connect to Cargo. The reason there is an init AND an enable function is to allow for an opt in authentication flow. MetaMask already supports this and other wallets will catch on. Essentially you need to ask the user to enable their wallet to interact with your application. You can do this when the user takes an action rather than showing a pop up as soon as the user hits the page.

cargo.on('enabled', () => {
// Cargo is enabled and you can now call api methods
cargo.on('has-provider-but-not-enabled', () => {
// Can be dispatched from the enable or init method.
// If a user doesn't connect MetaMask to Cargo JS this will fire
cargo.on('accounts-change', (accounts) => {
// Will be dispatched when accounts change within MetaMask
// Can be used to reload data in your app.
cargo.enable().then(isEnabled => {
// If isEnabled do something
// Else do something else.

Interacting with the APIs

After Cargo JS has been enabled you can access the API methods. Methods that do not require MetaMask can be called before enabling Cargo JS. You can learn about all the API methods here.

cargo.api.getBeneficiaryBalance(beneficiaryId).then((response) => {
// Do something.