Minting

Minting an item means placing creating an NFT on the blockchain. Users can then use NFTs in multiple games and trade them on the open market. To mint an item, you need to:

1. Call the Mint Contract.
2. Pass the user through the Checkout.
3. Implement the Callbacks API for your application and handle transaction events.

Learn more about the minting process here.

• Mint Contract
  • Auth
  • Gasless Transaction
  • Example
• Checkout
• Callbacks API
  • Authorization
  • Get Item Callback
  • Notify Callback
  • Examples
• Airdrop

Mint Contract

When your user initiates the minting of an item in your system, your backend needs to call the Faraway Platform Mint Contract API. Mint Contract API returns a URL that is used to open Faraway Checkout. Checkout then walks the user through posting a transaction on the blockchain. You can find the Mint Contract API documentation here. Below are important concepts related to the request parameters:

• requestId - This ID allows you to identify your request when receiving callbacks and to track its progress in your system, note that if you call the contract with previously used requestId you get an "already exists" error.
• transactionFee - If you set this parameter, the user who initiated the transaction will pay an additional fee, which will be distributed among the specified accounts (see accounts guide) according to the shares provided.
• royaltyShares - When an item is minted, the NFT can be sold by the owner on the secondary market, and a portion of the profit will be transferred to the royalty accounts. Typically royalty accounts are setup on the collection level, for more details see collection guide. Leave this field empty or null if you want to use royalties configured on the collection level. If you want to Mint an item with royalty accounts or shares different from collection royalties you will need to fill this field. A share is defined as a percentage, so the sum of all shares must be less or equal to 100% where 100% means all the profit goes to the royalty accounts.
• maxSupply - Defines how many NFTs can be minted for the same item. The higher this parameter, the less unique your item becomes. The most common use case is to pass 1. Passing 1 makes your item unique with respect to a given item ID (only one NFT can be minted per item ID).
• preconditions - Use options in this field to implement features like whitelist restrictions or requiring certain items to be minted before the current one. A common use case is restricting minting some items to holders of specific NFTs.
• gasTankId - See Gasless Transactions.

Auth

Most Faraway Platform contracts use Basic Auth to authorize your project. You can retrieve your credentials at https://dev.faraway.com -> Your Project -> Manage -> API Keys. To authenticate, include the Authorization header with a value constructed as follows:

“Basic ” + base64(client_id + “:” + client_secret)

To authorize a user, you also need to include the X-Platform-User-Token header with the OAuth JWT token of your user. For more details, refer to the OAuth2 guide.

Gasless Transaction

Every blockchain transaction requires a cryptocurrency fee (gas) to process the transaction. Minting an item is a blockchain transaction, and by default, the user initiating the mint will pay the gas fees. However, if you want to offer gasless minting to your users, you can sponsor the gas fees yourself.

To do this, you need to set up a gas tank at https://dev.faraway.com. Follow these steps:

1. Select your project.
2. Navigate to Finance.
3. Click on the Create Gas Tank button.
4. Complete the form, ensuring that the selected blockchain matches the blockchain used for minting your items.

After creating the gas tank, deposit cryptocurrency into its address. For detailed instructions, refer to our Gas Tanks guide.

Once your gas tank has a positive balance, you can use its ID as the value for the gasTankId parameter in the Mint Contract. By doing so, the transaction becomes gasless for your users, and you will cover the gas fees on their behalf.

Example

You can generate a Faraway Platform API client using our OpenAPI specification. Follow these steps:

1. Navigate to https://editor-next.swagger.io/.
2. Go to File -> Import URL and input: https://api.faraway.com/docs/api.swagger.json.
3. Review the UI rendered for the API specification.
4. Select Generate Client and choose the programming language that matches your backend.

For additional context, please refer to the cURL example below.

Request:

curl --location 'https://api.faraway.com/v1/contracts/mint' \
--header 'Authorization: Basic ###' \
--header 'X-Platform-User-Token: ###' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "test request id",
    "itemId": "test item id",
    "collectionId": "test collection id",
    "maxSupply": 1 
}'

Response:

200 OK
{"url":"https://checkout.faraway.com/confirm?blockchain=###&id=###"}

Checkout

To pass your user through the checkout process, use the URL returned by the Mint Contract and send it to the Faraway Checkout component on the frontend of your application.

To simply open the URL, you can use the following approach:

window.open(url, '_blank')

Or, if you need to subscribe to events provided by the checkout, you first need to connect the checkout-lib to your project via CDN:

<script src="https://checkout.faraway.com/faraway-wallets-provider-latest.js"></script>
<script src="https://checkout.faraway.com/faraway-checkout-latest.js"></script>

And then use method “open”:

const checkout = new FarawayCheckout();  
checkout.open(url);

After that you can subscribe to Checkout methods using “on” and unsubscribe with “off”:

checkout.on('FARAWAY_CHECKOUT_CLOSE', disposer);

// List of methods:

export interface MessagingMap {
  /**
   * Send after initialization
   */
  FARAWAY_CHECKOUT_INIT: MessageData;

  /**
   * Send sizes of window
   */
  FARAWAY_CHECKOUT_INITIAL_SIZE: MessageData<{ width: number; height: number }>;

  /**
   * Send after wallets detect
   */
  FARAWAY_CHECKOUT_DETECT_EXTENSIONS: MessageData<{ extensions: string[] }>;

  /**
   * Send after change the wallet in extension
   * @deprecated
   */
  FARAWAY_CHECKOUT_CHANGE_WALLET: MessageData<{ wallet: string; address: string; blockchain: string }>;

  /**
   * Send balance of current wallet
   */
  FARAWAY_CHECKOUT_BALANCE: MessageData<{ balance: number }>;

  /**
   * Send after successfully transaction
   */
  FARAWAY_CHECKOUT_COMPLETE: MessageData<{ txHash?: string; blockchain: string; wallet: string; address: string }>;

  /**
   * Send on processing transaction
   */
  FARAWAY_CHECKOUT_PROCESSING: MessageData<{ txHash?: string; blockchain: string; wallet: string; address: string }>;

  /**
   * Send after click on close button
   */
  FARAWAY_CHECKOUT_CLOSE: MessageData<{ type: 'lib' | 'page' | 'button' | 'dApp'; from?: 'cancel' | 'ok' | 'cross' }>;

  /**
   * Send after any error
   */
  FARAWAY_CHECKOUT_ERROR: MessageData<{ message: string }>;
}

Once the user has completed the checkout, your app will receive a callback delivering the result of this user interaction. See Callbacks API for more information on handling the callback and processing the result.

Callbacks API

In order to receive Faraway Platform callbacks, you need to configure your application’s callback URL at https://dev.faraway.com.

Follow these steps:

1. Select your project.
2. Navigate to Manage -> Callback & OAuth.
3. Set the base URL of your application’s API in the “Callback URL” field.

For detailed instructions, refer to our guide.

For minting, you need to implement the following callbacks:

GET <Callback URL>/v1/get-item
POST <Callback URL>/v1/notify

You can find the documentation for the callbacks here:
https://docs.faraway.com/reference/callback_getitem
https://docs.faraway.com/reference/callback_receivenotification

Authorization

To confirm that the callback is sent by Faraway Platform you need to verify the request using JSON Web Key Set at https://api.faraway.com/v1/auth/keys. The signing and verification processes are based on https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures.

Get Item Callback

When calling the Mint Contract, Faraway Platform sends a request back to your application in order to receive the item's metadata. Your API needs to reply with all the data related to your item according to the response schema. The data will be linked to the NFT and used by other projects and marketplaces. Metadata fields expected by Faraway Platform:

• name, imageUrl, description - the data of the item that will be used by all the marketplaces and wallets (name and imageUrl are required);
• externalUrl - the URL to view the item on your project’s site;
• animationUrl - the URL to a multi-media attachment for the item. The file extensions as GLTF, GLB, WEBM, MP4, M4V, OGV, and OGG are supported, along with the audio-only extensions like MP3, WAV, and OGA. Animation_url also supports HTML pages, allowing you to build rich experiences and interactive NFTs using JavaScript canvas, WebGL, and more. Scripts and relative paths within the HTML page are now supported. However, access to browser extensions is not supported;
• attributes - various optional attributes of the item that will be shown on all NFT-marketplaces. You can use it to add value and rarity to your item based on the specifics of your project. You can define an attribute using parameters:
  • name - attribute name;
  • displayType - a field indicating how you would like it to be displayed. For string attributes, you don't have to worry about it;
  • stringValue, intValue, doubleValue - typed variations for the attribute value, you need to choose one.
• properties - properties that can be used by other projects that want to adopt your tokens, like: links to 3D models, textures, sounds, and other assets that can be shared between different games. These properties are not visible to users via wallets or on marketplaces. You can define a property using parameters:
  • name - property name;
  • stringValue, intValue, doubleValue, jsonValue - typed variations for the property value, you need to choose one;
  • fileValue - file variation for the property value that is defined by uri, mimeType, and CDN.

Notify Callback

When Faraway Platform finishes the minting process, it sends a notification back to your application about the successful or unsuccessful result. Only after receiving a successful result should you count the item as minted in your system. You can get minted items the user owns calling Inventory API.

You should use requestId from the callback to match the notification to the checkout request made to Mint Checkout API. This way you can get all the initial information (itemId, userId, etc.) that you have saved previously. Blockchain item with the item in your system, you can use the mint field of the request (or silentMint). There you can find the itemId field with the ID of your item.

Examples

You can generate your server using our OpenAPI specification. Follow these steps:

1. Navigate to https://editor-next.swagger.io/.
2. Go to File -> Import URL and input: https://api.faraway.com/docs/callbacks.swagger.json.
3. Review the UI rendered.
4. Select Generate Server and choose the programming language that matches your backend.

For additional context, please refer to the cURL example below.

Get Item request from Faraway Platform:

curl --location '<Callback URL>/v1/get-item?itemId=test%20item%20id'  
--header 'Signature: keyId="callbacks-prod",algorithm="ecdsa-sha256",
     created=1402170695,expires=1402170699,
     headers="(request-target) (created) (expires) date digest",
     signature="SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+lavg7T8hc0GppauB6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM="'
--header 'Date: Sun, 05 Jan 2014 21:31:40 GMT'
--header 'Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE='

Get Item response example:

200 OK  
{  
    "item": {  
        "name": "item name",  
        "imageUrl": "item image url",  
        "attributes": [  
            {  
                "name": "string attribute",  
                "stringValue": "value"  
            },  
            {  
                "name": "int attribute",  
                "intValue": 123  
            }  
        ],  
        "properties": [  
            {  
                "name": "string property",  
                "stringValue": "value"  
            },  
            {  
                "name": "float property",  
                "doubleValue": 1.23  
            }  
        ]  
    }  
}

Notify request from Faraway Platform:

curl --location '<Callback URL>/v1/notify'
--header 'Signature: keyId="callbacks-prod",algorithm="ecdsa-sha256",
     created=1402170695,expires=1402170699,
     headers="(request-target) (created) (expires) date digest",
     signature="SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+lavg7T8hc0GppauB6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM="'
--header 'Date: Sun, 05 Jan 2014 21:31:40 GMT'
--header 'Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE='  
--header 'Content-Type: application/json'  
--data '{  
    "requestId": "test request id",  
    "status": "SUCCESS",  
    "userId": "test user id",  
    "blockchainTime": "2006-01-02T15:04:05Z",  
    "transactionHash": "###",  
    "at": "2006-01-02T15:04:05Z",  
    "mint": {  
        "requestId": "test request id",  
        "itemId": "test item id",  
        "collectionId": "test collection id",  
        "maxSupply": 1  
    }  
}'

Notify response example:

200 OK

Airdrop

To be able to send minted items to users in the background without the Checkout, you need to use the Silent Mint contract. The contract requires a gas tank (see Gasless Transaction).

Note: Silent Mint requires a user to have a Faraway Wallet linked to their Faraway Connect account.

What if the user does not have a Faraway Wallet?

• The contract returns a 400 ERR_EMBEDDED_WALLET_REQUIRED error, in which case you can notify the user about the requirement;
• You can preemptively check if the user has the wallet by calling Get User and checking the hasEmbeddedWallet field.