Card Minting

This tutorial is a guide to help Klip Partners mint and manage Cards conveniently using APIs.

1. Klip Partners

1-1. Request Membership and Approval

In order to start minting Cards, you first have to join Klip Partners. Upon requesting membership, you will receive an approval after an individual consultation with the Klip staff. When you receive the approval, you will get a confirmation email and will be eligible to log in to Klip Partners. For more details on membership, please visit Klip Partners. If you need help with this document or with Klip in general, please visit our Developer Forum.

1-2. Sign In

Pass your ID(email) and password to Klip Partners via Sign In.

  • password is a 64-digit string and a hash(SHA256) of the password.

    • Password is a string consisting of 8-16 alphabet characters, numbers, and special characters.

//Klip Partners Sign In
curl -X POST "https://api.klipwallet.com/v2/partner/auth" \
-d '{"email":"ray.kim@groundx.xyz", "password":"C01069C9ABB6EA7DA49AE418A24BBEF3AD67170DDCD20AC7C76084A5A85E4057"}' \
-H "Content-Type: application/json"

If the request is successful, it returns the following:

{
  "email": "terri.kwak@groundx.xyz",
  "klaytn_address":0xdc6AE5861a73d852bd3cdD84a4BA7f598A5160F3,
  "contract_address": "0xc94770007dda54cF92009BFF0dE90c06F603a09f",
  "name": "Terri Kwak",
  "phone": "01012345678",
  "service_name": "Puppy World Revolution"
  "access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJI...",
  "status" : 10,
  "mint_limit": 1000,
  "mint_count": 1,
}

When you sign up for Klip Partners, an EOA address and a smart contract is created on the Klaytn blockchain from which you can mint Cards. klaytn_address is your EOA address created in the Klaytn blockchain, and contract_address is the (SCA) from which you can mint Cards.

You will receive a JWT authentication token(access_token) which is valid for 24 hours. This token will expire after 24 hours, in which case you have to obtain a new token.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

2. Mint Cards

2-1. Upload Card Image

Card image is what will be visible to Klip users. In order to start minting Cards, you have to upload Card image. Pass the Card image file and the access_token you received when signing in to Klip Partners via Upload Image and request image upload.

To mint Cards using Mint Card To user, you first have to upload Card images using Upload Image API

//Upload image to Klip Partners
curl -X POST "https://api.klipwallet.com/v2/wallet/image" \
-F upload=@./imagefile.png \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: multipart/form-data"

If the request is successful, it returns the following:

{"image": "https://path_to_image/image.png"}

If the image file is successfully uploaded, it returns the URL address of the uploaded image file.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

2-2. Mint Card to EOA

Pass the mint_info.json file, and the access_token you received when signing in to Klip Partners via Mint Card To user. It uses the uploaded Card image. Any user with an EOA can receive the Cards.

//Mint Card
curl -X POST "https://api.klipwallet.com/v2/wallet/mint" \
-d @./mint_info.json \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

An example of a mint_info.json file is shown below. This file contains the URL of the Card image and the information necessary to mint Cards.

//An example of a mint_info.json file
{
  "pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
  "to_address": ["0x01ea07D1258c106FFD3197721a838F02408ea809",
    "0xE2d12bE9E570AE58277d6872B001fE9dF94D1531",
    "0xb1764B96da889Cc2F043025aa368517C80e86795"],
  "contract_address": "0xbad6444e1f84af055c22281d4ac7d75bde2ddec8",
  "name": "Magic Sword",
  "description" : "Summon your Magic Sword within the game.",
  "image": "https://path_to_image/image.png",
  "animation_url": "https://path_to_video/video.mp4",
  "background_color" : "#ae312e",
  "sendable": true,
  "send_friend_only": true,
  "group_name": "Ground X Magic Game",
  "group_icon": "https://path_to_image/image.png",
  "hashtags": ["Game","groundX","Magic"],
  "layout": "vertical",
  "external_link": "https://path_to_ext_link",
  "qr_code": "https://path_to_image/qr_image.png",
  "bar_code": "https://path_to_image/bar_image.png",
  "attributes" : [
    {
      "trait_type": "Sword", 
      "value": "Iron Short Sword"
    }, 
    {
      "trait_type": "Magic Type", 
      "value": "Fire"
    }, 
    {
      "trait_type": "Sword Level", 
      "value": "5"
    }, 
    {
      "trait_type": "Magic Level", 
      "value": "2"
    }
  ],
  "secure" : {
    "bar_code" : "1234 ABCD 5678 EFGH 90IJ",
    "qr_code" : "https://your-domain.com?key=1234",
    "attributes" : [
      {
        "trait_type": "Sword",
        "value": "Iron Short Sword"
      },
      {
        "trait_type": "Magic Type",
        "value": "Fire"
      },
      {
        "trait_type": "Sword Level",
        "value": "5"
      },
      {
        "trait_type": "Magic Level",
        "value": "2"
      }
    ]
  },
  "status_url" : "https://your-domain.com?key=1234"
}

  • pin is a 64-digit string and hash(SHA256) of the PIN Code(The 6-digit string that you entered when signing up for Klip Partners).

    • pin is used in place of the private key to sign transactions.

    • PIN Code is a 6-digit string.

  • to_address is an array of user EOAs that will receive the Cards.

    • If you pass an array with just one element to_address, it is only sent to one user.

    • The maximum number of EOA addresses to be included in to_address is 200 per API request.

  • If sendable TRUE, the recipient of the Card can send that Card to another user on Klip.

  • If send_friend_only is TRUE, the recipient of the Card can send that Card to only his or her KakaoTalk friends on Klip.

  • The maximum number of elements in the array hashtags is 10. The maximum number of characters for each element is 100.

  • If you set external_link, you can include a URL address that redirects to an external browser outside of Klip. The maximum number of characters is 255.

  • We recommend the qr_code image to be at least 400px in width and without margins in any direction.

  • We recommend the bar_code image to be at least 400px in width and without margins in any direction.

  • attributes is an array of objects containing the properties of the Cards in the form trait_type/value.

If the request is successful, it returns the following:

{
  "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97"
}

If the Card is minted successfully, it returns the the transaction hash of the smart contract. You can track the transaction by entering the hash in Klaytnscope to confirm that the transaction has been executed successfully.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

2-3. Mint Card to Klip Member

Pass the mint_info.json file, and the access_token that you received when signing in to Klip Partners via Mint Card To Klip Member and send a request to mint Card. Sends Cards only to a Klip Member identified by name and phone number.

//Mint Card
curl -X POST "https://api.klipwallet.com/v2/wallet/mint/person" \
-d @./mint_info.json \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

An example of the mint_info.json file is shown below. This file contains the URL of the Card image and the information necessary to mint Cards.

//An example of a mint_info.json file
{
  "pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
  "to_person": [["Alice", "010-1111-2222"], ["Brian", "010-3333-4444"]]
  "contract_address": "0xbad6444e1f84af055c22281d4ac7d75bde2ddec8",
  "name": "Magic Sword",
  "description" : "Summons a magic sword that has magical properties and effects in the game.",
  "image": "https://path_to_image/image.png",
  "animation_url": "https://path_to_video/video.mp4",
  "background_color" : "#ae312e",
  "sendable": true,
  "send_friend_only": true,
  "group_name": "Ground X Magic Game",
  "group_icon": "https://path_to_image/image.png",
  "hashtags": ["Game","groundX","Magic"],
  "layout": "vertical",
  "external_link": "https://path_to_ext_link",
  "qr_code": "https://path_to_image/image.png",
  "bar_code": "https://path_to_image/bar_image.png",
  "attributes" : [
    {
      "trait_type": "Sword", 
      "value": "Iron Short Sword"
    }, 
    {
      "trait_type": "Magic Type", 
      "value": "Fire"
    }, 
    {
      "trait_type": "Sword Level", 
      "value": "5"
    }, 
    {
      "trait_type": "Magic Level", 
      "value": "2"
    }
  ],
  "secure" : {
    "bar_code" : "1234 ABCD 5678 EFGH 90IJ",
    "qr_code" : "https://your-domain.com?key=1234",
    "attributes" : [
      {
        "trait_type": "Sword",
        "value": "Iron Short Sword"
      },
      {
        "trait_type": "Magic Type",
        "value": "Fire"
      },
      {
        "trait_type": "Sword Level",
        "value": "5"
      },
      {
        "trait_type": "Magic Level",
        "value": "2"
      }
    ]
  },
  "status_url" : "https://your-domain.com?key=1234"
}

  • pin is a 64-digit string and hash(SHA256) of the PIN Code(The 6-digit string that you entered when signing up for Klip Partners).

    • pin is used in place of the private key to sign transactions.

    • PIN Code is a 6-digit string.

  • to_person is a 2-dimensional array containing the users[Real Name, Phone Number] that will receive the Cards.

    • If you pass an array with just one element to to_person, it is be sent to just one user.

    • The maximum number of the element [Real Name, Phone Number] that can be included in to_person is 200 per API request.

    • If there is not a Klip user with the corresponding Real Name and Phone Number passed to the to_person parameter, minting will fail.

  • If sendable TRUE, the recipient of the Card can send that Card to another user on Klip.

  • If send_friend_only is TRUE, the recipient of the Card can send that Card to only his or her KakaoTalk friends on Klip.

  • The maximum number of elements in the array hashtags is 10. The maximum number of characters for each element is 100.

  • If you set external_link, you can include a URL address that redirects to an external browser outside of Klip. The maximum number of characters is 255.

  • We recommend the qr_code image to be at least 400px in width and without margins in any direction.

  • We recommend the bar_code image to be at least 400px in width and without margins in any direction.

  • attributes is an array of objects containing the properties of the Cards in the form trait_type/value.

If the request is successful, it returns the following:

{
  "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97",
  "result": [["Alice", "010-1111-2222", "success", ""], ["Brian", "010-3333-4444", "fail", "phone number does not exist"], ...]
}

If the Card is minted successfully, it returns the the transaction hash of the smart contract and the result. If at least one user from the array in to_person received the Card, the request is regarded as successful.

From the result above, the user "Alice" has a Membership record with the corresponding Real Name and Phone Number, so she receives the Card. From the result above, the user "Brian" does not have a Membership record with the corresponding Real Name and Phone Number, so he doesn't receive the Card.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

2-4. Upload Card Video Clip

If you want to use the animation_url field when minting Cards, you first have to upload the file of the Card video clip. Pass the file of the clip and the access_token that you received when signing in Klip Partners via Upload NFT Resource and request Card Video Clip Upload.

//Upload Card Video Clip to Klip Partners
curl -X POST "https://api.klipwallet.com/v2/wallet/nftResource" \
-F upload=@./video.mp4 \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: multipart/form-data"

If the request is successful, it returns the following:

{"url": "https://path_to_video/video.mp4"}

If the file is uploaded, it returns the URL of the uploaded file.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

3. Get Card Information

3-1. Get Card Information by BApp

After you minted a Card, you can retrieve the Card's information along with the BApp information. Pass the access_token that you received when siging in to Get Card Information by BApp and make the request.

//Get Card Information By BApp
curl "https://api.klipwallet.com/v2/wallet/bapp" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

//An example of a BApp list and Cards by BApp
{
    "bapps": [
        {
            "id": 2,
            "name": "bapp2",
            "bapp_img": "/img/bapp-icon2.svg",
            "category_id": 2,
            "nft_order_no": 1,
            "summary": "summary",
            "card_count": 10,
            "nft_id": 52,
            "cards": [
                    {
                        "created_at": 1580300503,
                        "updated_at": 1580300503,
                        "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                        "sender": "0x0000000000000000000000000000000000000000",
                        "card_id": 18,
                        "card_uri": "https://...",
                        "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
                    },
                    {
                        "created_at": 1580300504,
                        "updated_at": 1580300504,
                        "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                        "sender": "0x0000000000000000000000000000000000000000",
                        "card_id": 19,
                        "card_uri": "https://...",
                        "transaction_hash": "0x8814f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
                    },
                    {
                        "created_at": 1580300505,
                        "updated_at": 1580300505,
                        "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                        "sender": "0x0000000000000000000000000000000000000000",
                        "card_id": 20,
                        "card_uri": "https://...",
                        "transaction_hash": "0x9254f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
                    },
                ],
            "cards_next_cursor": ""
        },
        {
            "id": 3,
            "name": "bapp3",
            "bapp_img": "/img/bapp-icon3.svg",
            "category_id": 2,
            "nft_order_no": 2,
            "summary": "summary",
            "card_count": 10,
            "nft_id": 55,
            "cards": [
                    {
                        "created_at": 1580300511,
                        "updated_at": 1580300511,
                        "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                        "sender": "0x0000000000000000000000000000000000000000",
                        "card_id": 5,
                        "card_uri": "https://...",
                        "transaction_hash": "0x1a54f10f73468ea85c84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
                    },

                ],
            "cards_next_cursor": ""
        },
    ],
    "next_cursor": ""
}

If the request is successful, it returns a list of all the BApps and the Cards by BApp.

  • bapp from bapps refers to a BApp provided by a Klip Partner.

  • card from cardsrefers to Klip Card used in this BApp. BApp contains one type of Card.

  • nft_id refers to the ID of the smart contract from which this card.

  • nft and bapp always corresponds 1:1.

  • card_uri is the URL containing the JSON file of the Card's metadata.

    • Card metadata contains the basic information of the Card such as name, description, image, background_color, attributes defined when minting the Card.

You can get a maximum of 100 elements of BApp information from a single request. If there are over 100 BApps to query, the result will return bapps.next_cursor, with which you can retrieve the rest of the BApps. To retrieve the rest of the BApps, set the cursor parameter with bapps.next_cursor and make another request to the same endpoint.

The maximum number of Cards returned for a BApp in a single request is 100. If the number of Cards of a BApp exceeds 100, you can retrieve the rest of the Cards using Get Card Information.

From the API response above, you can see that the minter uses 2 BApps. The first BApp has three Cards, and the second BApp has one Card. The bapps[0].cards array shows you the information including when the Card was created/updated, the address of the Card owner, the address of the Card sender, and the hash of the transaction that minted the Card.

If the number of BApps to query exceeds 100, the reponse will only contain 100 BApps per request along with the bapps.next_cursor. To retrieve the rest of the BApps, set the cursor parameter with bapps.next_cursor and make another request to the same endpoint.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

3-2. Get Card Information

Each BApp has an nft_id, which is the ID of the smart contract from which the Cards are minted. Pass the path parameter nft_id and the access_token which you received when signing up to Klip Partners via Get Card Information.

//Get Card Information - '52' is the `nft_id` of our interest.
curl "https://api.klipwallet.com/v2/wallet/nft/52" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

//An example of a Card information result
{
    "name": "conan",
    "symbol_img": "",
    "cards": [
            {
                "created_at": 1580300501,
                "updated_at": 1580300501,
                "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                "sender": "0x0000000000000000000000000000000000000000",
                "card_id": 1,
                "card_uri": "https://...",
                "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
            },
            ...
            {
                "created_at": 1580300502,
                "updated_at": 1580300502,
                "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                "sender": "0x0000000000000000000000000000000000000000",
                "card_id": 100,
                "card_uri": "https://...",
                "transaction_hash": "0x9254f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
            },

        ],
    "next_cursor": "mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL",
}

If the request is successful, it returns the list of Cards owned by the BApp and their detailed information.

  • card from cardsrefers to Klip Card used in this BApp. BApp contains one type of Card.

  • You must use either cursor or isAll as query parameter (You can use cursor if isAll is false).

  • If you use cursor, Pagination will be used.

    • You can receive information of 100 Cards per one request.

    • If the number of Cards to query exceeds 100, you can retrieve the rest of the Cardi information using next_cursor, which is the pointer from which to return the next 100 objects.

    • To retrive the rest of the Card information, set the cursor parameter with next_cursor and make another request to the same endpoint.

  • nft_id can be found via Get Card Information by BApp.

From the example above, since the field cards.next_cursor has a value, this account has over 100 conan Cards. If the number of Cards to query exceeds 100, the reponse will only contain 100 Cards per request along with the cards.next_cursor. To retrieve the rest of the Card information, set the cursor parameter with cards.next_cursor and make another request to the same endpoint.

For example, if there are a total of 150 Cards from which to retrieve information, the request will return the information of 100 Cards and the cards.next_cursor. You can retrieve the information of the remaining 50 Cards, by setting the cursor parameter with the cards.next_cursor from the previous step and make another request to the same endpoint.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

Pass cards.next_cursor and the access_token that you received when signing in to Klip Partners via Get Card Information and send a request to retrieve the rest of the Cards.

//Get Card Information, cards.next_cursor used as cursor
curl "https://api.klipwallet.com/v2/wallet/nft/52?cursor=mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

//An example of retrieving information for the remaining 50 Cards using cursor
{
    "name": "conan",
    "symbol_img": "",
    "cards": [
          {
              "created_at": 1580300503,
              "updated_at": 1580300503,
              "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
              "sender": "0x0000000000000000000000000000000000000000",
              "card_id": 101,
              "card_uri": "https://...",
              "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
          },
          ...
          {
              "created_at": 1580300515,
              "updated_at": 1580300515,
              "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
              "sender": "0x0000000000000000000000000000000000000000",
              "card_id": 150,
              "card_uri": "https://...",
              "transaction_hash": "0x9254f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
          },

      ],
    "next_cursor": "",
}

The details of the cards array is the same as that of bapps[i].cards from Get Card Information by BApp.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

3-3. Retrieving the remaining Cards when total Card number exceeds 100

Get Card Information By BApp will return the information of up to 100 Cards per request. If the number of Cards by of a BApp exceeds 100, you have to send a request to Get Card Information to retrieve the rest of the Cards. To make a query from the 101st Card, set the cursor parameter with bapps[i].cards_next_cursor and send a request to Get Card Information.

For example, say you have 2 BApps. BApp1 has 150 Cards, and BApp2 has 200 Cards. If you send a request to Get Card Information By BApp, you will get information of 100 Cards for both BApp1 and BApp2. Pass the access_token that you received when signing in and Get Card Information By BApp and make the request.

//Get Card Information By BApp
curl "https://api.klipwallet.com/v2/wallet/bapp" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

//An example of a Get Card Information By BApp response with BApp1 having 150 Cards, BApp2 having 200 Cards
{
    "bapps": [
        {
            "id": 1,
            "name": "bapp1",
            "bapp_img": "/img/bapp-icon1.svg",
            "category_id": 2,
            "nft_order_no": 1,
            "summary": "summary",
            "card_count": 150,
            "nft_id": 60,
            "cards": [
                    {
                        "created_at": 1580300503,
                        "updated_at": 1580300503,
                        "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                        "sender": "0x0000000000000000000000000000000000000000",
                        "card_id": 1,
                        "card_uri": "https://...",
                        "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
                    },

                    ...

                    {
                        "created_at": 1580300505,
                        "updated_at": 1580300505,
                        "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                        "sender": "0x0000000000000000000000000000000000000000",
                        "card_id": 100,
                        "card_uri": "https://...",
                        "transaction_hash": "0x9254f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
                    },
                ],
            "cards_next_cursor": "gKvkL1lPYv1P93dpEWgaBzrq7XZ4LwjpgNe39AH9Dt3C1iWkubJtGotkrsQs4qSwdIJMHr3HKrhlCqJupwToWCd0T55IKhLzARM60N5xAGJQbKomeDkVl2O8WxMB0GQ9"
        },
        {
            "id": 2,
            "name": "bapp2",
            "bapp_img": "/img/bapp-icon2.svg",
            "category_id": 2,
            "nft_order_no": 2,
            "summary": "summary",
            "card_count": 200,
            "nft_id": 61,
            "cards": [
                    {
                        "created_at": 1580300511,
                        "updated_at": 1580300511,
                        "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                        "sender": "0x0000000000000000000000000000000000000000",
                        "card_id": 1,
                        "card_uri": "https://...",
                        "transaction_hash": "0x1a54f10f73468ea85c84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
                    },

                    ...

                    {
                        "created_at": 1580300515,
                        "updated_at": 1580300515,
                        "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                        "sender": "0x0000000000000000000000000000000000000000",
                        "card_id": 100,
                        "card_uri": "https://...",
                        "transaction_hash": "0x3t54f10f73468ea85c84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
                    },

                ],
            "cards_next_cursor": "Xrzed2Ot9LeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL"
        },
    ],
    "next_cursor": ""
}

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

To retrieve the information for the rest of the Cards in BApp1, set the cursor parameter with bapps[0].cards_next_cursor(gKvkL1lPYv1P93dpE...) and send a request to Get Card Information.

Pass gKvkL1lPYv1P93dpE... and the access_token that you received while signing up to Klip Partners via Get Card Information and send a request to retrieve information for the rest of the 50 Cards in BApp1.

//An example of retrieving the rest of the cards in BApp 1
//Get Card Information, setting cursor with bapps[0].cards_next_cursor
curl "https://api.klipwallet.com/v2/wallet/nft/60?cursor=gKvkL1lPYv1P93dpEWgaBzrq7XZ4LwjpgNe39AH9Dt3C1iWkubJtGotkrsQs4qSwdIJMHr3HKrhlCqJupwToWCd0T55IKhLzARM60N5xAGJQbKomeDkVl2O8WxMB0GQ9" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

//An example of retrieving the remaining 50 Cards using cursor
{
    "name": "ray1",
    "symbol_img": "",
    "cards": [
            {
                "created_at": 1580300503,
                "updated_at": 1580300503,
                "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                "sender": "0x0000000000000000000000000000000000000000",
                "card_id": 101,
                "card_uri": "https://...",
                "transaction_hash": "0x9e54f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
            },
            ...
            {
                "created_at": 1580300515,
                "updated_at": 1580300515,
                "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                "sender": "0x0000000000000000000000000000000000000000",
                "card_id": 150,
                "card_uri": "https://...",
                "transaction_hash": "0x92d4f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
            },

        ],
    "next_cursor": "",
}

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

To retrieve the information of the remaining 100 Cards in BApp2, set the cursor parameter with bapps[1].cards_next_cursor(Xrzed2Ot9LeEor...) and send a request to Get Card Information. Pass Xrzed2Ot9LeEor... and the access_token that you received when signing in to Klip Partners via Get Card Information and send a request to retrieve the information of the remaining 100 Cards in BApp2.

//An example of retrieving the information of the rest of the Cards in BApp 2
//Get Card Information, setting cursor with bapps[1].cards_next_cursor
curl "https://api.klipwallet.com/v2/wallet/nft/61?cursor=Xrzed2Ot9LeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

//An example of retrieving information of the remaining 100 Cards using cursor
{
    "name": "ray2",
    "symbol_img": "",
    "cards": [
            {
                "created_at": 1580300505,
                "updated_at": 1580300505,
                "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                "sender": "0x0000000000000000000000000000000000000000",
                "card_id": 101,
                "card_uri": "https://...",
                "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
            },
            ...
            {
                "created_at": 1580300520,
                "updated_at": 1580300520,
                "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
                "sender": "0x0000000000000000000000000000000000000000",
                "card_id": 200,
                "card_uri": "https://...",
                "transaction_hash": "0x9254f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
            },

        ],
    "next_cursor": "",
}

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

3-4. Get all Cards

To get the information of all Cards at once instead of using pagination to get 100 Cards per request, send the Query parameter isAll, the Path parameter nft_id and the access_token that you received when signing in to [Klip Partners](https://partners.klipwallet.com via Get Card Information and send a request for all Cards.

//Get All Card Information - '52' is the `nft_id` of our interest.
curl "https://api.klipwallet.com/v2/wallet/nft/52?isAll=true" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

//An example of retrieving Card information
{
    "name": "conan",
    "symbol_img": "",
    "cards": [
        {
            "created_at": 1580300501,
            "updated_at": 1580300501,
            "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
            "sender": "0x0000000000000000000000000000000000000000",
            "card_id": 1,
            "card_uri": "https://...",
            "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
        },
        ...
        {
            "created_at": 1580300502,
            "updated_at": 1580300502,
            "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263",
            "sender": "0x0000000000000000000000000000000000000000",
            "card_id": 100,
            "card_uri": "https://...",
            "transaction_hash": "0x9254f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f"
        },

    ],
    "next_cursor": "",
}

If your request is successful, i will return a list of all Cards used in this BApp and their information.

  • You must use either cursor or isAll as query parameter (You can use cursor if isAll is false).

The details of the cards array is the same as that of bapps[i].cards in Get Card Information by BApp.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

4. Send Card

4-1. Send to EOA

Pass the access_token that you received when signing in, the send_info.json file, nft_id and card_id(Path Parameters) of the BApp Cards to send to Klip Partners via Send Card To user, and send a request to send the Card held by the current EOA address to another EOA address.

Any user with an EOA can receive Cards.

curl -X POST "https://api.klipwallet.com/v2/wallet/nft/50/1/send" \
-d @./send_info.json \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

An example of a send_info.json file is shown below:

//An example of send_info.json file used to send Magic Sword Card (a game item)
{
    "pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
    "to_address": "0xb1764B96da889Cc2F043025aa368517C80e86795",
    "card_name": "Magic Sword"
}

This file contains the Card name, pin, and the recipient's EOA address.

  • pin is a 64-digit string and hash(SHA256) of the PIN Code(The 6-digit string that you entered when signing up for Klip Partners).

    • pin is used in place of the private key to sign transactions.

    • PIN Code is a 6-digit string.

If the request is successful, it returns the following:

{ to_address: "0xb1764B96da889Cc2F043025aa368517C80e86795",
  fail_count: 0,
  tx_hash: "0x7cf09602cebb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97" }

If the request is successful, it returns the the Card recipient's EOA address, the number of failed attemps, and the hash of the transaction that sent the Card. If the Card is successfully sent, fail_count returns 0.

When a Card is sent, the Klip user recipient receives a notification. The sender does not get any notification. You have to include card_name so that the Card name appears for the recipient.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

4-2. Send to Klip Member

Pass the access_token that you received when signing in, and the send_info.json file, the nft_id and card_id(Path Parameter) of the BApp Card to Klip Partners via Send Card To Klip Member and send a request to send the Card currently held by the EOA address to another user.

Sends Cards only to a Klip Member identified by name and phone number.

curl -X POST "https://api.klipwallet.com/v2/wallet/nft/50/1/send/person" \
-d @./send_info.json \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

An example of a send_info.json file looks like this:

//An example of a send_info.json file for sending a game item "Magic Sword Card"
{
    "pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
    "to_person": ["Alice", "010-1111-2222"]
    "card_name": "Magic Sword"
}

This file contains the card name, pin, and the name and phone number of the Card receiver used when signing up for Klip.

  • pin is a 64-digit string and hash(SHA256) of the PIN Code(The 6-digit string that you entered when signing up for Klip Partners).

    • pin is used in place of the private key to sign transactions.

    • PIN Code is a 6-digit string.

  • If the Klip Member with the corresponding name and phone number passed to the to_person parameter doesn't exist, the send request will fail.

If the send request is successful, it returns the following:

{fail_count: 0, tx_hash: "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97"}

If the send request is successful, fail_count will return 0.

When a Card is sent, the Klip user recipient receives a notification. The sender does not get any notification. You have to include card_name so that the Card name appears for the recipient.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

5. Escrow

5-1. Approve Escrow

In order to use escrow, you first have to enable escrow in the Card minting contract. You do this by using Approve Escrow. You only need to give your approval only once.

curl -X POST "https://api.klipwallet.com/v2/escrow/approve" \
-d @./approve_info.json \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

An example of the approve.json is shown below:

{
    "pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
    "contract_address": "0x6E3571F451fc960Ea69b532006A2c8683fF8922F"
}

This file contains pin, and the contract_address, which is the address of the smart contract(SCA) that minted the Card.

  • pin is a 64-digit string and hash(SHA256) of the PIN Code(The 6-digit string that you entered when signing up for Klip Partners).

    • pin is used in place of the private key to sign transactions.

If the request is successful, it returns the following:

{
    "tx_hash":"0x831e207b0b951127646b8f7d7eded55903cecb29fe794e17a2d93f457b7158a4",
    "fail_count":0,
}

If the escrow is successfully initiated, it returns the transaction hash. If the pin could not be verified, fail_count returns a number higher than 0.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

5-2. Get Escrow Approval Status

You can find out whether escrow is enabled or not.

curl -X GET "https://api.klipwallet.com/v2/escrow/approve?contract_address=0x6E3571F451fc960Ea69b532006A2c8683fF8922F" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

{
    "approve":true
}

If the escrow is successfully initiated, the approve field returns true.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

5-3. Creat Escrow

Escrow allows you to send a Card through a link, instead of directly sending it to a Klip Member. In order to use escrow, you first have to send a request to the Create Escrow API to generate a link through which Klip user can receive the Card. You can initiate escrow process for Cards that you hold. Once the escrow process is initiated, the Card will no longer be visible from the Card list.

curl -X POST "https://api.klipwallet.com/v2/escrow" \
-d @./escrow_info.json \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

An example of the escrow_info.json file is shown below:

{
    "pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
    "contract_address": "0x6E3571F451fc960Ea69b532006A2c8683fF8922F"
    "card_ids": [15277, 15279],
}

This file contains pin, and the contract_address, which is the address of the smart contract(SCA) that minted the Card, and the array card_ids, which will be sent using escrow.

  • pin is a 64-digit string and hash(SHA256) of the PIN Code(The 6-digit string that you entered when signing up for Klip Partners).

    • pin is used in place of the private key to sign transactions.

If the request is successful, it returns the following:

{
    "tx_hash":"0x5082643fc9799badeea30d243e3c5aba46dfd0eedf623f6698c8f30c36618c6c",
    "fail_count":0,
    "claim_links": ["https://klipwallet.com/?target=/claimCard/64/15277?claimKey=234b78b5d03a395f440b3b9acf784959a4f5f0a7f6c558ef6a2d22f8fee25a79", "https://klipwallet.com/?target=/claimCard/64/15279?claimKey=8fdaae3e92208aeb19753edff72abddacfd4d4f36fe871c77eb79f061537e415"]
}

If the escrow process is successfully initiated, it returns the transaction hash, the link through which to receive the Card,and the fail_count reading 0.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

5-4. Get Cards in Escrow

If the escrow process is initiated successfully, you can retrieve the Cards that are currently in escrow.

curl -X GET "https://api.klipwallet.com/v2/escrow?contract_address=0x6E3571F451fc960Ea69b532006A2c8683fF8922F&cursor=" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

{
    "name":"Partners Card",
    "symbol_img":"https://...",
    "cards":[{"created_at":1605921829,"updated_at":1606057801,"owner":"0x7998d102b2938532bc068300517d4db783f326c2","sender":"0xc95e3a887cb2108d4a19e2a9bcbe0827367372fe","card_id":15279,"card_uri":"https://klip-media.klaytn.com/card_asset/20295/7de0f5cc-6624-487f-adb9-4bfa86d38992.json","transaction_hash":"0x5082643fc9799badeea30d243e3c5aba46dfd0eedf623f6698c8f30c36618c6c"},{"created_at":1605921668,"updated_at":1606057801,"owner":"0x7998d102b2938532bc068300517d4db783f326c2","sender":"0xc95e3a887cb2108d4a19e2a9bcbe0827367372fe","card_id":15277,"card_uri":"https://klip-media.klaytn.com/card_asset/20295/e18133b8-aedc-4daf-aa2a-87654beabadf.json","transaction_hash":"0x5082643fc9799badeea30d243e3c5aba46dfd0eedf623f6698c8f30c36618c6c"}],
    "next_cursor":""
}

For details on the cards array, please refer to the Response Detail in Get Cards in Escrow.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

5-5. Cancel Escrow

You can the escrow process for Cards that are in escrow. Once cancelled, the Cards become visible in the Card list again.

curl -X DELETE "https://api.klipwallet.com/v2/escrow" \
-d @./cancel_info.json \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

An example of the cancel_info.json file is shown below:

{
    "pin": "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
    "contract_address": "0x6E3571F451fc960Ea69b532006A2c8683fF8922F"
    "card_ids": [15277, 15279],
}

This file contains pin, the contract_address, which is the address of the smart contract(SCA) that minted the Card, and the array card_ids, which are Cards for which the escrow process will be cancelled.

  • pin is a 64-digit string and hash(SHA256) of the PIN Code(The 6-digit string that you entered when signing up for Klip Partners).

    • pin is used in place of the private key to sign transactions.

If the request is successful, it returns the following:

{
    "tx_hash":"0x831e207b0b951127646b8f7d7eded55903cecb29fe794e17a2d93f457b7158a4",
    "fail_count":0,
}

If the escrow process is successfully initiated, it returns the transaction hash with fail_count reading 0.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

6. Transaction

6-1. Get Transaction Result

You can find out whether the transaction has been successfully recorded on blockchain. If you attempt to retrieve the result right after sending a transaction request, it may return 4700: no transaction receipt. It is recommended to wait at least 2 seconds and repeat the request until it succeeds.

curl -X GET "https://api.klipwallet.com/v2/wallet/receipt?tx_hash=0x880a45d3c482c7d794c2e7b7dbdc9e933a68f4a1f3d978d582ba9f9ebd1f9e72" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

{
  "success": true
}

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

7. Manage Account

7-1. Change Password and PIN

Send old_password, new_password and the access_token that you received when signing in to Klip Partners via Change Passwordand send a request to change password.

  • old_password and new_password are 64-digit strings and hash(SHA256) of the old/new passwords.

    • Password is a string consisting of 8-16 alphabet characters, numbers, and special characters.

curl -X PUT "https://api.klipwallet.com/v2/partner/?opt=password" \
-d '{"old_password":"HASHED_OLD_PASSWORD", "new_password":"HASHED_NEW_PASSWORD"}' \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

{}

If there is no error, the password should have changed successfully.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

Pass the old PIN, new PIN, and the access_token that you received when signing in to Klip Partners via Change PIN and send a request to change PIN.

  • old_pin and new_pin are 64-digit strings and hash(SHA256) of the old/new PIN.

    • old_pin and new_pin are used in place of the private key to sign transactions.

    • The old/new PIN are a 6-digit string of numbers.

curl -X PUT "https://api.klipwallet.com/v2/partner/pin" \
-d '{"old_pin":"HASHED_OLD_PIN_NUMBER", "new_pin":"HASHED_NEW_PIN_NUMBER"}' \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

{}

If there is no error, your PIN should have changed successfully.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

7-2. Get Mint Count

You can find out the total number of Cards minted using a Partner account. The count is renewed on the 1st day of each month.

curl -X GET "https://api.klipwallet.com/v2/wallet/mint/count" \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

If the request is successful, it returns the following:

{
  "mint_count": 10
}

mint_count returns the total number of Cards minted.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

7-3. Delete Card

Pass the delete_info.json file, the access_token that you received when signing in to Klip Partners via Delete Card and send a request to delete the Card.

curl -X DELETE "https://api.klipwallet.com/v2/wallet/nft" \
-d @./delete_info.json \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json"

An example of the delete_info.json file is shown below:

//An example of the delete_info.json file
{
    pin: "91B4D142823F7D20C5F08DF69122DE43F35F057A988D9619F6D3138485C9A203",
    card_id: 12,
    contract_address: "0xbad6444e1f84af055c22281d4ac7d75bde2ddec8"
}

This file contains the ID of the Card to delete, the SCA address of the contract that minted the Card, and the PIN.

  • pin is a 64-digit string and hash(SHA256) of the PIN Code(The 6-digit string that you entered when signing up for Klip Partners).

    • pin is used in place of the private key to sign transactions.

If the request is successful, it returns the following:

{
    "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97"
}

If there is no error, the Card should have been deleted successfully. With successful deletion, it returns the transaction hash.

You can't delete Cards already sent to others. Deleting a Card will not delete the Card image.

If the request is not successful, it returns the following:

"bad request": Incorrect request. Check if you entered the right request parameters.

If you need help with this document or with Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).

PreviousTutorialNextApp2App API

Last updated