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.
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.
🌎 - 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.
You can use this method to get a paginated list of NFTs for a given project, or smart contract on Cargo. You can get the project ID for your project from the URL bar when viewing the project on the Cargo website.
cargo.api.getTokensByProject(options).then(response => {// Do something with response});
Argument | Description |
| An object containing the following properties:
|
type SuccessResponse = {err: false,status: 200,data: {// Contract namename: string;// Contract symbolsymbol: string;// Array of tokensresults: {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 pagepage: string;// Limitlimit: string;// Total number of pagestotalPages: string;}}
You can use this method the get details for a given collectible.
cargo.api.getTokenDetails(projectId, collectibleId).then(response => {// Do something with response});
Argument | Description |
| The ID of the project on Cargo. This can be found in the URL bar when viewing the project on Cargo. |
| The ID of the collectible within the collection. |
type Response = {err: boolean,status: number,data: {// Username of ownerowner?: string,// Address of ownerownerAddress: string,// If this item is for sale, details about saleresaleItem?: {seller: string,contract: string,tokenId: string,price: string,signatureGenerator?: boolean,groupId: stringcrate: string,createdAt: string,},// Collectible IDtokenId: string,// Name of collection token belongs tocontractName: string,// Symbol of collection token belongs tocontractSymbol: string,}}
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});
Argument | Description |
| An object that contains the following properties:
|
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 collectioncontract: string;// Id of the collectibletokenId: string;// Price in Wei that the collectible is selling forprice: 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 tocrate?: string;createdAt: string;}[]}}
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});
Argument | Description |
| An object containing the following properties:
|
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 === truetotalOwned?: number,// Available only when useAuthToken === trueowned?: boolean,}[],limit: string,totalPages: string,total: string,page: string,}}
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});
Argument | Description |
| Required. String. The ID of the showcase |
| 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. |
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;}}
You can use this method to get a showcase by its slug and slug ID.
cargo.api.getShowcaseBySlug(slug, slugId).then(res => {// do something});
Argument | Description |
| Required. String. The slug of the showcase |
| Required. String. Slug ID of the showcase. |
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;}}
You can use this method to get information about a project on Cargo. If an auth token is present then an additional isOwned value will be returned in the response.
cargo.api.getProjectMetadata(id, useAuth).then(response => {// Use response});
Argument | Description |
| Required. The ID of the project. This can be found in the URL bar when viewing the project on Cargo. |
| Optional. If |
type SuccessResponse = {err: false;status: 200;data: {totalSupply: number;address: string;name: string;cargoContract: boolean;symbol: string;supportsMetadata: boolean;createdAt: string;}}
You can retrieve orders for collectible sales which relate to you.
cargo.api.orders(options).then(res => {// do something with response});
Argument | Description |
| An object that contains the following:
|
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 metadata1: {name: 'Crypto hero',description: 'Something about this collectible',},2: {name: 'Crypto Goblin',description: 'Something about this collectible',},}cargo.api.bulkMetadataUpdate(collectionAddress, updates, chain).then(response => {if(response.status === 200) {// success}});
Argument | Description |
| The collection in which to update collectible metadata |
| An object where keys represent the collectible ID and the value is a JSON serializable object containing the new metadata |
| Optional. Leave blank for Ethereum, valid options are |
type SuccessResponse = {status: 200,err: false,data: {code: 'success',}}
You can use this method to add individual NFTs to a showcase.
cargo.api.addCollectiblesToShowcase(items, showcaseId).then(response => {if(response.status === 200) {// Success}});
Argument | Description |
| An object where the keys are collection addresses and the values are arrays of token IDs. Ex: |
showcaseId | The ID of the showcase to add the collectibles to. |
type SuccessResponse = {err: false,status: 200,data: {success: true,}}
You can use this method to remove NFTs from a showcase.
cargo.api.removeCollectiblesFromShowcase(items, showcaseId).then(res => {if(res.err === false) {// done}});
Argument | Description |
| An object where the keys are collection addresses and the values are arrays of token IDs. Ex: |
showcaseId | The ID of the showcase to remove collectibles from. |
type SuccessResponse = {err: false,status: 200,data: {success: true,}}
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});
Argument | Description |
| An object that has the following properties:
|
type SuccessResponse = {err: false,status: 200,data: {results: {tokenId: string,metadata: {},tokenURI: string,}[],limit: string,totalPages: string,page: string,total: string}}
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}});
Argument | Description |
| An Object containing the following properties
|
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;};
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});
Argument | Description |
| An optional object with the following properties:
|
type Response = {err: boolean,status: number,data: {results: {name: string,id: string,}[],// Total number of showcases createdtotal: string,// Current pagepage: string,// Limitlimit: string,// Total number of pagestotalPages: string,}}
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);}});
Argument | Description |
| Required. String. The ID of the showcase to retrieve items for |
| Optional. String. The page specified for pagination |
| Optional. String. The max number of items to return in the 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;}}
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}});
Argument | Description |
| Required. An Object containing the following keys and values
|
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});
Argument | Description |
| ID of showcase to return vendors for. |
| Page of results to start returning results at. |
| Limit of results per page |
type Response = {err: boolean,status: number,data: {results: {// Address of vendoraddress: string// Cargo id of vendor_id: string,// Username of vendordisplayUsername: string,}[],// Total number of showcases createdtotal: string,// Current pagepage: string,// Limitlimit: string,// Total number of pagestotalPages: string,}}
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});
Argument | Description |
| The address of the vendor |
| The showcase the vendor belongs to for which you'd like to retrieve beneficiaries for. |
type Response = {err: boolean,status: number,data: {results: {// The address of the beneficiaryaddress: string,// The commission of the beneficiarycommission: string,// The address of the vendor for whom this// beneficiary belongs tovendorAddress: string,// The showcase IDcrateId: string,// Timestamp for when the vendor was createdcreatedAt: string,}[],// Total number of showcases createdtotal: string,// Current pagepage: string,// Limitlimit: string,// Total number of pagestotalPages: string,}}
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. Email and username are optional. The email will be used to send notifications when the users collectibles have sold. The username will be displayed on Cargo and returned in various responses. The only requirement is that the user has a Web3 enabled wallet.
When creating accounts on Cargo your users must agree to the Cargo Terms of Service
cargo.api.register(email, username).then(response => {if(response.status === 200) {// User has been created and is authenticated// for future requests}});
Argument | Description |
| Optional. Valid email address that will be tied to the account |
| Optional. Username to be used for new account |
type Response = {err: boolean,status: number,data: {// JSON web tokentoken: string,}}
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}});
This method does not take any arguments.
type SuccessResponse = {err: false,status: 200,data: {// JSON web tokentoken: string}}// If an account is required you will get this responsetype AccountRequiredResponse = {err: true,status: 401,data: {code: 'account-required'}}
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(saleId, chain).then(txHash => {// Transaction submitted});
Argument | Description |
| Required. The ID of the sale |
| Required. Valid options are |
The response will contain a transaction hash.
You can use this method to transfer a collectible you own to another address.
cargo.api.transferCollectible(contractAddress, tokenId, toAddress).then(txHash => {// Transaction submitted});
Argument | Description |
| The collection address for which the collectible belongs to. |
| The ID of the collectible to transfer. |
| The Ethereum address to transfer the collectible to. |
The response will contain a transaction hash.
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});
Argument | Description |
| Address of collection |
| The ID of the collectible to burn. |
The response will contain a transaction hash.
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
/**Price should be converted to Wei if selling in Ether.If selling in another currency the price should be converted based on thedecimal place set.For example:GEM uses 18 decimal places.If selling an item for 5 GEM the price should be converted as such:price = new cargo.BigNumber(5).times(10 ** 18).toFixed();TST uses 4 decimal places.If selling an item for 5 TST the price should be converted as such:price = new cargo.BigNumber(5).times(10 ** 4).toFixed();*/cargo.api.sell(options, unapprovedFn).then(response => {if(!response.err) {// Item has been marked for sale}});
Argument | Description |
| An object with the following properties:
|
| 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. |
type Response = {err: boolean,status: number,data: {// ID of newly created resale itemresaleItemId: string,}}
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.});
Argument | Description |
| The ID of the resale item. |
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',}}
You can use this method to create a new showcase.
cargo.api.createShowcase(showcaseName, description, bannerFile).then(response => {if(response.status === 200) {// Showcase created}});
Argument | |
| Required. String. The name of your new showcase |
| Optional. String. Description of your showcase. Max length 120 characters. |
| Optional. File. Banner file. Max size 2mb |
type Response = {err: false,status: 200,data: {showcaseId: string}}
You can use this method to modify an existing showcase.
cargo.api.modifyShowcase(showcaseName, update).then(response => {if(response.status === 200) {// Showcase created}});
Argument | |
| Required. String. The name of your new showcase |
| Required. Object. An object containing the following properties:
|
You can use the following methods to create new collections and NFTs within those collections. Collections are also known as projects.
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, network, symbol, web3TxParams).then(txHash => {// Transaction has been submitted});
Argument | Description |
| Name of your collection |
| Required. |
| Ticker symbol of your collection |
| Optional. Showcase ID in which the collection will be added to after creation. |
The response will contain a transaction hash.
Use this method to initialize a new minting session.
cargo.api.createMintingSession(projectId).then(sessionId => {// Do something});
Argument | Description |
| Required. The ID of the project you will be creating NFTs in. |
This function returns a Promise which resolves with a sessionId which is a string.
This method can be used to get an existing session to continue modifying, or finalize.
cargo.api.getMintingSession(sessionId).then(data => {// Do something});
This function accepts one argument sessionId which is a string.
type Content = {originalFileName: string;fileName: string;mimeType: string;hash: string;public: boolean;url: string;owner: string;// size in bytessize: Number;}type SuccessResponse = {// Array of pending NFT data associated with sessionnfts: {uuid: string;session: string;createdAt: string;name: string;description: string;amount: number;metadata: string;displayContentType: string;fileMap: {locked: Content[];previewImage: Content[];displayContent: Content[];};// size in bytes of files associated with this NFTsize: number}[]}
This method can be used to save pending NFT data to an existing session.
cargo.api.saveNft(sessionId, nfts, onSaved, onError).then(() => {// done});
Argument | Description |
| Required. Session ID |
| Required. An array of NFT objects. Each object should have the following properties:
|
| Optional. A function which is called after the NFT content is saved. The first argument will contain the NFT content ID. |
| Optional. A function which is called after the NFT content is saved. The first argument will contain the NFT content ID. The second argument will contain the failure reason. |
Use this method to create new collectibles using the wallet associated with your Cargo account. Prior to calling this method you must first create a new session.
cargo.api.wizardMint(sessionId, toAddress, web3TxParams).then(txHash => {// Transaction submitted});
Argument | Description |
| Required. The ID of the session you will be minting. |
| Required. The wallet address which these NFTs will be transferred to after creation. |
| An optional object which can be passed to the web3 function used to execute the transaction. |
The response will contain a transaction hash.
You can use this method to add royalties to a given NFT. Royalties are fees that you will collect whenever the given NFT is sold through Cargo. You can only add royalties to NFTs created within collections that were made on Cargo. You add up to 15 different wallet addresses and royalties cannot equal more than 15%.
cargo.api.addRoyalty(params).then(res => {})
Argument | Description |
| An object containing the following properties:
|
type SuccessRes = {data: { success: true };err: false;status: 200;}
You can use this method to get royalty information about a given NFT.
cargo.api.getRoyalty(params).then(res => {})
Argument | Description |
| An object containing the following properties:
|
type SuccessRes = {success: false;status: 200;data: {royalty: {contractAddress: string;tokenId: string;payees: string[];commissions: number[];} | void}}
You can use this method to allow a user to approve a given address to transfer a specified ERC-20 token on their behalf.
cargo.api.approveErc20(amount, address, operator, web3Params).then(txHash => {});
Argument | Description |
| The amount to be approved |
| The ERC-20 contract address |
| The address which will be approved to transfer |
| Additional parameters sent in the web3 |
You can use this endpoint to get a list of currencies supported by Cargo.
cargo.api.getCurrencies().then(res => {if(res.err === false){// do something}});
This method does not take any arguments.
type SuccessResponse = {err: false,status: 200,data: {_id: string;address: string;name: string;image: string;}[]}
You can use this method to get a currency ID by the currency's address. Currency IDs are used when setting items for sale.
cargo.api.getCurrencyIdByAddress(address).then(res => {});
Argument | Description |
| The address of the currency |
type SuccessResponse = {err: false;status: 200;data: {id: string;}}
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 => {});
Argument | Description |
| A string. The amount the caller wants to approve. |
This method returns a promise which resolves a Web3 transaction receipt. You can use the PollTx class to listen for when this transaction completes.
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 => {});
Argument | Description |
| String. The address of the collection that contains the NFT to stake. |
| String. The ID of the NFT to stake. |
| String. The amount of Gems the caller wishes to stake. Must account for the 18 decimal points of the Gems contract. |
This method returns a promise which resolves a Web3 transaction receipt. You can use the PollTx class to listen for when this transaction completes.
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}});
Argument | Description |
| String. The wallet address to retrieve a list of staked tokens for. |
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 tokenstokens: {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 };};};}[]}}
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 => {});
Argument | Description |
| String. The contract address in which the staked NFT was created in. |
| String. The ID of the staked NFT. |
This method returns a promise which resolves a Web3 transaction receipt. You can use the PollTx class to listen for when this transaction completes.
Use this method to trigger multiple transactions. This uses the web3.BatchRequest method under the hood.
cargo.api.batchClaimAndStakeRewards(data).then(() => {});
Argument | Description |
| An Array of Objects containing the following properties:
|
You can use this method to get the total Gems staked in a given NFT.
cargo.api.getTokenStake(address, tokenId).then(balance => {})
Argument | Description |
| Required. String. The ERC-721 collection address. |
| Required. String. The token ID |
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 => {})
Argument | Description |
| String. The contract address in which the staked NFT was created in. |
| String. The ID of the staked NFT. |
| String. The amount of Gems to withdraw from specified NFT. |
This method returns a promise which resolves a Web3 transaction receipt. You can use the PollTx class to listen for when this transaction completes.
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.
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 give