cargo.api

cargo.api exposes methods that can be called without an Ethereum enabled browser (provider) along with methods that require an Ethereum enabled browser. Methods that require a provider can be called after calling cargo.enable . Some methods will require authentication. An authentication token is provided after calling the register, or authenticate methods - both of which require an Ethereum enabled browser.

How things are documented

Each method will be described in English and then an example call of the method will be documented. Arguments are described using English while return types are described using TypeScript types. Arguments are required unless they are specified as optional.

Emoji Legend

🌎 - Open method, authentication not required

đŸĻŠ - Method requiring MetaMask, or similar Web3 browser or extension. These methods use Web3 API's.

🔒 - Authenticated method, authentication required. A pre-requisite to authentication is getting an access token and to get an access token requires MetaMask or something like it. So by default all authenticated methods are also đŸĻŠ.

🍕 - Optional authenticated method. Authentication is optional and may affect response.

​

Get a list of collectibles 🌎

You can use this method to get a paginated list of collectibles for any collection that adheres to the ERC-721 specification and includes the enumeration extension.

cargo.api.getTokensByContract(options).then(response => {
// Do something with response
});
Arguments
Response
Arguments

Argument

Description

options

An object containing the following properties:

  • contractAddress - Required. Address of the contract you wish to query

  • page - Optional. Optional page for pagination.

  • limit - Optional. Limit the number of results returned. Defaults to 10.

  • ownerAddress - Optional. Only tokens owned by this address will be returned in the response.

Response
type SuccessResponse = {
err: false,
status: 200,
data: {
// Contract name
name: string;
// Contract symbol
symbol: string;
// Array of tokens
results: {
tokenId: string;
metadata: { [key: string]: any };
tokenURI: string;
resaleItem?: {
seller: string;
contract: string;
tokenId: string;
price: string;
signatureGenerated: boolean;
crate?: string;
metadata: { [key: string]: any };
}
}[],
// Total number of tokens in contract,
// or total number of tokens owned by address
// passed as "ownerAddress"
totalSupply: string;
// Current page
page: string;
// Limit
limit: string;
// Total number of pages
totalPages: string;
}
}

Get collectible details 🌎

You can use this method the get details for a given collectible.

cargo.api.getTokenDetails(collectionAddress, collectibleId).then(response => {
// Do something with response
});
Arguments
Response
Arguments

Argument

Description

collectionAddress

The address of the collection.

collectibleId

The ID of the collectible within the collection.

Response
type Response = {
err: boolean,
status: number,
data: {
// Username of owner
owner?: string,
// Address of owner
ownerAddress: string,
// If this item is for sale, details about sale
resaleItem?: {
seller: string,
contract: string,
tokenId: string,
price: string,
signatureGenerator?: boolean,
groupId: string
crate: string,
createdAt: string,
},
// Collectible ID
tokenId: string,
// Name of collection token belongs to
contractName: string,
// Symbol of collection token belongs to
contractSymbol: string,
}
}

Get a list of collectibles that are for sale 🌎 🍕

You can use this method to get a paginated list of collectibles that are for sale. You can filter collectibles in the response. See arguments for details.

cargo.api.getResaleItems(options).then(response => {
// Do something with response
});
Arguments
Response
Arguments

Argument

Description

options

An object that contains the following properties:

  • showcaseId - Optional. String. Display resale items by a given showcase.

  • collectionId - Optional. String. Display resale items for a given collection.

  • collectionAddress - Optional. String. Display resale items for a given collection address.

  • page - Optional. String. Page in results to display.

  • limit - Optional. String. Limit of results per page.

  • owned - Optional. Boolean. Display resale items that are owned by the current authenticated user only.

  • slug - Optional. String. Filter resale items by showcase slug. Can be used as an alternative to showcaseId. slugId required when this is passed.

  • slugId - Optional. String. Required when slug is passed

  • seller - Optional. String. Ethereum wallet address of seller. Will only return items for this seller.

  • sort - Optional. String. One of new , high-to-low , or low-to-high

  • filter- Optional. An Object containing the following keys and values:

    • containsGems - Optional. Boolean.

    • builtOnCargo - Optional. Boolean.

    • threed - Optional. Boolean.

    • audio - Optional. Boolean.

    • video - Optional. Boolean.

    • image - Optional. Boolean.

Response
type SuccessResponse = {
err: false,
status: 200,
data: {
limit: string;
page: string;
totalPages: string;
results: {
// Will be blank if ERC-721. If ERC-1155
// type will be '1155'
type: '1155' | void;
seller: string;
// ID of the collection
contract: string;
// Id of the collectible
tokenId: string;
// Price in Wei that the collectible is selling for
price: string;
// If owned is true this will show the user if purchase signatures
// have been generated. If they have cancelling the sale safely will
// require a transaction to be submitted.
signatureGenerated?: boolean;
// Will only be in response if owned is set to true. This can be
// used to safely cancel a sale. You can use the cancelSale method
// and Cargo JS will handle this for you.
groupId?: string;
// Showcase ID resale item belongs to
crate?: string;
createdAt: string;
}[]
}
}

Get a list of collections on Cargo 🌎 🍕

You can use this method to get a paginated list of collections (ERC-721 contracts). You can filter contracts in the response. See arguments for details.

cargo.api.getContracts(options).then(response => {
// Do something with response
});
Arguments
Response
Arguments

Argument

Description

options

An object containing the following properties:

  • page - Optional. String. Page of results to display. Defaults to 1.

  • limit - Optional. String. Limit of collections per page. Defaults to 10.

  • showcaseId - Optional. String. Limit results to show only collections in the given showcase.

  • owned - Optional. Boolean. Show only collections that the current authenticated user owns.

  • address - Optional. String. Ethereum wallet address. If specified will only return collections for a given user.

  • skipAuth - Optional. Boolean. Will not use current logged in users address if true.

  • hasTokens - Optional. Boolean. Will only return collection if the user owns at least one NFT within that collection.

  • cargoContract - Optional. Boolean. Return only collections created on Cargo.

  • useAuthToken - Optional. Boolean. Show only collections that the current authenticated user either owns, or has collectibles in. Collections within response will contain an additional contractTokens property stating how many collectibles the user owns within that collection. This takes precedence over the owned parameter.

Response
type Response = {
err: boolean,
status: number,
data: {
results: {
// ID of collection
_id: string,
address: string,
name: string,
symbol: string,
supportsMetadata: boolean,
createdAt: string,
// total number of owned collectibles in collection
// Available only when useAuthToken === true
totalOwned?: number,
// Available only when useAuthToken === true
owned?: boolean,
}[],
limit: string,
totalPages: string,
total: string,
page: string,
}
}

Get a showcase by ID 🌎 🍕

You can use this method to get information about a showcase by it's ID. If the showcase is private you will need to be authenticated and be either the owner or the vendor of that showcase.

cargo.api.getShowcaseById(showcaseId, auth).then(res => {
// do something with response
});
Arguments
Response
Arguments

Argument

Description

showcaseId

Required. String. The ID of the showcase

auth

Optional. Boolean. If true you must be authenticated and your authentication token will be sent in with the request. This will be required to get information about a private showcase.

Response
type SuccessResponse = {
err: false,
status: 200,
data: {
name: string,
createdAt: string,
public: boolean,
slug: string,
slugId: string,
owner: string,
resellingEnabled: boolean,
isOwner?: boolean;
isVendor?: boolean;
}
}

Get a showcase by it's slug 🌎

You can use this method to get a showcase by its slug and slug ID.

cargo.api.getShowcaseBySlug(slug, slugId).then(res => {
// do something
});
Arguments
Response
Arguments

Argument

Description

slug

Required. String. The slug of the showcase

slugId

Required. String. Slug ID of the showcase.

Response
type SuccessResponse = {
err: false,
status: 200,
data: {
name: string,
createdAt: string,
public: boolean,
slug: string,
slugId: string,
owner: string,
resellingEnabled: boolean,
isOwner?: boolean;
isVendor?: boolean;
}
}

Get information about a collection 🌎 🍕

You can use this method to get information about a collection. A requirement is that the specified collection (ERC-721 contract address) must exist in the Cargo system. This contract doesn't necessarily need to be created on Cargo, but it needs to have been indexed by Cargo. Contracts are indexed when you register with your Ethereum address. If an auth token is present then an additional isOwned value will be returned in the response.

You can also pass the showcase slug and slugId to determine if the given collection is within that showcase

cargo.api.getContractMetadata(contractAddress, useAuth, slug, slugId)
.then(response => {
// Use response
});
Arguments
Response
Arguments

Argument

Description

contractAddress

Required. The address of the collection to get information for.

useAuth

Optional. If true this method requires authentication. Will return isOwned boolean in response.

slug

Optional. Showcase slug to check if collection is contained within showcase.

slugId

Optional. Slug ID associated with passed in slug argument.

Response
type SuccessResponse = {
err: false;
status: 200;
data: {
totalSupply: number;
address: string;
name: string;
cargoContract: boolean;
symbol: string;
supportsMetadata: boolean;
createdAt: string;
}
}

Get orders 🔒

You can retrieve orders for collectible sales which relate to you.

cargp.api.orders(options).then(res => {
// do something with response
});
Arguments
Arguments

Argument

Description

options

An object that contains the following:

  • contractAddress - Optional. String. Collection address to filter orders by

  • vendorId - Optional. String

  • sellerAddress - Optional. String

  • buyerAddress - Optional. String

  • tokenId - Optional. String

  • crateId - Optional. String. Showcase ID

  • from - Optional. String. ISO date string

  • to - Optional. String. ISO date string

  • limit - Optional. String. Limit of results per page

  • page - Optional. String. Page of paginated results to return

Bulk metadata update 🔒

You can use this method to update the metadata for many collectibles in a collection at one time. Existing metadata for specified collectibles will be replaced.

// Updates are made using an object where the keys represent the
// token ID to be updated and the value is a JSON serializable object
// which is the update.
​
// For example:
const updates = {
// 1 is the ID of the collectible and the value
// is the new metadata
1: {
name: 'Crypto hero',
description: 'Something about this collectible',
},
2: {
name: 'Crypto Goblin',
description: 'Something about this collectible',
},
}
​
cargo.api.bulkMetadataUpdate(collectionAddress, updates).then(response => {
if(response.status === 200) {
// success
}
});
Arguments
Response
Arguments

Argument

Description

collectionAddress

The collection in which to update collectible metadata

updates

An object where keys represent the collectible ID and the value is a JSON serializable object containing the new metadata

Response
type SuccessResponse = {
status: 200,
err: false,
data: {
code: 'success',
}
}

Add collectibles to a showcase 🔒

You can use this method to add individual NFTs to a showcase.

cargo.api.addCollectiblesToShowcase(items, showcaseId).then(response => {
if(response.status === 200) {
// Success
}
});
Arguments
Response
Arguments

Argument

Description

items

An object where the keys are collection addresses and the values are arrays of token IDs. Ex:{[collectionAddress]: [1, 2, 3]}

showcaseId

The ID of the showcase to add the collectibles to.

Response
type SuccessResponse = {
err: false,
status: 200,
data: {
success: true,
}
}

Remove collectibles from a showcase 🔒

You can use this method to remove NFTs from a showcase.

cargo.api.removeCollectiblesFromShowcase(items, showcaseId).then(res => {
if(res.err === false) {
// done
}
});
Arguments
Response
Arguments

Argument

Description

items

An object where the keys are collection addresses and the values are arrays of token IDs. Ex:{[collectionAddress]: [1, 2, 3]}

showcaseId

The ID of the showcase to remove collectibles from.

Response
type SuccessResponse = {
err: false,
status: 200,
data: {
success: true,
}
}

Get collectibles for a user by collection 🌎 🍕

You can use this to get the owned collectibles for a user in a given collection. The contractId is not the address of the collection, but the ID which can be retrieved using the getContracts method.

cargo.api.getUserTokensByContract(options).then(response => {
// Do something with response
});
Arguments
Response
Arguments

Argument

Description

options

An object that has the following properties:

  • page - Optional. String. Page of results to display.

  • limit - Optional. String. Limit of results to display per page.

  • contractId - Required. String. ID of collection

  • address - Optional. String. Ethereum wallet address of user. Should set skipAuth option to true when using address.

  • skipAuth - Optional. Boolean. Skips using the current logged in users address and will use the address value.

Response
type SuccessResponse = {
err: false,
status: 200,
data: {
results: {
tokenId: string,
metadata: {},
tokenURI: string,
}[],
limit: string,
totalPages: string,
page: string,
total: string
}
}

Get all collectibles for a user 🌎

You can use this method to get all compatible collectibles for a given Ethereum wallet. The wallet needs to be associated with a registered user on Cargo.

cargo.api.getAllUserCollectibles(options).then(res => {
if(res.err === false) {
// do something
}
});
Arguments
Response
Arguments

Argument

Description

options

An Object containing the following properties

  • address - Required. String. The Ethereum wallet to fetch NFTs for.

  • page - Optional. String. The page used for pagination.

  • limit - Optional. String. The max number of results to return.

Response
type SuccessResponse = {
results: {
tokenId: string;
metadata: Record<string, any>;
tokenURI: string;
resaleItem?: {
sellerAddress: string;
tokenAddress: string;
tokenId: string;
resaleItemId: string;
price: string;
fromVendor: boolean;
metadata: Record<string, any>;
};
owner: string;
collection: {
_id: string;
address: string;
name: string;
symbol: string;
supportsMetadata: boolean;
tags?: string[];
owned?: boolean;
totalOwned?: number;
createdAt: string;
};
}[];
page: string;
limit: string;
totalPages: string;
};

Get showcases for a user 🔒

You can use this method to get a paginated list of the showcases the authenticated user has created.

cargo.api.getUserShowcases(options).then(response => {
// Do something with response
});
Arguments
Response
Arguments

Argument

Description

options

An optional object with the following properties:

  • page - String. Optional. Page number of results to return.

  • limit - String. Optional. Limit of results to display on each page.

Response
type Response = {
err: boolean,
status: number,
data: {
results: {
name: string,
id: string,
}[],
// Total number of showcases created
total: string,
// Current page
page: string,
// Limit
limit: string,
// Total number of pages
totalPages: string,
}
}

Get all collectibles in a showcase 🌎

You can use this method to get all collectibles in a given showcase.

cargo.api.getAllShowcaseItems(showcaseId, page, limit).then((res) => {
if(res.err === false){
// console.log(res.data);
}
});
Arguments
Response
Arguments

Argument

Description

showcaseId

Required. String. The ID of the showcase to retrieve items for

page

Optional. String. The page specified for pagination

limit

Optional. String. The max number of items to return in the response.

Response
type SuccessResponse = {
err: false;
status: 200;
data: {
results: {
tokenId: string;
metadata: Record<string, any>;
resaleItem?: {
sellerAddress: string;
tokenAddress: string;
tokenId: string;
resaleItemId: string;
price: string;
fromVendor: boolean;
metadata: Record<string, any>;
};
collection: {
_id: string;
address: string;
name: string;
symbol: string;
supportsMetadata: boolean;
tags?: string[];
owned?: boolean;
totalOwned?: number;
createdAt: string
};
}[];
page: string;
totalPages: string;
limit: string;
}
}

Get items for sale in a showcase 🌎

You can use this method to get a list of NFTs for sale in a given showcase.

cargo.api.getShowcaseItemsForSale(options).then((res) => {
if(res.err === false){
// do something
}
});
Arguments
Arguments

Argument

Description

options

Required. An Object containing the following keys and values

  • page - Optional. String. The page specified for pagination.

  • limit - Optional. String. The max number of items to return in the response.

  • showcaseId - Required. String. The showcase ID to retrieve items for.

  • sort - Optional. String. One of new , high-to-low , or low-to-high

  • filter - Optional. An Object containing the following keys and values:

    • containsGems - Optional. Boolean.

    • builtOnCargo - Optional. Boolean.

    • threed - Optional. Boolean.

    • audio - Optional. Boolean.

    • video - Optional. Boolean.

    • image - Optional. Boolean.

Get vendors in a showcase 🔒

You can use this method to get a paginated list of vendors for a given showcase. The authenticated user must be the owner of the showcase.

cargo.api.getShowcaseVendors(showcaseId, page, limit).then(response => {
// Do something with response
});
Arguments
Response
Arguments

Argument

Description

showcaseId

ID of showcase to return vendors for.

page

Page of results to start returning results at.

limit

Limit of results per page

Response
type Response = {
err: boolean,
status: number,
data: {
results: {
// Address of vendor
address: string
// Cargo id of vendor
_id: string,
// Username of vendor
displayUsername: string,
}[],
// Total number of showcases created
total: string,
// Current page
page: string,
// Limit
limit: string,
// Total number of pages
totalPages: string,
}
}

Get beneficiaries for a vendor 🔒

You can use this method to get a paginated list of beneficiaries for the given vendor. Vendors are in relation to a showcase so a showcase ID is also required.

cargo.api.getVendorBeneficiaries(vendorAddress, showcaseId).then(results => {
// Do something with results
});
Arguments
Response
Arguments

Argument

Description

vendorAddress

The address of the vendor

showcaseId

The showcase the vendor belongs to for which you'd like to retrieve beneficiaries for.

Response
type Response = {
err: boolean,
status: number,
data: {
results: {
// The address of the beneficiary
address: string,
// The commission of the beneficiary
commission: string,
// The address of the vendor for whom this
// beneficiary belongs to
vendorAddress: string,
// The showcase ID
crateId: string,
// Timestamp for when the vendor was created
createdAt: string,
}[],
// Total number of showcases created
total: string,
// Current page
page: string,
// Limit
limit: string,
// Total number of pages
totalPages: string,
}
}

Create an account đŸĻŠ

You can use this method to create a new Cargo account. The response will contain an JSON web token that is used to make authenticated requests. Cargo JS stores this token for you so you don't need to worry about storing it. When creating an account the user will be asked to sign a message to prove they are who they say they are.

cargo.api.register(email, username).then(response => {
if(response.status === 200) {
// User has been created and is authenticated
// for future requests
}
});
Arguments
Response
Arguments

Argument

Description

email

Valid email address that will be tied to the account

username

Username to be used for new account

Response
type Response = {
err: boolean,
status: number,
data: {
// JSON web token
token: string,
}
}

Authenticate existing account đŸĻŠ

You can use this method to authenticate and existing account. The response will contain an JSON web token that is used to make authenticated requests. Cargo JS stores this token for you so you don't need to worry about storing it. When authenticating an account the user will be asked to sign a message to prove they are who they say they are.

cargo.api.authenticate().then((response) => {
if(response.status === 200){
// User is authenticated
}
});
Arguments
Response
Arguments

This method does not take any arguments.

Response
type SuccessResponse = {
err: false,
status: 200,
data: {
// JSON web token
token: string
}
}
​
​
// If an account is required you will get this response
type AccountRequiredResponse = {
err: true,
status: 401,
data: {
code: 'account-required'
}
}

Get Cargo credit balance đŸĻŠ

Use this method to get the Cargo credit balance of the current user. Cargo credits are required to create collectibles.

cargo.api.getMintingCreditBalance().then(balance => {
// Do something with balance
});
Arguments
Description
Arguments

This method doesn't take any arguments.

Description

This method returns the balance of Cargo credits for the current user.

Purchase a collectible đŸĻŠ

You can use this method to purchase a collectible. You do not need to have registered an account on Cargo to use this method. You will just need a Web3 enabled browser.

cargo.api.purchase(collectibleId, collectionAddress).then(txHash => {
// Transaction submitted
});
Arguments
Response
Arguments

Argument

Description

collectibleId

The ID of the collectible to purchase

collectionAddress

The address of the collection (ERC-721 contract) that contains the collectible.

Response

The response will contain a transaction hash.

Transfer a collectible đŸĻŠ

You can use this method to transfer a collectible you own to another address.

cargo.api.transferCollectible(contractAddress, tokenId, toAddress).then(txHash => {
// Transaction submitted
});
Arguments
Response
Arguments

Argument

Description

contractAddress

The collection address for which the collectible belongs to.

tokenId

The ID of the collectible to transfer.

toAddress

The Ethereum address to transfer the collectible to.

Response

The response will contain a transaction hash.

Burn a collectible đŸĻŠ

You can use this method to transfer a collectible you own to another address. The contract needs to be an ERC-721 contract created on Cargo, or a contract that supports the following function:

function burn(uint256 tokenId) public

cargo.api.burn(collectionAddress, tokenId).then(txHash => {
// Transaction submitted
});
Arguments
Response
Arguments

Argument

Description

collectionAddress

Address of collection

tokenId

The ID of the collectible to burn.

Response

The response will contain a transaction hash.

Sell a collectible đŸĻŠ 🍕

Owners of a collectible can sell a collectible through Cargo by using this method. Cargo must be approved to transfer the collectible on your behalf. This method will verify that Cargo is approved to transfer your collectible. If Cargo is not approved the setApprovalForAll method will be called before marking the item for sale. Cargo

cargo.api.sell(options, unapprovedFn).then(response => {
if(!response.err){
// Item has been marked for sale
}
});
Arguments
Response
Arguments

Argument

Description

options

An object with the following properties:

  • contractAddress - Required. The address of the collection containing the collectible to sell.

  • tokenId - Required. The ID of the collectible.

  • price - Required. The price, in Wei, of the collectible.

  • crateId - Optional. The showcase ID representing the showcase in which this item will be displayed for sale in.

​

unapprovedFn

This is an optional function that will be called if the sale requires an approval from the collection smart contract. This is could be used to display a blocking modal which can then be removed once the method resolves completely.

Response
type Response = {
err: boolean,
status: number,
data: {
// ID of newly created resale item
resaleItemId: string,
}
}

Cancel a sale đŸĻŠ 🍕

You can cancel a sale by using this method. You must either have authenticated with the same address used to initiate the sale of the item, or you must be able to sign a message with that address. For security purposes, if a signature has been generated for the purchase of this collectible you will be required to execute a transaction to Cargo's smart contract to ensure the collectible cannot be sold. This method will automatically call the smart contract method if it is required.

cargo.api.cancelSale(resaleItemId).then(response => {
// Response will contain either a transaction hash
// or a typical Cargo response.
});
Arguments
Response
Arguments

Argument

Description

resaleItemId

The ID of the resale item.

Response

If signatures have been generated to purchase this item then a transaction will be required. The response will contain a transaction hash. If no transaction is required then signatures have not been generated. response will have the following shape if no signatures were generated:

type Response = {
status: 200,
err: false,
data: {
signatureGenerated: false,
code: 'success',
}
}

Create a showcase 🔒

You can use this method to create a new showcase.

cargo.api.createShowcase(showcaseName, description, bannerFile).then(response => {
if(response.status === 200) {
// Showcase created
}
});
Arguments
Response
Arguments

Argument

​

showcaseName

Required. String. The name of your new showcase

description

Optional. String. Description of your showcase. Max length 120 characters.

bannerFile

Optional. File. Banner file. Max size 2mb

Response
type Response = {
err: false,
status: 200,
data: {
showcaseId: string
}
}

Modify a showcase 🔒

You can use this method to modify an existing showcase.

cargo.api.modifyShowcase(showcaseName, update).then(response => {
if(response.status === 200) {
// Showcase created
}
});
Arguments
Arguments

Argument

​

showcaseName

Required. String. The name of your new showcase

update

Required. Object. An object containing the following properties:

  • name - Optional. String

  • description - Optional. String

  • file - Optional. FIle.

Set application fee for a showcase đŸĻŠ 🔒

You can use this method to set an application fee for a showcase. An application fee is the percentage of funds the showcase owner will receive upon the selling of a vendor collectibles in that showcase. The fee can be from 0 to 0.2 meaning the maximum percentage a showcase owner can receive is 20% of each sale.

cargo.api.setShowcaseApplicationFee(fee, showcaseId).then(txHash => {
// Tx submitted
});
Arguments
Response
Arguments

Argument

Description

fee

A number from 0 to 0.2 representing the fee as a percentage

showcaseId

ID of the showcase to add the fee to.

Response

The response will contain a transaction hash.

Remove a vendor đŸĻŠ 🔒

An owner of a showcase can use this method to remove a vendor from within that showcase.

cargo.api.removeVendor(vendorAddress, showcaseId).then(txHash => {
// Transaction has been submitted. cargo.pollTx will emit an event
// when the transaction has been confirmed.
});
Arguments
Response
Arguments

Argument

Description

vendorAddress

Address of the vendor to remove

showcaseId

ID of the showcase to remove the vendor from

Response

The response will contain a transaction hash.

Create a new collection (ERC-721 contract) đŸĻŠ 🔒

You can use this method to create a new collection (ERC-721 contract) on the Ethereum blockchain. This method will require the user submitting the transaction to pay the required fees for deploying a new collection. You can pass in an optional Showcase ID to automatically add the collection to that Showcase after it's been created. The cost will be 0.1 ETH (the standard cost to create a Cargo ERC-721 contract).

cargo.api.createContract(name, symbol, showcaseId).then(txHash => {
// Transaction has been submitted
});
Arguments
Response
Arguments

Argument

Description

name

Name of your collection

symbol

Ticker symbol of your collection

showcaseId

Optional. Showcase ID in which the collection will be added to after creation.

Response

The response will contain a transaction hash.

Create new collectibles đŸĻŠ 🔒

Use this method to create new collectibles. You can use this method to create one or many collectibles depending on the amount of Cargo credits you have. When creating many collectibles they will all initially share the same name, description, preview image, metadata, and associated files. Cargo will add an "edition" field to the JSON metadata file associated with the collectible which corresponds to the consecutive collectible ID. If you need to update these fields for individual collectibles you can use the Bulk Metadata Update method to accomplish this.

cargo.api.mint(options).then(txHash => {
// Transaction submitted
});
Arguments
Response
Arguments

Argument

Description

options

Options is an object with the following fields:

  • contractAddress - The address of the contract to create collectibles in.

  • amount - The number of collectibles to create

  • to - The address in which to send the collectible(s)

  • name - Optional. Name of collectible(s)

  • description - Optional. Description of collectible(s)

  • metadata - Optional. JSON serializable object containing arbitrary metadata for your collectible(s)

  • previewImage - Optional. A File.

  • files - Optional. An array of Files that only the owner of the collectible will have access to.

  • method - Optional. Valid options are mint and batchMint. This will default to batchMint which should be valid in most cases.

Response

The response will contain a transaction hash.

Add a vendor đŸĻŠ 🔒

In order for any user to sell items in a showcase they must be added as a vendor to that showcase (including the owner of the showcase). Use this method to add vendors to a showcase.

cargo.api.addVendor(vendorAddress, showcaseId).then(txHash => {
// Transaction submitted
});
First Tab
Second Tab
First Tab

Argument

Description

vendorAddress

The address of the vendor to add to the showcase

showcaseId

The ID of the showcase

Second Tab

The response will contain a transaction hash.

Add a beneficiary đŸĻŠ 🔒

A vendor can use this method to add a beneficiary.

cargo.api.addBeneficiary(showcaseId, beneficiaryAddress, commission)
.then(txHash => {
// transaction submitted
})
.catch(e => {
// something went wrong
});
Arguments
Response
Arguments

Argument

Description

showcaseId

ID of the showcase that the user submitting the transaction is a vendor in. The beneficiary will be added to that vendor within that showcase.

beneficiaryAddress

The address of the beneficiary you'd like to add

commission

A number between 0 and 1 representing the percentage of each sale this beneficiary will receive.

Response

The response will contain a transaction hash.

Remove a beneficiary đŸĻŠ 🔒

Vendors can use this method to remove a beneficiary. The sending address must represent the vendor and the beneficiary address passed to the method must be owned by the vendor. The showcase ID must represent the showcase in which the beneficiary and vendor reside.

cargo.api.removeBeneficiary(beneficiaryAddress, showcaseId).then((txHash) => {
// Transaction submitted
});
Arguments
Response
Arguments

Argument

Description

beneficiaryAddress

The beneficiaries address

showcaseId

The ID of the showcase containing the beneficiary

Response

The response will contain a transaction hash.

Update the commission of a beneficiary đŸĻŠ 🔒

Use this method to update the commission of an existing beneficiary.

cargo.api.updateBeneficiaryCommission(beneficiaryAddress, commission, showcaseId)
.then(txHash => {
// Transaction submitted
});
Arguments
Response
Arguments

Argument

Description

beneficiaryAddress

The address of the beneficiary to update the commission for.

commission

A number between 0 and 1 representing the percentage of each sale this beneficiary will receive.

showcaseId

The ID of the showcase the vendor and beneficiary belongs to.

Response

The response will contain a transaction hash.

Gems

Approve Gems to be staked đŸĻŠ

This method is used to approve the Cargo NFT staking contract to transfer Gems on the callers behalf. The amount argument must account for Gems 18 decimal points. For example if you want to approve 100 Gems you could do the following: const amount = new cargo.BigNumber(100).times(10 ** 18).toFixed()

Under the hood this calls the ERC-20 approve method.

cargo.api.approveGems(amount: string).then(txReceipt => {});
Arguments
Response
Arguments

Argument

Description

amount

A string. The amount the caller wants to approve.

​

Response

This method returns a promise which resolves a Web3 transaction receipt. You can use the PollTx class to listen for when this transaction completes.

Stake Gems đŸĻŠ

You can use this method to stake Gems within an owned NFT. The caller must first have approved an amount greater than or equal to the amount they wish to stake by using the .approveGems method.

cargo.api.stakeGems(contractAddress: string, tokenId: string, amount: string)
.then(txReceipt => {});
Arguments
Response
Arguments

Argument

Description

contractAddress

String. The address of the collection that contains the NFT to stake.

tokenId

String. The ID of the NFT to stake.

amount

String. The amount of Gems the caller wishes to stake. Must account for the 18 decimal points of the Gems contract. ex. 1 Gem = 1 * 10 ** 18

Response

This method returns a promise which resolves a Web3 transaction receipt. You can use the PollTx class to listen for when this transaction completes.

Get staked tokens for a given address 🌎

This method will list all of NFTs that a given wallet address has staked.

cargo.api.getStakedTokens(address: string).then(res => {
if(res.err === false) {
// do something
}
});
Arguments
Response
Arguments

Argument

Description

address

String. The wallet address to retrieve a list of staked tokens for.

Response
type SuccessResponse = {
err: false,
statue: 200,
data: {
// Total amount of Gems a user has staked across all NFTs
// This value has already been converted to 18 decimal places for you.
totalStakedAmount: string;
// Total amount of rewards for user across NFTs
// Currently Cargo Gems and Cargo Credit rewards
// we be equal so this is the total available rewards
// which can be used to represent rewards in both tokens.
// This value has already been converted to 18 decimal places for you.
totalAvailableRewards: string;
// List of staked tokens
tokens: {
contract: string;
owner: string;
tokenId: string;
// This value will need to be converted to 18 decimal places
// ex: const num = new cargo.BigNumber(stakedAmount).div(10 ** 18).toFixed(5)
stakedAmount: string;
// Total rewards which can be used to represent total reward value
// of Gems independently from the total reward value of Credits
// This value has already been converted to 18 decimal places for you.
totalRewards: string;
details: {
owner?: string;
ownerAddress: string;
tokenId: string;
metadata?: { [key: string]: any };
tokenURI: string;
contractName: string;
contractSymbol: string;
contractAddress: string;
resaleItem?: {
seller: string;
contract: string;
tokenId: string;
price: string;
signatureGenerated: boolean;
groupId: string;
crate?: string;
createdAt: string;
metadata?: { [key: string]: any };
};
};
}[]
}
}

Claim and stake rewards đŸĻŠ

This method can be used to claim and stake rewards automatically so those rewards can be compounded. This serves as a convenience method so the user does not need to withdraw their rewards from the staking contract before staking them.

cargo.api.claimAndStakeRewards(contractAddress: string, tokenId: string)
.then(txReceipt => {});
Arguments
Response
Arguments

Argument

Description

contractAddress

String. The contract address in which the staked NFT was created in.

tokenId

String. The ID of the staked NFT.

Response

This method returns a promise which resolves a Web3 transaction receipt. You can use the PollTx class to listen for when this transaction completes.

Batch claim and stake rewards

Use this method to trigger multiple transactions. This uses the web3.BatchRequest method under the hood.

cargo.api.batchClaimAndStakeRewards(data).then(() => {});
Arguments
Arguments

Argument

Description

data

An Array of Objects containing the following properties:

  • address - Required. String. ERC-721 contract address

  • tokenId - Required. String. The NFT token ID to claim and re-stake.

  • web3TxParams - Optional. An object that will be merged into the web3 request parameters.

Get the staked amount for a given token ID

You can use this method to get the total Gems staked in a given NFT.

cargo.api.getTokenStake(address, tokenId).then(balance => {})

​

Arguments
Arguments

Argument

Description

address

Required. String. The ERC-721 collection address.

tokenId

Required. String. The token ID

Withdraw đŸĻŠ

This method can be used to withdraw Gems from a staked NFT. The amount argument must account for Gems 18 decimal points. For example if you want to approve 100 Gems you could do the following: const amount = new cargo.BigNumber(100).times(10 ** 18).toFixed()

cargo.api.withdraw(contractAddress: string, tokenId: string, amount: string)
.then(txReceipt => {})
Arguments
Response
Arguments

Argument

Description

contractAddress

String. The contract address in which the staked NFT was created in.

tokenId

String. The ID of the staked NFT.

amount

String. The amount of Gems to withdraw from specified NFT.

Response

This method returns a promise which resolves a Web3 transaction receipt. You can use the PollTx class to listen for when this transaction completes.

Selling ERC-1155 Collectibles

Cargo JS supports the buying and selling of ERC-1155 tokens the same way it supports ERC-721. You can use the getResaleItems method to view which ERC-1155 tokens are for sale and you can cancel a sale using the cancelSale method.

sellErc1155(options) đŸĻŠđŸ•

This method can be used to sell up to 50 different token types at once. If this is the first time you are calling this method for the given wallet address you will be required to submit a transaction to approve Cargo to sell on your behalf. If the calling wallet address is not authenticated then this method will ask the user to sign a message to prove ownership of the current address. Signatures are cached using session storage, so this only need to be done once per session.

cargo.api.sellErc1155({
// The token ids representing collectibles you wish to sell
// Index of ID must correspond to an item in the values array
ids: ['1', '2', '3'],
// The number of each ID to sell. Values must be in the same
// index as the respective ID
values: ['10', '2', '50'],
// The asking price in Wei
price,
// The contract these tokens exist within
contractAddress,
// Optional showcase ID this contract belongs to
// useful for setting application fees
showcaseId
}, unapprovedFn).then(res => {
// Do something
});
Arguments
Response
Arguments

Argument

Description

options

An object with the following keys and values

​

  • ids - Required - An array of IDs you wish to include in this sale

  • values - Required - The corresponding values representing the number of each ID to include in this sale.

  • price - Required - String - The asking price in Wei

  • contractAddress - Required - String - The address of the contract these tokens exist within

  • showcaseId - Optional - String- The ID representing the showcase this contract resides in. The contract must be added to this showcase prior to calling this method - see Adding a collection to a showcase​

​

unapprovedFn

This is an optional function that will be called if the sale requires an approval from the collection smart contract. This is could be used to display a blocking modal which can then be removed once the method resolves completely.

Response

This function returns a promise which resolves with the following response if successful:

type SuccessResponse = {
err: false;
status: 200;
data: {
// The ID that can be used to purchase your tokens
resaleItemId: string;
}
}

purchaseErc1155(resaleItemId) đŸĻŠ

This method can be used to purchase ERC-1155 tokens after they have been set for sale.

cargo.api.purchaseErc1155(resaleItemId).then(txHash => {
// do something
})
Arguments
Response
Arguments

Argument

Description

resaleItemId

The ID of the sale.

Response

This method will return a transaction hash.

Contents
How things are documented
Emoji Legend
Get a list of collectibles 🌎
Get collectible details 🌎
Get a list of collectibles that are for sale 🌎 🍕
Get a list of collections on Cargo 🌎 🍕
Get a showcase by ID 🌎 🍕
Get a showcase by it's slug 🌎
Get information about a collection 🌎 🍕
Get orders 🔒
Bulk metadata update 🔒
Add collectibles to a showcase 🔒
Remove collectibles from a showcase 🔒
Get collectibles for a user by collection 🌎 🍕
Get all collectibles for a user 🌎
Get showcases for a user 🔒
Get all collectibles in a showcase 🌎
Get items for sale in a showcase 🌎
Get vendors in a showcase 🔒
Get beneficiaries for a vendor 🔒
Create an account đŸĻŠ
Authenticate existing account đŸĻŠ
Get Cargo credit balance đŸĻŠ
Purchase a collectible đŸĻŠ
Transfer a collectible đŸĻŠ
Burn a collectible đŸĻŠ
Sell a collectible đŸĻŠ 🍕
Cancel a sale đŸĻŠ 🍕
Create a showcase 🔒
Modify a showcase 🔒
Set application fee for a showcase đŸĻŠ 🔒
Remove a vendor đŸĻŠ 🔒
Create a new collection (ERC-721 contract) đŸĻŠ 🔒
Create new collectibles đŸĻŠ 🔒
Add a vendor đŸĻŠ 🔒
Add a beneficiary đŸĻŠ 🔒
Remove a beneficiary đŸĻŠ 🔒
Update the commission of a beneficiary đŸĻŠ 🔒
Gems
Approve Gems to be staked đŸĻŠ
Stake Gems đŸĻŠ
Get staked tokens for a given address 🌎
Claim and stake rewards đŸĻŠ
Batch claim and stake rewards
Get the staked amount for a given token ID
Withdraw đŸĻŠ
Selling ERC-1155 Collectibles
sellErc1155(options) đŸĻŠđŸ•
purchaseErc1155(resaleItemId) đŸĻŠ