# Introduction This page is an introduction to Klip and Klip Developer Guide. ## Klip Klip is a personal digital wallet that allows you to conveniently manage digital assets. Despite there being numerous blockchain wallets out there, most of them failed to gain traction due to poor user experience (UX). Klip, on the other hand, is integrated in the messaging app KakaoTalk, and offers a good, simple UX. It can also contribute to the growth of blockchain applications (BApps), acting as a window to diverse [Klaytn](https://www.klaytn.com/)-based BApps. For more information on Klip, download KakaoTalk and go into the More\[…] tab on the menu.\ \ If you need any help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). ## BApp and Card BApps (Blockchain Applications) and DApps (Decentralized Applications) are essentially similar, but while the latter tends to emphasize "decentralization", BApp is a broader term that encompasses more of the unique advantages that blockchains offer. Fore more details on BApps, please visit [Klaytn BApp](https://docs.klaytn.com/misc/vision/bapps). Digital assets on Klip are called Cards. Klip Partners can issue various assets (game items, discount coupons etc.) in the form of Cards and send them to Klip or BApp users. Users can use or send the Cards they received on Klip, located in the More\[…] tab in the mobile app KakaoTalk. During this process, Klip Partners get a chance to expose their BApps to potential customer base and convert them into actual clients. All cards are [**NFTs**](https://docs.klaytn.com/smart-contract/token-standard#non-fungible-token-standard-kip-17)(Non-Fungible Tokens). In simple terms, NFTs are **unique assets**, and not "currencies"(like Bitcoin, Ether etc.). For example, a dollar bill can be replaced with any other dollar bill any day, which makes it **fungible**. But my artwork is not replaceable with my neighbor's artwork, and thus is **non-fungible**. This is because the value of each art piece is unique, which cannot be compared in a consistent, let alone objective way. To sum up, NFTs are digitized piece of a unique asset, such as collectibles, artwork, and personal items, created in the form of tokens on a blockchain. The NFT used for BApps is called Cards. Klip users can use and exchange them on Klip.\ \ If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). ## Klip API Klip API allows you to send KLAY or FTs (Fungible Tokens), mint, retrieve, send, and burn NFTs on Klip from external services. It consists of Card Minting API and App2App API. ### Card Minting API Card Minting API allows registered Partners to mint, retrieve, send, and burn Cards. Using this simple API, you can build BApps that utilize Cards without having to deploy or manage complex smart contracts yourself. The steps for using Card Minting API are as follows: 1. Apply to become a [Klip Partners](https://partners.klipwallet.com). 2. After receiving approval from the Klip team, [Sign In](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#sign-in) on the website. 3. After signing in, upload a cover image for your Card via [Upload Image](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#upload-image). 4. Start minting Cards using the uploaded image via [Mint Card To User](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#mint-card-to-user) or [Mint Card To Klip Member](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#mint-card-to-klip-member). 5. You can retrieve Card information using [Get Card Information By BApp](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#get-card-information-by-bapp), [Get Card Information](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#get-card-information). 6. Send the minted Card to other users via [Send Card To User](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#send-card-to-user) or [Send Card To Klip Member](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#send-card-to-klip-member). The API also allows you to conveniently manage accounts and Cards. * Sign in with [Sign In](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#sign-in). * Change password to your account with [Change Password](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#change-password). * Change PIN with [Change Pin](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#change-pin). * Retrieve and Delete Cards using [Delete Card](https://github.com/ground-x/klip-docs/blob/EN/rest-api-card-minting.md#delete-card). Klip API allows you to send KLAY or FT (Fungible Tokens) from external services, or to mint, retrieve, send, burn NFTs on Klip. Klip API consists of Card Minting API and App2App API. ### App2App API App2App API allows BApp developers to authenticate Klip users as well as send tokens and Cards without a separate registration process. You can also make requests to Klip users to execute smart contracts that you wrote. In a mobile environment where KakaoTalk is installed, BApps will generate a deep link to request signature on Klip. App2App API can be used to: * authenticate BApp user's Klip Wallet address * send KLAY, tokens through Klip * send and retrieve Cards through Klip * run smart contracts through Klip The steps for using App2App API are as follows: * Select and install the suitable SDK for your BApp in the [Download](https://github.com/ground-x/klip-docs/blob/EN/a2a-sdk-download.md) tab. Alternatively, you can use REST API. * Incorporate Klip user authentication or signature function into your BApp using the Prepare, Request and Result APIs. During the **Prepare** step, you will obtain the key required to use App2App API, and for the **Request** step, run Klip. Finally in the **Result** step, you can view the request results. * The **Request** step can be done using QR code on PC or in a remote mobile environment. See [App2App REST API](https://github.com/ground-x/klip-docs/blob/EN/rest-api-a2a.md#request) for more details. ![Card Minting](/files/-MkaVpBtOVOx7_EGRXSg) \ \ If you need any help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). ## About This Document Klip Developer Guide contains instructions for BApp developers or Partners to manage and send FTs, or to mint, send, and burn NFTs using various APIs. | Page | Description | | ----------------------------------------------------------------------- | ----------------------------------------------------- | | [Introduction](/) | Klip and Klip API. | | [Basics](/basics) | Authentication, pagination, error code, and glossary. | | [REST API](https://github.com/ground-x/klip-docs/blob/EN/rest-api.md) | Card Minting API and App2App API. | | [App2App SDK](https://github.com/ground-x/klip-docs/blob/EN/a2a-sdk.md) | App2App API SDKs for JavaScript, Android, iOS. | | [Tutorial](https://github.com/ground-x/klip-docs/blob/EN/tutorial.md) | Tutorials for Card Minting API and App2App API. | | [Change Log](/changelog) | The change log of APIs | {% hint style="warning" %} This document contains some basic information on API and development, which is subject to change. Software built following the instructions stated here must undergo a final test with the appropriate operating systems. {% endhint %} \ If you need any help with this document or Klip in general, please visit our \[Developer Forum]\(). # Basics This page provides an overview on Card Minting API, user authentication for App2App API, pagination, return codes and abbreviations. ## Card Minting API ### Authentication Before you can start working with Card Minting API, you need a JWT access token. You can obtain the token using the ID and password that you used for registering as Klip Partners. Tokens are valid for 24 hours and have to be refreshed before they expire. Issued tokens should be provided in the `Authrization` field of the request header when making the API request. \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Pagination When you want to retrieve the information for a large number of Cards, you may have to make multiple requests in order to avoid being overwhelmed with too many results. That's where `next_cursor` comes in handy. GET API requests will return `next_cursor`, which is a pointer to a specific item in the dataset. So, say you make a GET request for over 100 Cards, it will return 100 items in the result *and* a `next_cursor` value. To retrieve the rest of the Cards, set the `cursor` parameter with `next_cursor` and make another request to the same endpoint. Here's an example request to retrieve your Card information: ```bash //Get Card Information By BApp curl "https://api.klipwallet.com/v2/wallet/bapp" \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` You will get the following response: ```javascript { "bapps": [...], "next_cursor": "N2r8KY...XOadEG" } ``` To retrieve the rest of the Cards, use `next_cursor` in the next request. You can get a complete list of all the Cards by continuing to make calls until the `next_cursor` field is returned empty. ```bash //Get Card Information By BApp curl "https://api.klipwallet.com/v2/wallet/bapp?cursor=N2r8KY...XOadEG" \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Success Codes/Error Codes If a request is successful, the server returns HTTP code 200. In case of an error, it returns HTTP codes 400, 401, or 500. 400 indicates that the request has incorrect syntax. 401 means that the access token is invalid. And 500 means that the server encountered an unexpected error. The 400 or 401 series errors are returned with a specific error code with a message. The error message is in JSON format with the following fields: If a request was successful, the server returns HTTP code 200. If a request results in an error, it will return HTTP codes 400, 401, or 500. 400 indicates that the request has incorrect syntax, and 401 is returned when the client provided an invalid access token. 500 means that the server encountered an unexpected error. 400 or 401 series errors will be returned with a specific error code along with a message. The error message is in JSON format with the following fields: ```javascript { "code": number, "err": string } ``` Below is the list of error messages: | Status Code | Error Code | Error Message | | ----------- | ---------- | -------------------------------------------------------- | | 400 | 400 | bad request | | 400 | 410 | invalid birth for account creation | | 400 | 411 | teenagers under the age of 19 are not allowed to sign up | | 400 | 412 | already existing account (wallet) | | 400 | 413 | already existing email | | 400 | 414 | already existing account without wallet | | 400 | 4111 | receiver is already an user of klip | | 400 | 4112 | sender daily limit exceeded | | 400 | 4113 | sender already sent invite message to receiver | | 400 | 4114 | receiver daily limit exceeded | | 400 | 4115 | receiver monthly limit exceeded | | 400 | 4070 | send token count daily limit exceeded | | 400 | 4071 | send token amount onetime limit exceeded | | 400 | 4072 | send token amount decimal places exceeded | | 400 | 4080 | mint count monthly limit exceeded | | 401 | 420 | inactive accounts require new pin code settings | | 401 | 421 | suspended accounts cannot login | | 401 | 422 | the account requesting the suspension | | 401 | 423 | the account has been unsubscribed | | 401 | 424 | undefined status | | 401 | 425 | not yet approved | | 401 | 440 | content is not active | | 401 | 402 | invalid session | | 400 | 403 | exceed pin code error count | | 404 | 404 | not Found | | 401 | 405 | attempted access from non-kakako app | | 401 | 406 | not found user info in db | | 401 | 4001 | invalid access token | | 401 | 4002 | the expired token | | 401 | 4003 | fail to get authorization in header | | 401 | 4004 | invalid password | | 401 | 4005 | account does not have a contract address | | 401 | 4006 | invalid pin code | | 400 | 4007 | not allow the same code as before | | 400 | 430 | duplicated ci for account creation | | 400 | 431 | inconsistency with previous ci | | 400 | 432 | fail to check Kakao ci | | 400 | 433 | fail to check Kakao legal name | | 400 | 434 | fail to check Kakao phone number | | 400 | 435 | kakao ci is empty | | 500 | 500 | internal server error | | 500 | 501 | fail to send kakao message | | 500 | 5002 | fail to call kakao unlink | | 401 | 4044 | access token does not exist | | 500 | 5003 | kakao server error | \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). #### Glossary | Term | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Klaytn | [Klaytn Blockchain Platform](https://www.klaytn.com/) | | Smart Contract | A collection of code (functions) and data (states) located in a specific Contract Address on the Klaytn blockchain. | | KLAY | The native transactional currency used on the Klaytn blockchain. | | FT | Fungible token, or just token. See [KIP-7](https://docs.klaytn.com/smart-contract/token-standard#fungible-token-standard-kip-7) for more. | | NFT | Non-fungible Token, or Card. See [KIP-17](https://docs.klaytn.com/smart-contract/token-standard#non-fungible-token-standard-kip-17) for more. | | Card | The digital asset (NFT) used on Klip | | Account | The entity that owns digital assets and sends transactions to the network on Klaytn. | | Sending transaction | The act of "changing" the blockchain's state, which normally involves uploading, editing, deleting data or deploying, executing smart contracts on the blockchain | | EOA | Klaytn's Externally Owned Account. The entity that owns KLAY, NFTs, FTs on Klaytn and sends transactions to the network. See [Account](https://docs.klaytn.com/klaytn/design/accounts#klaytn-account-types) for more. | | Signature | The act of creating data to prove that the transaction to be executed on Klaytn has been initiated by the sender. | | Account Key | The key used for signatures. A valid signature to the transaction is given by the AccountKey. | If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ## App2App API ### Authentication App2App API doesn't require authentication. But a request key for different API requests is issued to distinguish between different BApps. This key allows Klip server to keep the requests separate and organized. The steps for obtaining and using a request key are described below: * Pass the authentication or signature data via the `prepare` function and obtain the request key in the response. * Request a deep link(URI that sends users directly to a specific location in an app) using the returned request key, and run Klip located in the More\[…] tab in the mobile app KakaoTalk. * You can send a polling request to Result API, specifying which request you want the results for in the query parameter `request_key`. \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Pagination When you want to retrieve the information for a large number of Cards, you may have to make multiple requests in order to avoid being overwhelmed with too many results. That's where `next_cursor` comes in handy. GET API requests will return `next_cursor`, which is a pointer to a specific item in the dataset. So, say you make a GET request for over 100 Cards, it will return 100 items in the result *and* a `next_cursor` value. To retrieve the rest of the Cards, set the `cursor` parameter with `next_cursor` and make another request to the same endpoint. Here's an example request for retrieving your Card information: ```bash //Get card list curl "https://api.klipwallet.com/v2/a2a/cards?sca=SCA&eoa=EOA" \ -H "Content-Type: application/json" ``` You will get the following response: ```javascript { "name": "KLIP", "symbol_img": "image url", "cards": [...], "next_cursor": "N2r8KY...XOadEG" } ``` To retrieve the rest of the Cards, use `next_cursor` in the next request. You can get a complete list of all the Cards by continuing to make calls until the `next_cursor` field is returned empty. ```bash //Get card list curl "https://api.klipwallet.com/v2/a2a/cards?sca=SCA&eoa=EOA&cursor=N2r8KY...XOadEG" \ -H "Content-Type: application/json" ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### SDK App2App API is primarily a RESTful API, but it also supports SDKs for the different development environments of each BApp. Currently available are SDKs for Android, iOS, and JavaScript for mobile web. See [SDK Page](https://github.com/ground-x/klip-docs/blob/EN/a2a-sdk.md) for more details. ### Success Codes/Error Codes If a request is successful, the server returns HTTP code 200. In case of an error, it returns the HTTP codes 400 or 500. 400 indicates that the request has incorrect syntax, or the `request_key` is invalid. 500 means that the server encountered an unexpected error. The 400 series errors are returned with a specific error code with a message. Refer to each API for detailed explanations. The error message is in JSON format with the following fields: The error message is in JSON format with the following fields: ```javascript { "request_key": "random key", "expiration_time": unix timestamp, "status": "error", "error": { "code": int, "err": "error message" } } ``` Since the Get Card Information API (/v2/a2a/cards) is not relevant to `request_key`, an error looks like this: ```javascript { "code": number, "err": string } ``` Here is list of error messages: | Status Code | Error Code | Error Message | | ----------- | ---------- | ------------------------------------------- | | 400 | 400 | bad request | | 400 | 6000 | request key does not exist | | 400 | 6001 | request key is expired | | 400 | 6010 | invalid request type | | 400 | 6011 | invalid request status | | 400 | 6200 | execute contract count daily limit exceeded | | 400 | 6401 | bapp name is required | | 400 | 6402 | invalid transaction | | 400 | 6403 | invalid to address | | 400 | 6404 | invalid amount | | 400 | 6405 | invalid contract | | 400 | 6406 | invalid card id | | 400 | 6407 | invalid abi | | 400 | 6408 | invalid params | | 400 | 6409 | invalid value | | 400 | 6410 | unknown request type | | 400 | 6411 | invalid from address | | 400 | 6412 | insufficient funds | | 400 | 6500 | address is on the blacklist | | 400 | 6501 | invalid user status | | 500 | 500 | internal server error | \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). | Term | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Deep link | URI that direct users straight to a specific location instead of a website (Used to specify the operations to request using query parameters) | | Request key | A randomly generated string (e.g. `a0fee72d-3b1b-43a3-ae0d-e277a1001bef`) to identify App2App API requests | \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). # REST API This page introduces Klip REST API. Klip REST API consists of Card Minting API and App2App API. ## Card Minting API Card Minting API is a REST API for implementing the functions to mint, send, delete and manage Klip Cards (NFT). Card Minting API allows you to sign in, manage accounts, and mint, send and manage Cards. ## App2App API App2App API is an API for implementing the function to link your "BApp" with "Klip". App2App API accesses Klip user accounts from the BApp to send KLAY, Klip Cards, or Klip tokens to other users, or initiate a smart contract. App2App API is available as a REST API and SDK (iOS, Android, JavaScript). | Item | Description | Notes | | --------------------------------------------------- | --------------------------------------------------------------------------------- | ----- | | [Card Minting API](/rest-api/rest-api-card-minting) | Mint, send, manage Klip Cards | | | [App2App API](/rest-api/rest-api-a2a) | Links BApp with Klip to send Klip Cards, tokens, KLAY and initate smart contracts | | 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). # Card Minting This page explains how to sign in to Klip Partners to mint, retrieve, send, and delete Cards using Card Minting API. ## Account Management Account Management consists of Signing In, Changing Password, and Changing PIN. ### Sign In ## Sign In `POST` `https://api.klipwallet.com/v2/partner/auth` After receiving membership approval, signs in to Klip Partners using the email address and password that were used to sign up. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ---------------- | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------- | | email\* | string | The email address used to sign up. This will be your account used for signing in. | | password\* | string | The password used for signing in. It will be sent as a SHA256 of the password used up sign up. | {% tabs %} {% tab title="200 " %} ``` { "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" : 1 "mint_limit": 1000 "mint_count": 1 } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="406" %} ``` "not found user info in db": Account data not found. ``` {% endtab %} {% tab title="426" %} ``` "not yet approved": Not approved for signup yet. ``` {% endtab %} {% tab title="4004" %} ``` "invalid password": Wrong password. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to sign in. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} [Klip Partners](https://partners.klipwallet.com) is currently accessible only by authorized entities. If your business is considering using the service, please submit via email (1) an introduction of your business, (2) purpose of using Cards, and (3) Card application ideas to . **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/partner/auth" \ -d '{"email":"terri.kwak@groundx.xyz", "password":"C01069C9ABB6EA7DA49AE418A24BBEF3AD67170DDCD20AC7C76084A5A85E4057"}' \ -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | email | string | The email address of the Partner that will be used for signing in. | | klaytn\_address | string | The address of the Partner's Klaytn [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas). | | contract\_address | string | The address of the [SCA](https://docs.klaytn.com/klaytn/design/accounts#smart-contract-accounts-scas) that mints Cards. | | name | string | Legal or registered business name of the Partner. | | phone | string | The phone number of the Partner. | | service\_name | string | The name of the BApp provided by the Partner. | | access\_token | string | A JWT authentication token issued to enable API requests. | | status | number | Account status code. | | mint\_limit | number | The maximum number of Cards that can be issued by the account. | | mint\_count | number | The number of Cards actually issued by the account in one month. | {% hint style="info" %} `status` will read 20 before the signup approval, and 1 after the approval.\ `access_token` will expire after 24 hours. `mint_count` and `mint_limit` will be renewed on the 1st day of each month. {% endhint %} For more details, please refer to our [Tuturial](/tutorial/tutorial-card-minting#sign-in).\ 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). ### Change Password ## Change Password `PUT` `https://api.klipwallet.com/v2/partner/?opt=password` Changes the password that was used to sign up. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------ | | old\_password\* | string | Your old password. | | new\_password\* | string | Your new password. | {% tabs %} {% tab title="200 " %} ``` {} ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="4004" %} ``` "invalid password": Wrong password. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to change password. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} **Request Example** ``` 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" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#change-password-and-pin).\ 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). ### Change PIN ## Change PIN `PUT` `https://api.klipwallet.com/v2/partner/pin` Changes the PIN Code. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ------------------ | | old\_pin\* | string | Your old PIN Code. | | new\_pin\* | string | Your new PIN Code. | {% tabs %} {% tab title="200 " %} ``` {} ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="403" %} ``` "exceed pin code error count": You exceeded the invalid PIN Code limit. ``` {% endtab %} {% tab title="4006" %} ``` "invalid pin code": PIN Code doesn't match. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to change PIN Code. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} **Request Example** ``` 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" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#change-password-and-pin).\ 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). ## Card Management Card Management consists of Uploading Image, Minting Card To Users, Minting Card To Klip Members, Sending Card To Users, Sending Cards To Klip Member, Getting Card Information By Bapp, Getting Card Information, and Deleting Cards. ### Upload Image ## Upload Image `POST` `https://api.klipwallet.com/v2/wallet/image` Uploads an image to be used for the Card. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | multipart/form-data | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | ------------------------------------------------------------------ | | upload\* | string | The file name of the image to be uploaded. Must include file path. | {% tabs %} {% tab title="200 " %} ``` {"image": "https://url_path_to_img_file/image.png"} ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to upload image. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/wallet/image" \ -F upload=@./imagefile.png \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: multipart/form-data" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#upload-image).\ 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). ### Upload NFT Resource ## Upload NFT resource `POST` `https://api.klipwallet.com/v2/wallet/nftResource` Uploads a resource that will be used for the Cards. A video file for the `animation_url` field is limited to 10MiB. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | multipart/form-data | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | ------------------------------------------------------------------ | | upload\* | string | The file name of the image to be uploaded. Must include file path. | {% tabs %} {% tab title="200 " %} ``` {"url": "https://url_path_to_file/file.mp4"} ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="4100" %} ``` "upload animation file limit exceeded": The video file exceeds 10MiB. Check the file size again. ``` {% endtab %} {% tab title="4101" %} ``` "upload animation file extension is not support": This video format is not supported. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to upload file. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/wallet/nftResource" \ -F upload=@./file.mp4 \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: multipart/form-data" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#upload-nftresource).\ 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). ### Mint Card to User ## Mint Card To User `POST` `https://api.klipwallet.com/v2/wallet/mint` Sends user information to Klip Partners and mints Cards. Cards will be minted to EOAs. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pin\* | string | The PIN Code that will be used for signing transactions. | | to\_address\* | array | An array of `string`s containing the EOA addresses where the Cards will be minted. | | contract\_address\* | string | The address of the SCA that will mint the Card. | | name\* | string | The name of the Cards. | | description\* | string | Description of the Cards. | | image\* | string | The URL of the image to be used for the Cards. | | animation\_url | string | The URL of the video that will be used for the Cards. Supported file extension is `.mp4`. The video won't play if it doesn't have H.264 codec or if the resolution is over `3840x2160`. | | background\_color | string | The RGB color code to be used as the Card's background. | | sendable | boolean | If TRUE, the Cards can be sent from Klip to another account. | | send\_friend\_only | boolean | If TRUE, the Cards can be sent from Klip only to your friend on KakaoTalk. | | group\_name | string | The name of the Card group. | | group\_icon | string | The URL of the image to be used as the Card group icon. | | hashtags | array | An array of `string`s containing hashtags. Hashtags make your Cards searchable by certain keywords. | | layout | string | Determines how the Cards will be displayed. Square is `general`, wide rectangle is `horizontal`, and long rectangle is `vertical`. The default value is `general`. | | external\_link | string | The URL address outside of Klip to which users are redirected. (Max. 255 characters) | | qr\_code | string | The image URL with QR Code. (Max. 255 characters) | | bar\_code | string | The image URL with Bar Code. (Max. 255 characters) | | attributes | array | An array of `object`s containing the Cards' attributes. (Max. 10 elements) | | secure | object | An `object` containing information only visible to the holder. You can select from the fields `bar_code`, `qr_code` and `attributes`. | | status\_url | string | An external URL with the Card's status. This URL must return a JSON object. You can set the required boolean type field `valid` and the optional array type field `attributes`. | {% tabs %} {% tab title="200 " %} ``` { "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97" } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to mint Cards. As some of the Cards may have been minted, send a request to **Get Card List** to see the complete list of tokens. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} ``` //attributes example 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 example (Normally you select one of either bar_code or qr_code) 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 example status_url: "https://your-domain.com?key=1234" //Response sample of a status_url request { valid: true, 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" } ] } ``` **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/wallet/mint" \ -d @./mint_info.json \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` **Request Details for** `secure` | Item | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | bar\_code | string | The string to be displayed as barcode. It follows the CODE 128 standard. This field is optional. (Max. 20 characters excluding ' '(empty space) or '-') | | qr\_code | string | The string to be displayed as QR code. This field is optional. (Max. 255 characters) | | attributes | array | An array of `object`s containing the Cards' attributes. | For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#mint-card-to-user).\ 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). ### Mint Card to Klip Member ## Mint Card To Klip Member `POST` `https://api.klipwallet.com/v2/wallet/mint/person` Sends Klip user information to Klip Partners and mints Card. Card will be minted to the EOA of Klip Member based on the name and phone number provided in `to_person`. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pin\* | string | The PIN Code that is used to sign the transaction. | | to\_person\* | array | A two-dimensional array containing the name and phone number of the recipient. | | contract\_address\* | string | SCA address from which the Cards will be minted. | | name\* | string | The name of the Cards. | | description\* | string | The description of the Cards. | | image\* | string | The URL of the image to be used for the Cards. | | animation\_url | string | The URL address of the video that will be used for the Cards. Supported file extension is `.mp4`. The video won't play if it doesn't have H.264 codec or if the resolution is over `3840x2160` | | background\_color | string | The RGB color code to be used as the Card's background. | | sendable | boolean | If TRUE, the Cards can be sent from Klip to another account. | | send\_friend\_only | boolean | If TRUE, the Cards can be sent from Klip only to your friend on KakaoTalk. | | group\_name | string | The name of the Card group. | | group\_icon | string | The URL of the image to be used as the Card group icon. | | hashtags | array | An array of `string`s containing hashtags. Hashtags make your Cards searchable by certain keywords. | | layout | string | Determines how the Cards will be displayed. Square is `general`, wide rectangle is `horizontal`, and long rectangle is `vertical`. The default value is `general`. | | external\_link | string | The URL address outside of Klip to which users are redirected. (Max. 255 characters) | | qr\_code | string | The image URL with QR Code. (Max. 255 characters) | | bar\_code | string | The image URL with Bar Code. (Max. 255 characters) | | attributes | array | An array of `object`s containing the the Cards' attributes. (Max. 10 elements) | | secure | object | An `object` containing information only visible to the holder. You can select from the fields `bar_code`, `qr_code` amnd `attributes`. | | status\_url | string | An external URL containing the Card status. This URL must return a JSON object. You can set the required boolean type field `valid` and the optional array type field `attributes`. | {% tabs %} {% tab title="200 " %} ``` { "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97", "result": [["Bruce", "010-1111-2222", "success", ""], ["Janet", "010-3333-4444", "fail", "phone number does not exist"], ...] } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to mint Cards. As some of the Cards may have been minted, send a request to **Get Card List** to see the complete list of tokens. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} ``` //attributes example 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 example (Normally you select one of either bar_code or qr_code) 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 예시 status_url: "https://your-domain.com?key=1234" //Response example for a status_url request { valid: true, 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" } ] } ``` **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/wallet/mint/person" \ -d @./mint_person_info.json \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` **Request Details for** `secure` | Item | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | bar\_code | string | The string to be displayed as barcode. It follows the CODE 128 standard. This field is optional. (Max. 20 characters excluding ' '(empty space) or '-') | | qr\_code | string | The string to be displayed as QR code. This field is optional. (Max. 255 characters) | | attributes | array | An array of `object`s containing the Cards' attributes. This field is optional. | For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#mint-card-to-klip-member).\ 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). ### Get Mint Count ## Get Mint Count `GET` `https://api.klipwallet.com/v2/wallet/mint/count` Returns the total number of Cards minted using the Partner account. The count is renewed on the 1st day of each month. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "mint_count": 10 } ``` {% endtab %} {% endtabs %} **Request Example** ``` curl -X GET "https://api.klipwallet.com/v2/wallet/mint/count" \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ----------- | ------ | -------------------------------------------- | | mint\_count | number | The number of Cards minted during the month. | For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#mint-count).\ 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). ### Send Card to User ## Send Card To User `POST` `https://api.klipwallet.com/v2/wallet/nft/:nft_id/:card_id/send` Sends Card to other users' EOAs. #### Path Parameters | Name | Type | Description | | ------------------------------------------ | ------ | -------------------------------------------------------------- | | nft\_id\* | string | The ID of the smart contract that minted the Card in the BApp. | | card\_id\* | string | The ID of the Card in the BApp. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | --------------------------------------------- | ------ | ------------------------------------------------------- | | pin\* | string | The PIN Code that will be used to sign the transaction. | | to\_address\* | string | The EOA address of the recipient of the Cards. | | card\_name\* | string | The name of the Card to send. | {% tabs %} {% tab title="200 " %} ``` // Successful response example { to_address: "0xb1764B96da889..." , fail_count: 0, tx_hash: "0x7cf09602cebb..."} // One failed PIN Code attempt {fail_count: 1} // Two failed PIN Code attempts {fail_count: 2} // The PIN Code attempt limit is 5. // Even if you get it right on the 6th attempt, it will return this response: {fail_count: 6} // The maximum value for fail_count is currently 6. // Seven failed PIN Code attempts {fail_count: 6} ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} {% hint style="info" %} You have to include `card_name` so that the Card name appears for the recipient. {% endhint %} **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/wallet/nft/60/1/send" \ -d @./send_info.json \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#send-card-to-user).\ 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). ### Send Card to Klip Member ## Send Card To Klip Member `POST` `https://api.klipwallet.com/v2/wallet/nft/:nft_id/:card_id/send/person` Sends Card to Klip Member to the EOA of Klip Member based on the name and phone number provided in `to_person`. #### Path Parameters | Name | Type | Description | | ------------------------------------------ | ------ | ----------------------------------------------- | | nft\_id\* | string | ID of the smart contract that minted the Cards. | | card\_id\* | string | The ID of the Card. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ---------------------------------------------------------------------------- | | pin\* | string | The PIN Code that was used to sign the transaction. | | to\_person\* | array | An array of `string`s that contains the recipients' names and phone numbers. | | card\_name\* | string | The name of the Card to send. | {% tabs %} {% tab title="200 " %} ``` // Successful response example { fail_count: 0, tx_hash: "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97" } // One failed PIN Code attempt {fail_count: 1, tx_hash: ""} // Two failed PIN Code attempts {fail_count: 2, tx_hash: ""} // The PIN Code attempt limit is 5. // Even if you get it right on the 6th attempt, it will return this response: {fail_count: 6, tx_hash: ""} // The maximum value for fail_count is currently 6. // Seven failed PIN Code attempts {fail_count: 6, tx_hash: ""} ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} {% hint style="info" %} You have to include `card_name` so that the Card name appears for the recipient. {% endhint %} **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/wallet/nft/60/1/send/person" \ -d @./send_person_info.json \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#send-card-to-klip-member).\ 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). ### Get Card List ## Get Card List `GET` `https://api.klipwallet.com/v2/wallet/bapp?cursor=` Returns a list of all your Cards. Cards will be displayed grouped in BApps. #### Query Parameters | Name | Type | Description | | ------ | ------ | ------------------------------------------------------------------------------------------------------------- | | cursor | string | The pointer after which the next request will retrieve the next 100 items if the number of BApps exceeds 100. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "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://.../card_meta.json", "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f" }, ... ], "cards_next_cursor": "" }, ... ], "next_cursor": "" } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve your list of Cards. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} **Request Example** ``` curl "https://api.klipwallet.com/v2/wallet/bapp?cursor=mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` **Response Details for** `bapps[i]`; | Item | Type | Description | | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | | id | number | The ID of the BApp. | | name | string | The name of the BApp. | | bapp\_img | string | The address of the BApp image file. | | category\_id | number | The ID for the BApp categories. | | nft\_order\_no | number | The order in which the Card groups are displayed on the Klip Card list. | | summary | string | A one-liner description about the BApp. | | card\_count | number | The number of Cards specifically used for this particular BApp. | | nft\_id | number | The ID of the NFT. NFT is the smart contract that implements the Card on the blockchain. | | cards | array | An array of `object`s containing the information of each Card. | | cards\_next\_cursor | string | The pointer after which the next request will retrieve the next 100 items if the number of Cards exceeds 100. | | next\_cursor | string | The pointer after which the next request will retrieve the next 100 items if the number of BApps exceeds 100. | **Response Details for** `bapps[i].cards[i]` | Item | Type | Description | | ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | | created\_at | number | The time at which the Card was minted. | | updated\_at | number | The time at which the Card was updated. | | owner | string | The [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address of the Card owner. | | sender | string | The [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address of the Card sender. | | card\_id | number | The ID of the Card. | | card\_uri | string | The URL of the JSON file containing the Card's metadata. | | transaction\_hash | string | The transaction hash of the smart contract that minted the Card. | For more details, please refer to our [Card Minting Tutorial-1](/tutorial/tutorial-card-minting#get-card-information-by-bapp) and [Card Minting Tutorial-2](/tutorial/tutorial-card-minting#get-extra-card-information).\ 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). ### Get Card Information ## Get Card Information `GET` `https://api.klipwallet.com/v2/wallet/nft/:nft_id?cursor=` Returns detailed information of your Cards. #### Path Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ---------------------------------------------------------------------------------------- | | nft\_id\* | string | The ID of the NFT. NFT is the smart contract that implements the Card on the blockchain. | #### Query Parameters | Name | Type | Description | | ------ | ------ | ---------------------------------------------------------------------------------------------- | | isAll | bool | If TRUE, it returns the informatino of all your Cards. Not usable with the `cursor` parameter. | | cursor | string | The pointer from which to return the next 100 objects. Not usable with the `isAll` parameter. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "name": "conan", "symbol_img": "", "cards": [ { "created_at": 1580300503, "updated_at": 1580300503, "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263", "sender": "0x0000000000000000000000000000000000000000", "card_id": 18, "card_uri": "https://.../card_meta.json", "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f" }, ], "next_cursor": "mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL", } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve Card information. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} **Request Example** ``` curl "https://api.klipwallet.com/v2/wallet/nft/52?cursor=mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------- | | name | string | The name of the Card. | | symbol\_img | string | The URL address of the image to be used for the Card. | | cards | array | An array of `object`s containing the information of each Card. | | next\_cursor | string | The pointer after which the next request will retrieve the next 100 items if the number of Cards exceeds 100. | **Response Details for** `cards[i]` | Item | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------- | | created\_at | number | The time at which the Card was minted. | | updated\_at | number | The time at which the Card was updated. | | owner | string | The [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address of the Card owner. | | sender | string | The [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address of the sender. | | card\_id | number | The ID of the Card. | | card\_uri | string | The URL of the JSON file containing Cards' metadata. | | transaction\_hash | string | The hash of the smart contract transaction that minted the Card. | For more details, please refer to our [Card Minting Tutorial-1](/tutorial/tutorial-card-minting#get-card-information) and [Card Minting Tutorial-2](/tutorial/tutorial-card-minting#get-extra-card-information).\ 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). ### Delete Card ## Delete Card `DELETE` `https://api.klipwallet.com/v2/wallet/nft` Deletes a specified Card. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------ | ------------------------------------------------------- | | pin\* | string | The PIN Code that will be used to sign the transaction. | | card\_id\* | number | The ID of the Card. | | contract\_address\* | string | The address of the SCA that minted the Cards. | {% tabs %} {% tab title="200 " %} ``` { "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97" } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to delete Card. To check the result, send a request to **Get Card List** to see the complete list of tokens. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} {% hint style="warning" %} You cannot delete Cards that you sent to others. Deleting the Cards will not delete the Card image. {% endhint %} **Request Example** ``` curl -X DELETE "https://api.klipwallet.com/v2/wallet/nft" \ -d @./delete_info.json \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#delete-card).\ 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). ### Approve Escrow ## Approve Escrow `POST` `https://api.klipwallet.com/v2/escrow/approve` Enables the use of escrow for sending Cards. You have send a request to this API at least once to use escrow. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------ | ------------------------------------------------------- | | pin\* | string | The PIN Code that will be used to sign the transaction. | | contract\_address\* | string | The address of the SCA that minted the Card. | {% tabs %} {% tab title="200 " %} ``` { "fail_count": 0, "tx_hash": "string" } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` { "code": number, "err": "string" } ``` {% endtab %} {% endtabs %} **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/escrow/approve" \ -d @./approve_info.json \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#approve-escrow).\ 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). ### Get Escrow Approval Status ## Get Escrow Approval Status `GET` `https://api.klipwallet.com/v2/escrow/approve` Shows whether escrow is enabled or not. #### Query Parameters | Name | Type | Description | | --------------------------------------------------- | ------ | -------------------------------------------- | | contract\_address\* | string | The address of the SCA that minted the Card. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "approve": true } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` { "code": number, "err": "string" } ``` {% endtab %} {% endtabs %} **Request Example** ``` curl -X GET "https://api.klipwallet.com/v2/escrow/approve?contract_address=0xc94770007dda54cF92009BFF0dE90c06F603a09f" \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#get-approve-escrow).\ 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). ### Create Escrow ## Create Escrow `POST` `https://api.klipwallet.com/v2/escrow` Initiates escrow process by creating a link through which Klip user can receive the Card. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------ | -------------------------------------------------------------------------- | | pin\* | string | The PIN Code that will be used to sign the transaction. | | card\_ids\* | array | An array of `number`s containing Card IDs. It can hold up to 100 elements. | | contract\_address\* | string | The address of the SCA that minted the Card. | {% tabs %} {% tab title="200 " %} ``` { "claim_links": [ "https://klipwallet.com/?target=/claimCard/2/123?claimKey=1234567890123456789012345678901212345678901234567890123456789012" ], "fail_count": 0, "tx_hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97" } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` { "code": number, "err": "string" } ``` {% endtab %} {% endtabs %} {% hint style="warning" %} You can only create escrows for Cards you hold, and not the ones sent. The Cards that are in escrow can be listed using **Get Cards in Escrow**. {% endhint %} **Request Example** ``` curl -X POST "https://api.klipwallet.com/v2/escrow" \ -d @./escrow_info.json \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#create-escrow).\ 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). ### Get Cards in Escrow ## Get Cards in Escrow `GET` `https://api.klipwallet.com/v2/escrow` Returns a list of Cards in escrow. #### Query Parameters | Name | Type | Description | | --------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contract\_address\* | string | The address of the SCA that minted the Card. | | cursor | string | The pointer from which to return the next 100 objects. If you make a GET request for over 100 Cards, it will return 100 items in the result *and* a `next_cursor` value. To retrieve the rest of the Cards, set the `cursor` parameter with `next_cursor` and make another request to the same endpoint. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "cards": [ { "name": "conan", "symbol_img": "", "cards": [ { "created_at": 1580300503, "updated_at": 1580300503, "owner": "0xa3b7aa3a3c8a08bd22f77932368e2043e7ffe263", "sender": "0x0000000000000000000000000000000000000000", "card_id": 18, "card_uri": "https://.../card_meta.json", "transaction_hash": "0x8754f10f73468ea85e84d9e29c2a864fc574c1e57675bfc70b5459d82477a91f" }, ], "next_cursor": "mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL", } ] } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` ``` {% endtab %} {% endtabs %} {% hint style="info" %} For more details on `cursor`, please refer to [Pagination](/basics#basic-card-minting). {% endhint %} **Request Example** ``` curl -X GET "https://api.klipwallet.com/v2/escrow?contract_address=0xc94770007dda54cF92009BFF0dE90c06F603a09f" \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------- | | name | string | The name of the Card. | | symbol\_img | string | The URL address of the image to be used for the Card. | | cards | array | An array of `object`s containing the information of each Card. | | next\_cursor | string | The pointer after which the next request will retrieve the next 100 items if the number of Cards exceeds 100. | **Response Details for** `cards[i]` | Item | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------- | | created\_at | number | The time at which the Card was minted. | | updated\_at | number | The time at which the Card was updated. | | owner | string | The [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address of the Card owner. | | sender | string | The [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address of the sender. | | card\_id | number | The ID of the Card. | | card\_uri | string | The URL of the JSON file containing the Card's metadata. | | transaction\_hash | string | The hash of the smart contract transaction that minted the Card. | For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#get-escrow).\ 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). ### Cancel Escrow ## Cancel Escrow `DELETE` `https://api.klipwallet.com/v2/escrow` Cancels the escrow process for Cards that are in escrow. #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------ | ----------------------------------------------------------------------- | | pin\* | string | The PIN Code that will be used to sign the transaction. | | card\_ids\* | array | An array of `number`s containing Card IDs. Can hold up to 100 elements. | | contract\_address\* | string | The address of the SCA that minted the Card. | {% tabs %} {% tab title="200 " %} ``` { "fail_count": 0, "tx_hash": "string" } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to cancel escrow process. Use **Get Cards in Escrow** to get a list of Cards in escrow. ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500 " %} ``` { "code": number, "err": "string" } ``` {% endtab %} {% endtabs %} {% hint style="warning" %} This only works for Cards that are currently in escrow, and not Cards already sent. Cancelled Cards will return to the list. {% endhint %} **Request Example** ``` curl -X DELETE "https://api.klipwallet.com/v2/escrow" \ -d @./cancel_info.json \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#cancel-escrow).\ 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). ### Get Transaction Result ## Get Transaction Result `GET` `https://api.klipwallet.com/v2/wallet/receipt` Returns whether the transaction has been successfully recorded on blockchain. #### Query Parameters | Name | Type | Description | | ------------------------------------------ | ------ | ------------------------------------------------- | | tx\_hash\* | string | The hash of the transaction to make the query on. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------- | | Authorization\* | string | A JWT authentication token. | | Content-Type\* | string | application/json | {% tabs %} {% tab title="200 " %} ``` { "success": true } ``` {% endtab %} {% tab title="400 " %} {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="4700" %} ``` "no transaction receipt": The transaction hash doesn't exist. The transaction is either not processed or non-existant. ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} **Request Example** ``` curl -X GET "https://api.klipwallet.com/v2/wallet/receipt?tx_hash=0x880a45d3c482c7d794c2e7b7dbdc9e933a68f4a1f3d978d582ba9f9ebd1f9e72" \ -H "Authorization: ACCESS_TOKEN" -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ------- | ---- | ----------------------------------------------- | | success | bool | Returns whether the transaction was successful. | For more details, please refer to our [Card Minting Tutorial](/tutorial/tutorial-card-minting#get-receipt).\ 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). # App2App This page explains how to use App2App REST API to integrate Klip to your BApp. ## ※ Introduction There are three steps involved in using App2App API: **Prepare**, **Request**, and **Result**. {% hint style="warning" %} * Do not impersonate "GroundX" when using Klip API. * Only you are responsible for any consequences arising from using Klip API. GroundX is not responsible for its users or third parties. * Your account may be blocked without prior notice in case of any illegal or abnormal use of Klip API, such as creating unsually high traffic. {% endhint %} ### Prepare This step involves selecting the actions you would like to enable for your BApp. All the actions except for "Authentication" require sending a transaction to the Klaytn network. You therefore have to create a transaction object for these steps. The actions are as follows: * **Authentication** * **Sending KLAY** * **Sending Tokens** * **Sending Cards** * **Executing Smart Contract** #### Authentication This is a process to access a BApp user's Klip wallet. It is used to obtain a Klip user's [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) in a BApp. You should comply with the button style guide below when providing a button to enable this feature. #### Klip Log-In Button Guide * Klip App2App Button Design Guide ([pdf](https://media.klipwallet.com/a2a/klip_A2A_button_guide_ENG_v1.0.0.pdf), [figma](https://www.figma.com/file/sZmlfrwbJL2CNOErBD3vtV/A2A-Button-Design-Guide-v.1.0.0?node-id=0%3A1)) * Klip App2App Button Template [Download](https://media.klipwallet.com/a2a/klip_A2A_button_template_ENG_v1.0.0.zip) {% hint style="warning" %} When enabling this feature, you *must* include a way to disconnect Klip Account, and when doing so must immediately delete all collected EOA data. Nonadherence to this policy may result in the blocking of APIs without prior notice. {% endhint %} #### Sending KLAY This step involves sending KLAY from a BApp Member's Klip Wallet to a Klaytn account address (EOA). A transaction object will be created. #### Sending Tokens This step involves sending FTs (Fungible Tokens) from a BApp Member's Klip Wallet to a Klaytn account address (EOA). A transaction object will be created. #### Sending Cards This step involves sending NFTs (Non-Fungible Tokens) from a BApp Member's Klip Wallet to a Klaytn account address (EOA). A transaction object will be created. #### Executing Smart Contract This step involves executing a smart contract using a Klip account. A transaction object will be created. {% hint style="info" %} A successful Prepare API request will return a request key.\ Request key is used for the steps **Request** and **Result**, where the actions specified during the **Prepare** step will be requested for actual execution. {% endhint %} ### Request The actions specified in the previous **Prepare** step will be executed. All actions other than "Authentication", which is basically importing BApp Member's Klip Wallet Address (EOA) to the BApp, involve obtaining a signature for the transaction. The four actions "Sending Token", "Sending KLAY", "Sending Cards" and "Executing Smart Contract" require that transactions be sent to Klaytn. For this step, these transactions will be signed using Klaytn account keys and then be submitted to the Klaytn network. {% hint style="info" %} Authentication or signature will be requested on Klip via deep link. {% endhint %} For example, when a BApp Member “A” clicks on the button to send tokens to another Member “B”, your BApp will use the App2App API to first authenticate “A”'s Klip Wallet address (can be ommitted) and access “A”'s Klip Wallet. It will then submit a transaction to send tokens or Cards to “B”'s Klaytn account address. ### Result Finally in the **Result** step, you will receive the result or response of the request from the previous step. The API has two forms: whereas the **Prepare** and **Result** steps are RESTful APIs that send a request to the Klip Backend server, the **Request** step creates a deep link to use Klip. There is also a RESTful API request for retrieving Card information. ## ※ API Flow Diagram The basic flow of an App2App process looks like this: ![App2App Flow](/files/BoB4UhK0q61eUAFIjUik) Aside from the API request, retrieving Card Information shares the same flow as other REST API requests. It sends a request to the backend to retrieve information, without involving Klip. This flow is demonstrated below: ![App2App Information API Flow](/files/DY5KR3Hv9P8vynVfemqf) Deep link is implemented via URL Scheme on iOS, and intentURI on Android. URL Scheme is a link that looks like the one below. When a BApp user clicks on it, Klip, located in the More\[…] tab on KakaoTalk, will be launched. In the `request_key` field, use the request key obtained in the **Prepare** step. ``` kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb ``` IntentURI for Android looks like this: ``` intent://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb#Intent;scheme=kakaotalk;package=com.kakao.talk;end ``` ## ※ API Specification Below is the specification for App2App API. ## Prepare `POST` `https://a2a-api.klipwallet.com/v2/a2a/prepare` Prepares to process an App2App API request and issues a request key. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ---------------- | | Content-Type\* | string | application/json | #### Request Body | Name | Type | Description | | -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | bapp\* | object | Information of the BApp that will perform the App2App API request. You can set the name and the callback URL. callback only supports deep links. The `callback` field is optional. Please refer to the example below. | | type\* | string | The request type that the App2App will perform. Authentication is `auth`, Sending KLAY is `send_klay`, Sending Tokens is `send_token`, Sending Cards is `send_card`, and Executing Smart Contract is `execute_contract`. | | transaction | object | The data to be signed. It contains `to`, `amount`, `contract` and etc. and requires that the necessary fields for each request type be set. This field is required for all request types except `auth`. Please refer to the example below: | {% tabs %} {% tab title="200 " %} ```json { "request_key": "random key", "status": "prepared", "expiration_time": 12345 //unix timestamp } ``` {% endtab %} {% tab title="400 " %} {% endtab %} {% tab title="500 " %} {% endtab %} {% endtabs %} \*\* `bapp` Object Sample \*\* ```json { "bapp": { "name": "My BApp", "callback": { // all optional "success": "mybapp://.../success/...", "fail": "mybapp://.../fail/..." } } } ``` `name` is the name of the BApp displayed on the Klip user's screen during authentication or transaction signing. The `success` field under `callback` is a deep link to return to the BApp once user validation on Klip is successful. `fail` is a deep link to return to the BApp in case of failures. The `callback` object is optional. \*\* `transaction` Object Sample \*\* 1. type: `send_klay` ```json { "transaction": { "from": "0x8756...4321", // optional "to": "0x1234...5678", "amount": "100" } } ``` `to` is the Klaytn address of the KLAY recipient. `amount` is the amount of KLAY being sent. `from` is the Klip user's address. `from` is an optional field used to sort out unwanted requests through comparison with Klip users' actual address. 1. type: `send_token` ```json { "transaction": { "contract": "SCA", "from": "0x8756...4321", // optional "to": "0x1234...5678", "amount": "100", } } ``` `contract` is the smart contract address of the token. `to` is the Klaytn account address of the recipient. `amount` is the amount of tokens to receive. `amount` is converted automatically based on the decimals of the contract. For example, a KIP-7 contract (FT contract) has 18 decimals, so `amount` 1 would mean 10^18 tokens in its smallest denomination. `from` is the Klip user's address. `from` is an optional field used to sort out unwanted requests through comparison with Klip users' actual address. 1. type: `send_card` ```json { "transaction": { "contract": "0xA987...4321", "from": "0x8756...4321", // optional "to": "0x1234...5678", "card_id": "100", } } ``` `contract` is the smart contract address of the token. `to` is the Klaytn account address of the Card recipient. `card_id` is the identification number of the Card to be sent. `from` is the Klip user's address. `from` is an optional field used to sort out unwanted requests through comparison with Klip users' actual address. 1. type: `execute_contract` ```json { "transaction": { "from": "0x8756...4321", // optional "to": "0xA987...4321", // contract address "value": "1000000000000000000", // Unit= peb. 1 KLAY "abi": "...", "params": "..." } } ``` `to` is the address of the smart contract to be executed. `value` is the amoung of KLAY to be sent to that contract. The unit is peb. For example, 1 KLAY equals 1000000000000000000 pebs. `abi` is the function data of the contract to be executed. `params` refer to the parameter to be passed to the function. `from` is the Klip user's address. `from` is an optional field used to sort out unwanted requests through comparison with Klip user's actual address. More detailed explanations of `abi` and `params` can be found in the tutorial. {% hint style="info" %} Although `from` is optional, it is recommended to test that the Klip user is the actual intended user for the transaction. {% endhint %} **Request Example** ```bash curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \ -d '{"bapp": { "name" : "My BApp" }, "type": "execute_contract" }' \ -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ---------------- | ------ | ----------------------------------------------------------------------- | | request\_key | string | A unique identifier to specify requests for Request, Result APIs. | | status | string | The current status of the API request. The default value is `prepared`. | | expiration\_time | number | The expiration time of the request key in unix timestamp. | {% hint style="info" %} `status` can be one of the following: `prepared`, `requested`, `completed`, `canceled`, or `error`. `canceled` is set when the user intentionally cancels the App2App process. {% endhint %} Please refer to our [Tutorial](/tutorial/tutorial-a2a-rest-api) for more details.\ 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). ## Request `DEEP LINK` `kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=` There are currently two ways to request authentication or signature on Klip: deep link and QR code. Specific request methods differ for each development environment. Deep link uses `kakaotalk://` for iOS, and `intent://` for Android. And QR code uses a URL of the form: `https://`. Refer to the Request Example below for more details. #### Query Parameters | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | request\_key\* | string | The request key obtained in the **Prepare** step. `request_key` is used to specify each request. | {% tabs %} {% tab title="200 " %} {% endtab %} {% endtabs %} **Request Example** The `request_key` field is set with the value obtained in the **Prepare** step. #### iOS ``` kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb ``` #### Android ``` intent://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=9892...4aeb#Intent;scheme=kakaotalk;package=com.kakao.talk;end ``` #### PC or Other Devices (QR Code) QR code is generated as a URL as below. Users can process App2App requests by reading a QR code through Klip or the native camera app. ``` https://klipwallet.com/?target=/a2a?request_key=9892...4aeb ``` ![QR Code Sample](/files/13w25Ezp4HADv9Vi0s8V) {% hint style="info" %} Refer to the following open source projects on creating QR codes: * JavaScript : * Android : * iOS : {% endhint %} ## Result `GET` `https://a2a-api.klipwallet.com/v2/a2a/result?request_key=` Returns the result of a specified App2App API request. #### Query Parameters | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | request\_key\* | string | The request key obtained in the **Prepare** step. `request_key` is used to specify each request. | {% tabs %} {% tab title="200 " %} ```json { "request_key": "random key", "expiration_time": unix timestamp, "status": "requested" or "completed", "result": { "klaytn_address": string } } ``` {% endtab %} {% tab title="400 " %} {% endtab %} {% tab title="500 " %} {% endtab %} {% endtabs %} **Request Example** ```bash curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/result?request_key=9892...4aeb" \ -H "Content-Type: application/json" ``` **Response Details** 1. type: `auth` ```json { "request_key": "random key", "expiration_time": unix timestamp, "status": "completed", } ``` | Item | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------- | | request\_key | string | A unique identifier to specify requests for Request, Result APIs. | | expiration\_time | number | The expiration time of the request key in unix timestamp. | | status | string | The current status of the API request. If the request is successful, it returns `completed`. | {% hint style="info" %} `status` can be one of the following: `prepared`, `requested`, `completed`, `canceled`, or `error`. `canceled` is set when the user intentionally cancels the App2App process. {% endhint %} 1. type: Types other than `auth` ```json { "request_key": "random key", "expiration_time": unix timestamp, "status": "completed", "result": { "tx_hash": string, "status": "success" } } ``` | Item | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------- | | request\_key | string | A unique identifier to specify requests for Request, Result APIs. | | expiration\_time | number | The expiration time of the request key in unix timestamp. | | status | string | The current status of the API request. If the request is successful, it returns `completed`. | | result | object | Result of the signature request. Returns the transaction hash and transaction status. | {% hint style="info" %} If the `status` field in the `result` object reads `pending`, it means that the transaction is still being processed on Klaytn. Normally, you would be able to see the request processed after a few seconds. `success` means that the request was successful, and `fail` means that it failed. {% endhint %} Please refer to our [Tutorial](/tutorial/tutorial-a2a-rest-api) for more details.\ 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). ## Get Card Information `GET` `https://a2a-api.klipwallet.com/v2/a2a/cards?cursor=` Returns a list of Cards owned by a specified EOA, minted with a specified NFT contract. #### Query Parameters | Name | Type | Description | | ------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | sca\* | string | The address of the smart contract to make the query on. | | eoa\* | string | The address to specify which user EOA's Card information to retrieve. Normally the EOA obtained from a App2App `auth` request will be used. | | cursor | string | The pointer from which to return the next 100 objects. | {% tabs %} {% tab title="200 " %} ```json { "name": "Klip", "symbol_img": "image url", "cards": [ { "created_at": 1580176787, "created_at_format": "format", "updated_at": 1580176787, "updated_at_format": "format", "owner": "0x2412b300750f505fb2e68ddf0cd45e9d95f5378d", "sender": "0x0000000000000000000000000000000000000000", "sender_kakao_id": "kakao_id" "card_id": 19, "card_uri": "metadata uri", "transaction_hash": "0x293a2e53ecf238109908e65a2b7ff4aad0919ce3ce54af08d6fc4323f28e935d" }, ], "next_cursor": string } ``` {% endtab %} {% tab title="400 " %} {% endtab %} {% tab title="500 " %} {% endtab %} {% endtabs %} **Request Example** ```bash curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/cards?sca=0x1234...&eoa=0x9876...&cursor=mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" \ -H "Content-Type: application/json" ``` **Response Details** | Item | Type | Description | | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | name | string | The name of the contract. | | symbol\_img | string | The URL of the contract symbol image. | | cards | array | The array of the `object`s containing Card information. | | next\_cursor | string | The pointer for the next request, after which the result will be returned. It is returned if the array contains over 100 elements. | **Response Details for** `cards[i]` | Item | Type | Description | | ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | | created\_at | number | The time at which the Card was minted. | | updated\_at | number | The time at which the Card was updated. | | owner | string | The address of this [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas). | | sender | string | The [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address of the Card sender. | | card\_id | number | The ID of the Card. | | card\_uri | string | The URL containing the JSON file of the Card's metadata. | | transaction\_hash | string | The hash of the smart contract transaction that minted the Card. | Please refer to our [Tutorial](/tutorial/tutorial-a2a-rest-api) for more details.\ 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). # App2App SDK This page introduces Klip's SDKs. App2App SDK allows you to easily integrate Klip to your applications. | Item | Description | Notes | | --------------------------------------- | ----------------------------- | ------------ | | [Javascript SDK](/a2a-sdk/a2a-sdk-js) | APIs for web environments | Javascript | | [Android SDK](/a2a-sdk/a2a-sdk-android) | APIs for Android environments | Java | | [iOS SDK](/a2a-sdk/a2a-sdk-ios) | APIs for iOS environments | Swift | | [Download](/a2a-sdk/a2a-sdk-download) | Download links for SDKs | Sample & SDK | \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). # JavaScript SDK This page explains how to use App2App JavaScript SDK to use Klip with your BApp. ## Prerequisites * (When using npm) node 10 or higher ## Environment Setup Klip JavaScript SDK doesn't require a separate registration process and works in any environments where HTTP communication is possible. But since user's consent is received using Klip located in the More\[…] tab in the mobile app KakaoTalk, you need to have KakaoTalk installed to make the requests. ### When using npm Install using the `npm install klip-sdk` or `yarn add klip-sdk` command. It should be imported as an ES module as shown below: ```javascript import { prepare, request, getResult, getCardList } from 'klip-sdk' ``` ### When downloading the file directly Download Klip JavaScript SDK in the [Download](/a2a-sdk/a2a-sdk-download) tab. Place the file in the repository and insert a script tag in the HTML file as shown below: ```html ``` Access each method using the klipSDK variable declared in the global namespace. ```javascript klipSDK.prepare(...) klipSDK.request(...) klipSDK.getResult(...) klipSDK.getCardList(...) ``` ## API ### Overview App2App API requests are made in the order: `prepare`, `request`, and `getResult`. * `prepare` is the step in which requests (from of a total of five) are defined * `request` is the step in which the function is called and the signing takes place on Klip * `getResult` is the step in which the result is returned from the function call In addition, `getCardList` is a function for the convenience of BApp developers that returns a list of NFTs of Klip users.\ If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).
### prepare Prepares a App2App API request and obtains a request key. ### prepare.auth Obtains user information. **Parameters** | Name | Type | Description | | ----------- | ------ | ---------------------------------------------------------------------------- | | bappName | string | The name of the BApp displayed to users | | successLink | string | (optional) The return link after obtaining user consent | | failLink | string | (optional) The return link in case of a problem while obtaining user consent | **Example** ```javascript const bappName = 'my app' const successLink = 'myApp://...' const failLink = 'myApp://...' const res = await prepare.auth({ bappName, successLink, failLink }) if (res.err) { // Handle error } else if (res.request_key) { // Store request_key } ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### prepare.sendKLAY A request to send a user's KLAY to a certain address. **Parameters** | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------- | | bappName | string | The name of the BApp displayed to users | | to | string | The address of the recipient | | amount | string | The amount of KLAY to send (Unit: KLAY, up to the 6th decimal place) | | from | string | (optional) To check if the Klip account address matches with the `from` address | | successLink | string | (optional) The return link after obtaining user consent | | failLink | string | (optional) The return link in case of a problem while obtaining user consent | **Example** ```javascript const bappName = 'my app' const from = '0xB21F0285d27beb2373EC...' const to = '0xD8b1dC332...' const amount = '13.2' const successLink = 'myApp://...' const failLink = 'myApp://...' const res = await prepare.sendKLAY({ bappName, from, to, amount, successLink, failLink }) if (res.err) { // Handle error } else if (res.request_key) { // Store request_key } ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### prepare.sendToken A request to send a user's tokens to a certain address. **Parameters** | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------- | | bappName | string | The name of the BApp displayed to users | | to | string | The address of the recipient | | amount | string | The amount of tokens to send (Unit: The default unit of the token, up to the 6th decimal place) | | contract | string | The address of the token contract | | from | string | (optional) To check if the Klip account address matches with the `from` address | | successLink | string | (optional) The return link after obtaining user consent | | failLink | string | (optional) The return link in case of a problem while obtaining user consent | **Example** ```javascript const bappName = 'my app' const from = '0xB21F0285d27beb2373EC...' const to = '0xD8b1dC332...' const amount = '10.123' const contract = '0x813FB7677BbBAA...' const successLink = 'myApp://...' const failLink = 'myApp://...' const res = await prepare.sendToken({ bappName, from, to, amount, contract, successLink, failLink }) if (res.err) { // Handle error } else if (res.request_key) { // Store request_key } ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### prepare.sendCard A request to send a user's NFT to a certain address. **Parameters** | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------- | | bappName | string | The name of the BApp displayed to users | | to | string | The address of the recipient | | id | string | ID of the NFT | | contract | string | The address of the NFT contract | | from | string | (optional) To check if the Klip account address matches with the `from` address | | successLink | string | (optional) The return link after obtaining user consent | | failLink | string | (optional) The return link in case of a problem while obtaining user consent | **Example** ```javascript const res = await prepare.sendCard({ bappName, from, to, id, contract, successLink, failLink }) if (res.err) { setErrorMsg(res.err) } else { setRequestKey(res.request_key) } ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### prepare.executeContract A request for the user to execute the functino of a certain contract. **Parameters** | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------- | | bappName | string | The name of the BApp displayed to users | | to | string | The address of the contract | | value | string | Amount of KLAY to be sent during contract execution (unit: peb) | | abi | string | ABI of the function to execute | | params | string | List of parameters of the function to execute | | from | string | (optional) To check if the Klip account address matches with the `from` address | | successLink | string | (optional) The return link after obtaining user consent | | failLink | string | (optional) The return link in case of a problem while obtaining user consent | **Example** ```javascript const bappName = 'my app' const from = '0xB21F0285d27beb2373EC...' const to = '0xD8b1dC332...' const value = '800000000' const abi = "{\"constant\":false,\"inputs\":[{\"name\":\"tokenId\",\"type\":\"uint256\"}],\"name\":\"buyCard\",\"outputs\":[],\"payable\":true,\"stateMutability\":\"payable\",\"type\":\"function\"}" const params = "[\"2829\"]" const successLink = 'myApp://...' const failLink = 'myApp://...' const res = await prepare.executeContract({ bappName, from, to, value, abi, params, successLink, failLink }) if (res.err) { // Handle error } else if (res.request_key) { // Store request_key } ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Klip request Request authentification or signature using deep link. If the device doesn't have KakaoTalk installed, or the version of the installed KakaoTalk doesn't support Klip, it redirects automatically to the download page on Google Play. You need to pass the request key obtained during the **prepare** step as a parameter. To implement the request step using QR code, please refer to [QR Code Tutorial](/rest-api/rest-api-a2a#request-qr-code). **Parameters** | Name | Type | Description | | ------------------------ | -------- | ----------------------------------------------------------------------- | | requestKey | String | Request number | | onUnsupportedEnvironment | Function | (optional) The callback function to execute in a non-mobile environment | **Example** ```javascript request('b37f873d-32ce-4d5d-b72e-08d528e7fb8e', () => alert('Please execute in a mobile environment')) ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### getResult Returns the response of an App2App API request. **Parameters** | Name | Type | Description | | ---------- | ------ | -------------- | | requestKey | String | Request number | **Example** ```javascript getResult('b37f873d-32ce-4d5d-b72e-08d528e7fb8e') ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### getCardList Returns a list of a user's Cards (NFTs). You have to know the contract address of the NFTs that you want to return. It must be a contract supported on Klip. **Parameters** | Name | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | | contract | String | The contract address of the Cards to retrieve | | eoa | String | Address of the user to retrieve | | cursor | String | (optional) The pointer after which the next request will retrieve the next 100 items if the number of Cards exceeds 100 | **Example** ```javascript const contract = '0xB21F0285d27beb2373EC...' const eoa = '0xD8b1dC332...' const cursor = '' getCardList({ contract, eoa, cursor }) ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ## Error Code | Http Status | Error Code | Description | | ----------- | ---------- | ------------------------------------------- | | - | - | Same as [Klip REST API Error Code](/basics) | \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). # Android SDK This page explains how to use App2App Android SDK to use Klip on your BApp. ## Prerequisites * API 16: Android 4.1 (Jelly Bean) or higer * Java 8 or higher * Android Studio 3.0.0 or higher * Android Permission: Internet Permission ## Environment Setup Klip JavaScript SDK doesn't require a separate registration process and works in any environments where HTTP communication is possible. But since user's consent is received using Klip located in the More\[…] tab in the mobile app KakaoTalk, you need to have KakaoTalk installed to make the requests. You can find a guide for executing Klip Android SDK Sample App in `README.md`. ### 1. Download Klip SDK Download Klip Android SDK in [Download](/a2a-sdk/a2a-sdk-download). ### 2. Add Klip SDK Library #### Option 1. Build Klip SDK and add to your project 1. Run **Terminal** at the location of downloaded Klip SDK project 2. Run the command `./gradlew :sdk:build` and build Klip SDK project (When building is complete, an AAR file is created at /sdk/build/outputs/aar/) 3. Create a **libs** directory in the project 4. Copy the built AAR file to the project's **libs** directory 5. Add directory reference and dependency to the project's `build.gradle` ``` repositories { flatDir { dirs 'libs' } } dependencies { // Klip SDK implementation 'com.klipwallet.app2app:klip-a2a-sdk-android_release_v2.0.0:2.0.0@aar' } ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\().
#### Option 2. Import Klip SDK source code and add to your project 1. Run the project in **Android Studio** 2. **Android Studio > File > New > Import Module** 3. Select the **sdk** directory in the Klip SDK project downloaded in the **Source Directory**, and click **Next** 4. Copy `gradle.properties` in the Klip SDK project to your project 5. Add the dependency setting in `build.gradle` of your project ``` dependencies { // Klip SDK implementation project(path: ':sdk') } ``` Once the Klip SDK source is copied to your project, you can modify the library code yourself. This may not be a suitable option if you want to maintain single version library code. In this case, add the compiled AAR file as directed in **Option 1**. ### 3. Add Permission In order to enable HTTP communication on Klip SDK, add `android.permission.INTERNET` in the `AndroidManifest.xml` file as shown below: ```xml ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ## API ### Overview App2App API requests are made in the order: `prepare`, `request`, and `getResult`. * `prepare` is the step in which requests (from of a total of five) are defined * `request` is the step in which the function is called and the signing takes place on Klip * `getResult` is the step in which the result is returned from the function call In addition, `getCardList` is a function provided for the convenience of BApp developers that returns a list of NFTs of a Klip user.\ If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).
### Klip.getInstance Creates an instance to use Klip SDK. **Parameters** | Name | Type | Description | | ------- | --------- | ------------------- | | context | `Context` | Application context | **Return Value** | Type | Description | | ------ | ------------- | | `Klip` | Klip instance | **Example** ```java public class SampleActivity extends AppCompatActivity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); Klip klip = Klip.getInstance(this); } } ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Klip.prepare Prepares to process an App2App API request and issues a request key. **Request Objects** * Connecting Klip(=authentication) `AuthRequest` * Sending KLAY `KlayTxRequest` * Sending Token `TokenTxRequest` * Sending Card `CardTxRequest` * Executing Contract `ContractTxRequest` **Parameters** | Name | Type | Description | | -------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | request | `KlipRequest` | Requested information depending on request type | | bappInfo | `BAppInfo` | Information of the requested BApp | | callback | `KlipCallback` | The callback function to obtain the response. If it's successful, it returns `KlipTxResponse`, and if not it returns `KlipErrorResponse`. | **Throws** | Type | Description | | ---------------------- | ---------------------------------------------------------- | | `KlipRequestException` | Request exception (e.g. a required parameter was ommitted) | Requesting consent to Klip users will return the data entered in `request` and `bappInfo`. The request key returned in the response serves as a key when requesting transactions to users, and is used with **KlipSDK.shared.getResult** and **KlipSDK.shared.request**. **Example 1. Obtaining User Information** ```java // Obtaining user information AuthRequest req = new AuthRequest(); // BApp information BAppInfo bappInfo = new BAppInfo("BApp Name"); // Response result Callback KlipCallback callback = new KlipCallback() { @Override public void onSuccess(final KlipTxResponse res) {} @Override public void onFail(final KlipErrorResponse res) {} } klip.prepare(req, bappInfo, callback); ``` **Example 2. Sending KLAY** ```java // Transaction request for sending KLAY KlayTxRequest req = new KlayTxRequest.Builder() .to("0x..receiver address..") .amount("10") .build(); klip.prepare(req, bappInfo, callback); // bappInfo, callback (example 1 참고) ``` **Example 3. Sending Tokens** ```java // Transaction request for sending tokens TokenTxRequest req = new TokenTxRequest.Builder() .contract("0x..token contract address..") .to("0x..receiver address..") .amount("10") .build(); klip.prepare(req, bappInfo, callback); // bappInfo, callback (example 1 참고) ``` **Example 4. Sending Card** ```java // Transaction request for sending Card CardTxRequest req = new CardTxRequest.Builder() .contract("0x..card contract address..") .to("0x..receiver address..") .cardId("9") .build(); klip.prepare(req, bappInfo, callback); // bappInfo, callback (example 1 참고) ``` **Example 5. Executing Contract** ```java // Transaction request for executing contract ContractTxRequest req = new ContractTxRequest.Builder() .to("0x..contract address..") .value("10") .abi("{..contract abi..}") .params(new ArrayList(){ // contract parameters }) .build(); klip.prepare(req, bappInfo, callback); // bappInfo, callback (refer to example 1) ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Klip.request Requests authentification or signature using deep link. If the device doesn't have KakaoTalk installed, or the version of the installed KakaoTalk doesn't support Klip, it redirects automatically to the download page on Google Play. To implement the request step using QR code, please refer to [QR Code Tutorial](/rest-api/rest-api-a2a#request-qr-code). **Parameters** | Name | Type | Description | | ---------- | ------ | ------------------------------------------ | | requestKey | String | Request number (Obtained from Klip Server) | **Throws** | Type | Description | | ---------------------- | ---------------------------------------------------------- | | `KlipRequestException` | Request exception (e.g. a required parameter was ommitted) | **Example** ```java klip.request(requestKey); ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Klip.getResult Returns the result of an App2App API request. **Parameters** | Name | Type | Description | | ---------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | requestKey | String | Request number (Obtained from Klip Server) | | callback | `KlipCallback` | The callback function to obtain the response. If it's successful, it returns `KlipTxResponse`, and if not it returns `KlipErrorResponse`. | **Throws** | Type | Description | | ---------------------- | ---------------------------------------------------------- | | `KlipRequestException` | Request exception (e.g. a required parameter was ommitted) | **Example** ```java KlipCallback callback = new KlipCallback() { @Override public void onSuccess(final KlipTxResponse res) {} @Override public void onFail(final KlipErrorResponse res) {} } Klip klip = Klip.getInstance(); klip.getResult(requestKey, callback) ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Klip.getCardList Returns a list of certain Cards of a user. **Parameters** | Name | Type | Description | | ----------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | cardAddress | String | Address of the Card to retrieve | | userAddress | String | Address of the user to retrieve | | cursor | String | (optional) The pointer after which the next request will retrieve the next 100 items if the number of Cards exceeds 100. | | callback | `KlipCallback` | The callback function to return the response. If it'successful, it returns `CardListResponse`, and if not it returns `KlipErrorResponse`. | **Throws** | Type | Description | | ---------------------- | -------------------------------------------------------------- | | `KlipRequestException` | Request exception (e.g. when a required parameter is ommitted) | **Example** ```java KlipCallback callback = new KlipCallback() { @Override public void onSuccess(final KlipCardListResponse res) {} @Override public void onFail(final KlipErrorResponse res) {} } Klip klip = Klip.getInstance(); klip.getCardList("0x..card address..", "0x..user address..", null, callback); ``` \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ## Error Code You can see the error code via `getErrorCode()` in `KlipErrorResponse`, which is the fail response of `KlipCallback`. | Http Status | Error Code | Description | | ----------- | ---------- | -------------------------------------------------------- | | - | - | Same as [Klip REST API Error Code](/basics) | | 500 | 10 | Error in Klip SDK (e.g. HTTP c connection failure) | | 500 | 21 | Error in Klip SDK (Klip REST API unsupported error code) | | 500 | 22 | Error in Klip SDK (Klip protocol error) | \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). # iOS SDK This page explains how to use App2App iOS SDK to use Klip on your BApp. ## Prerequisites * iOS 12.0 or higher * Swift 5.0 or higher * Xcode 13.4 or higher ## Environment Setup Klip iOS SDK doesn't require a separate registration process. It works in any environment where HTTP communication is available. Still, users must have KakaoTalk installed to make the requests because the user's consent is received using the Klip application or Klip located in the More\[…] tab in the mobile app KakaoTalk. ### 1. Download Klip SDK Download Klip iOS SDK in [Download](/a2a-sdk/a2a-sdk-download) ### 2. Add Klip SDK Framework #### Import Klip SDK Framework and add to your project 1. Execute your project with **Xcode** 2. Go to **Xcode** > **Project's TARGETS** > **General Tab** > **Frameworks, Libraries, and Embedded Content Tab** and click on the **+** button 3. Select the **sdk** directory of Klip SDK project downloaded in **Source Directory** and click **Next** 4. Check if the SDK is imported to Frameworks in the Project Navigator and build. ```diff ! Only `KlipLib.xcframework` must be included to register on Apple App Store. Please ensure that `KlipLib-simulator.xcframework` is used for development purposes only. ``` Once the Klip SDK source is copied to your project, you can modify the library code yourself. ### 3. Set Info.plist #### Register Allowlist for Apps To execute applications like KakaoTalk using iOS SDK with iOS 9.0 or higher, you have to register a custom scheme in the Info.plist file. Add an array type key LSApplicationQueriesSchemes in \[Info] > \[Custom iOS Target Properties], and add 'klip' and 'itms-apps' as 'Item' of that key. ```xml LSApplicationQueriesSchemes klip kakaotalk itms-apps ``` ### 4. Set Source Import #### v2.1.0 or above ```swift import KlipLib ``` #### v2.1.0 below ```swift import KlipSDK ``` ## API ### Overview App2App API requests are made in the order: `prepare`, `request`, and `getResult`. * `prepare` is the step in which requests (from of a total of five) are defined * `request` is the step in which the function is called and the signing takes place on Klip * `getResult` is the step in which the result is returned from the function call In addition, `getCardList` is a function provided for the convenience of BApp developers that returns a list of NFTs of a Klip user.\ If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).
### KlipSDK.shared Creates an instance to use Klip SDK. **Return Value** | Type | Description | | ------ | ------------- | | `Klip` | Klip instance | **Example** ```swift let klip = KlipSDK.shared ``` ### KlipSDK.shared.prepare `KlipSDK.shared.prepare(request: KlipRequest, bappInfo: BAppInfo, completion: @escaping(KlipCallback) -> Void)`\ \ Prepares to process an App2App API request and issues a request key. **Request Objects** * Connecting Klip(=authentication) `AuthRequest` * Sending KLAY `KlayTxRequest` * Sending Token `TokenTxRequest` * Sending Card `CardTxRequest` * Executing Contract `ContractTxRequest` **Parameters** | Name | Type | Description | | -------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | request | `KlipRequest` | Requested information depending on request type | | bappInfo | `BAppInfo` | Information of the requested BApp | | callback | `KlipCallback` | The callback function to obtain the response. If it's successful, it returns `KlipTxResponse`, and if not it returns `KlipErrorResponse`. | Requesting consent to Klip users will return the data entered in `request` and `bappInfo`. The request key returned in the response serves as a key when requesting transactions to users, and is used with **KlipSDK.shared.getResult** and **KlipSDK.shared.request**. **Example 1. Obtaining User Information** ```swift // Transaction request for obtaining user information let req: AuthRequest = AuthRequest(); // BApp Information let bappInfo: BAppInfo = BAppInfo(name : "BApp Name"); // Response Callback KlipSDK.shared.prepare(request: req, bappInfo: bappInfo) { result in switch result { case .success(let response): case .failure(let error): } } ``` **Example 2. Sending KLAY** ```swift // Transaction request for sending KLAY let req: KlayTxRequest = KlayTxRequest(to: "0x..receiver address..", amount: "10") KlipSDK.shared.prepare(request: req, bappInfo: bappInfo) { result in switch result { case .success(let response): case .failure(let error): } } ``` **Example 3. Sending Token** ```swift // Transaction request for sending tokens let req: TokenTxRequest = TokenTxRequest(to: "0x..receiver address..", amount: "10", contract: "0x..token contract address..") KlipSDK.shared.prepare(request: req, bappInfo: bappInfo) { result in switch result { case .success(let response): case .failure(let error): } } ``` **Example 4. Sending Card** ```swift // Transaction request for for sending Card let req: CardTxRequest = CardTxRequest(to: "0x..receiver address..", contract: "0x..card contract address..", cardId: "9") KlipSDK.shared.prepare(request: req, bappInfo: bappInfo) { result in switch result { case .success(let response): case .failure(let error): } } ``` **Example 5. Execute Contract** ```swift // Transaction request for sending contract let req: ContractTxRequest = ContractTxRequest(to: "0x..contract address..", value: "10", abi: "{...}", params: "[{...}]") KlipSDK.shared.prepare(request: req, bappInfo: bappInfo) { result in switch result { case .success(let response): case .failure(let error): } } ``` ### KlipSDK.shared.request `KlipSDK.shared.request(requestKey: String), isKlipAppCall: Bool = false) -> Void`\ Requests authentification or signature using deep link. Under the below circumstances, it would redirect automatically to the download page of Klip or KakaoTalk on the Apple AppStore. * If the device doesn't have Klip or KakaoTalk installed * The version of the installed KakaoTalk doesn't support Klip * To implement the request step using QR code, please refer to [QR Code Tutorial](/rest-api/rest-api-a2a#request-qr-code). **Parameters** | Name | Type | Description | | ------------- | ------ | ----------------------------------------------------- | | requestKey | String | Request Number (Obtained from Klip Server) | | isKlipAppCall | Bool | If the Klip app was called first, then it should true | **Example** ```swift KlipSDK.shared.request(requestKey: "request key...", isKlipAppCall: true) ``` ### KlipSDK.shared.getResult `KlipSDK.shared.getResult(requestKey: String, completion: @escaping(KlipCallback) -> Void)`\ \ Checks the result of an App2App API request **Parameters** | Name | Type | Description | | ---------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | requestKey | String | Request Number (Obtained from Klip Server) | | callback | `KlipCallback` | The callback function to obtain the response. If it's successful, it returns `KlipTxResponse`, and if not it returns `KlipErrorResponse`. | **Example** ```swift KlipSDK.shared.getResult(requestKey: "request key...") { result in switch result { case .success(let response): case .failure(let error): } } ``` ### KlipSDK.shared.getCardList `KlipSDK.shared.getCardList(cardAddress: String, userAddress: String, cursor: String?, completion: @escaping(KlipCallback) -> Void)`\ \ Returns a list of certain Cards of a user **Parameters** | Name | Type | Description | | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | cardAddress | String | The address of the Card to return | | userAddress | String | The address of the user to return | | cursor | String | (optional) The pointer after which the next request will retrieve the next 100 items if the number of Cards exceeds 100. | | callback | `KlipCallback` | The callback function to obtain the response. If it's successful, it returns `CardListResponse`, and if not it returns `KlipErrorResponse`. | **Example** ```swift KlipSDK.shared.getCardList(cardAddress: "0x..card address..", userAddress: "0x..user address..", cursor: nil) { result in switch result { case .success(let response): case .failure(let error): } } ``` ## Error Code | Http Status | Error Code | Description | | ----------- | ---------- | -------------------------------------------------------- | | - | - | Same as [Klip REST API Error Code](/basics) | | 500 | 10 | Error in Klip SDK (ex. HTTP c connection failure) | | 500 | 21 | Error in Klip SDK (Klip REST API unsupported error code) | | 500 | 22 | Error in Klip SDK (Klip protocol error) | # Download This page provides download links for App2App SDKs. You can download JavaScript via npm. Android and iOS provide a ZIP file. ## JavaScript | Program | Version | Release Date | | -------------------------------------------------------------------------- | ------- | ------------ | | [npm package](https://www.npmjs.com/package/klip-sdk) | v2.0.1 | 2020.10.26 | | [klipSDK-2.0.1.min.js](https://dl.klipwallet.com/sdk/klipSDK-2.0.1.min.js) | v2.0.1 | 2020.10.26 | | [Sample App](https://dl.klipwallet.com/sdk/js/example_vanilla.zip) | v2.0.1 | 2020.10.26 | ## Android | Program | Version | Release Date | Notes | | -------------------------------------------------------------------------------------------------- | ------- | ------------ | -------------------------------------------------------------------------------------- | | [Android SDK Full Source & Samples](https://dl.klipwallet.com/sdk/klip-a2a-sdk-android-v2.0.1.zip) | v2.0.1 | 2021.07.07 | [Reference](https://dl.klipwallet.com/sdk/docs/klip-a2a-sdk-android-v2.0.1/index.html) | ## iOS | Program | Version | Release Date | Notes | | ------------------------------------------------------------------------------------------ | ------- | ------------ | ---------------------------------------------------------------------------------- | | [iOS SDK Full Source & Samples](https://dl.klipwallet.com/sdk/klip-a2a-sdk-ios-v2.0.1.zip) | v2.0.1 | 2021.07.07 | [Reference](https://dl.klipwallet.com/sdk/docs/klip-a2a-sdk-ios-v2.0.1/index.html) | {% hint style="warning" %} * Do not impersonate GroundX when using Klip SDK. * Only you are responsible for any consequences arising from using Klip SDK. GroundX is not responsible for its users or third parties. * Do not sell Klip SDK for commercial use. * Your account may be blocked without prior notice in case of any illegal or abnormal use of Klip SDK, such as creating unsually high traffic. {% endhint %} ## Open Source Software Notice * Android SDK: [Notice on Open Source Library](https://dl.klipwallet.com/sdk/docs/klip-a2a-sdk-android-v2.0.1/NOTICE.html) * iOS SDK: [Notice on Open Source Library](https://dl.klipwallet.com/sdk/docs/klip-a2a-sdk-ios-v2.0.1/NOTICE.html) \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). # Tutorial This page introduces Klip API tutorials. Klip API Tutorials consist of Card Minting REST API and App2App REST API. ## Card Minting API Card Minting API is a REST API for implementing the functions to mint, send, delete and manage Klip Cards (NFT). The Card Minting API tutorial provides detailed instructions to help you sign in, manage accounts, and mint, send and manage Cards. ## App2App API App2App API is an API for implementing the function to link your "BApp" with "Klip". App2App API tutorial explains this process including configuration of the environment to allow BApp to access Klip, authentication (`auth`) where a BApp sends Klip a request, sending KLAY (`send_klay`), sending token (`send_token`), sending Cards (`send_card`), and executing contracts (`execute_contract`). The App2App API tutorial deals with REST APIs. | Item | Description | Notes | | --------------------------------------------------- | --------------------------------------------------------------------------------------- | ----- | | [Card Minting API](/tutorial/tutorial-card-minting) | How to mint, send and manage Klip Cards | | | [App2App API](/tutorial/tutorial-a2a-rest-api) | How to link BApp with Klip to send Klip Cards, tokens, KLAY and initate smart contracts | | 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). # 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](https://partners.klipwallet.com). For more details on membership, please visit [Klip Partners](https://partners.klipwallet.com).\ 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). ### 1-2. Sign In Pass your ID(`email`) and password to [Klip Partners](https://partners.klipwallet.com) via [Sign In](/rest-api/rest-api-card-minting#sign-in). * `password` is a 64-digit string and a hash([SHA256](https://wikipedia.org/wiki/SHA)) of the password. * Password is a string consisting of 8-16 alphabet characters, numbers, and special characters. ```bash //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: ```bash { "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](https://partners.klipwallet.com), an [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address and a smart contract is created on the [Klaytn](https://docs.klaytn.com/klaytn) blockchain from which you can mint Cards. `klaytn_address` is your [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address created in the [Klaytn](https://docs.klaytn.com/klaytn) blockchain, and `contract_address` is the ([SCA](https://docs.klaytn.com/klaytn/design/accounts#smart-contract-accounts-scas)) from which you can mint Cards. {% hint style="info" %} 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. {% endhint %} If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="406" %} ``` "not found user info in db": Account information not found. ``` {% endtab %} {% tab title="426" %} ``` "not yet approved": Membership has not yet been approved. ``` {% endtab %} {% tab title="4004" %} ``` "invalid password": Wrong password. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to sign in. ``` {% endtab %} {% endtabs %} ### \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ## 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](https://partners.klipwallet.com) via [Upload Image](/rest-api/rest-api-card-minting#upload-image) and request image upload. To mint Cards using [Mint Card To user](/rest-api/rest-api-card-minting#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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to upload image. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 2-2. Mint Card to EOA Pass the `mint_info.json` file, and the `access_token` you received when signing in to [Klip Partners](https://partners.klipwallet.com) via [Mint Card To user](/rest-api/rest-api-card-minting#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](https://wikipedia.org/wiki/SHA)) 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 [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas)s 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](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) 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 `object`s 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](https://scope.klaytn.com/) to confirm that the transaction has been executed successfully. If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to mint Card. As some of the Cards may have been minted, send a request to **Get Card List** to see the complete list of tokens. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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](https://partners.klipwallet.com) via [Mint Card To Klip Member](/rest-api/rest-api-card-minting#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](https://wikipedia.org/wiki/SHA)) 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 `object`s 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. {% hint style="info" %} 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. {% endhint %} If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to mint Card. As some of the Cards may have been minted, send a request to **Get Card List** to see the complete list of tokens. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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](https://partners.klipwallet.com) via [Upload NFT Resource](/rest-api/rest-api-card-minting#upload-nftresource) 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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to upload file. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ## 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](/rest-api/rest-api-card-minting#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 `cards`refers 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](/rest-api/rest-api-card-minting#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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve Card information by BApp. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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](https://partners.klipwallet.com) via [Get Card Information](/rest-api/rest-api-card-minting#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 `cards`refers 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](/rest-api/rest-api-card-minting#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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve Card Information. ``` {% endtab %} {% endtabs %} Pass `cards.next_cursor` and the `access_token` that you received when signing in to [Klip Partners](https://partners.klipwallet.com) via [Get Card Information](/rest-api/rest-api-card-minting#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": "", } ``` {% hint style="info" %} The details of the `cards` array is the same as that of `bapps[i].cards` from [Get Card Information by BApp](/rest-api/rest-api-card-minting#get-card-information-by-bapp). {% endhint %} If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve Card information. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 3-3. Retrieving the remaining Cards when total Card number exceeds 100 [Get Card Information By BApp](/rest-api/rest-api-card-minting#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](/rest-api/rest-api-card-minting#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](/rest-api/rest-api-card-minting#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](/rest-api/rest-api-card-minting#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](/rest-api/rest-api-card-minting#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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve a list of Cards by BApp. ``` {% endtab %} {% endtabs %} 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](/rest-api/rest-api-card-minting#get-card-information). Pass `gKvkL1lPYv1P93dpE...` and the `access_token` that you received while signing up to [Klip Partners](https://partners.klipwallet.com) via [Get Card Information](/rest-api/rest-api-card-minting#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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve Card Information. ``` {% endtab %} {% endtabs %} 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](/rest-api/rest-api-card-minting#get-card-information). Pass `Xrzed2Ot9LeEor...` and the `access_token` that you received when signing in to [Klip Partners](https://partners.klipwallet.com) via [Get Card Information](/rest-api/rest-api-card-minting#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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve Card information. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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]\( via [Get Card Information](/rest-api/rest-api-card-minting#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`). {% hint style="info" %} The details of the `cards` array is the same as that of `bapps[i].cards` in [Get Card Information by BApp](/rest-api/rest-api-card-minting#get-card-information-by-bapp). {% endhint %} If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to retrieve Card Information. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ## 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](https://partners.klipwallet.com) via [Send Card To user](/rest-api/rest-api-card-minting#send-card-to-user), and send a request to send the Card held by the current [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address to another [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) 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](https://ko.docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) address. * `pin` is a 64-digit string and hash([SHA256](https://wikipedia.org/wiki/SHA)) 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](https://ko.docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) 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. {% hint style="info" %} 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. {% endhint %} If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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](https://partners.klipwallet.com) via [Send Card To Klip Member](/rest-api/rest-api-card-minting#send-card-to-klip-member) and send a request to send the Card currently held by the [EOA](https://docs.klaytn.com/klaytn/design/accounts#externally-owned-accounts-eoas) 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](https://wikipedia.org/wiki/SHA)) 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. {% hint style="info" %} 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. {% endhint %} If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ## 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](https://docs.klaytn.com/klaytn/design/accounts#smart-contract-accounts-scas)) that minted the Card. * `pin` is a 64-digit string and hash([SHA256](https://wikipedia.org/wiki/SHA)) 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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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](https://docs.klaytn.com/klaytn/design/accounts#smart-contract-accounts-scas)) that minted the Card, and the array `card_ids`, which will be sent using escrow. * `pin` is a 64-digit string and hash([SHA256](https://wikipedia.org/wiki/SHA)) 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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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":"" } ``` {% hint style="info" %} For details on the `cards` array, please refer to the Response Detail in [Get Cards in Escrow](/rest-api/rest-api-card-minting#escrow-information). {% endhint %} If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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](https://docs.klaytn.com/klaytn/design/accounts#smart-contract-accounts-scas)) 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](https://wikipedia.org/wiki/SHA)) 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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ## 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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="4700" %} ``` "no transaction receipt": The transaction hash doesn't exist. The transaction is either not processed or non-existant. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ## 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](https://partners.klipwallet.com) via [Change Password](/rest-api/rest-api-card-minting#change-password)and send a request to change password. * `old_password` and `new_password` are 64-digit strings and hash([SHA256](https://wikipedia.org/wiki/SHA)) 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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="4004" %} ``` "invalid password": Wrong password. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to change password. ``` {% endtab %} {% endtabs %} Pass the old PIN, new PIN, and the `access_token` that you received when signing in to [Klip Partners](https://partners.klipwallet.com) via [Change PIN](/rest-api/rest-api-card-minting#change-pin) and send a request to change PIN. * `old_pin` and `new_pin` are 64-digit strings and hash([SHA256](https://wikipedia.org/wiki/SHA)) 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: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="403" %} ``` "exceed pin code error count": You exceeded the invalid PIN Code limit. ``` {% endtab %} {% tab title="4006" %} ``` "invalid pin code": PIN Code doesn't match. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to change PIN. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). ### 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]\(). ### 7-3. Delete Card Pass the `delete_info.json` file, the `access_token` that you received when signing in to [Klip Partners](https://partners.klipwallet.com) via [Delete Card](/rest-api/rest-api-card-minting#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](https://docs.klaytn.com/klaytn/design/accounts#smart-contract-accounts-scas) address of the contract that minted the Card, and the PIN. * `pin` is a 64-digit string and hash([SHA256](https://wikipedia.org/wiki/SHA)) 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. {% hint style="warning" %} You can't delete Cards already sent to others. Deleting a Card will not delete the Card image. {% endhint %} If the request is not successful, it returns the following: {% tabs %} {% tab title="400" %} ``` "bad request": Incorrect request. Check if you entered the right request parameters. ``` {% endtab %} {% tab title="Etc." %} ``` Failed to send Card. Make a request to **Get Card List** to see the accurate status of the Cards. ``` {% endtab %} {% endtabs %} \ If you need help with this document or with Klip in general, please visit our \[Developer Forum]\(). # App2App API This tutorial is a guide to help Klip Partners use App2App REST API more easily. Since SDKs are based on REST API, you can refer to the explanations below. ## Environment Setup App2App API doesn't require a separate registration process and works in any environments where HTTP communication is possible. But since user's consent is received using Klip located in the More\[…] tab in the mobile app KakaoTalk, you need to have KakaoTalk installed to make the requests. {% hint style="info" %} There is no sandbox environment provided at the moment. You can test and implement using actual KakaoTalk accounts. {% endhint %} IN the examples below, REST APIs can be called using `curl`, deep links using the APIs of SDKs provided by each mobile environment. Mobile webs can use the `Web2App` library. The `Web2App` library is available in the GitHub repository below. Visit the links for more details. * [curl download](https://curl.haxx.se/download.html) * [Web2App GitHub repository](https://github.com/kakao/web2app) \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ## Step 1: Prepare The first step in App2App is **Prepare**, in which you pass the data to Klip and receive a request key. Reqeust key is required to launch a deep link and retrieve the result. Possible requests are `auth`, `transaction`. `transaction` further consists of KLAY Transfer Transaction, Token Send Transaction, Card Send Transaction, and Contract Execute Transaction. Set the appropriate fields and send a request to the API. {% hint style="info" %} Set the `from` field with the Klaytn address of the Klip user that signs the transaction. This field is optional, but it is recommended to fill it up because it is used to compare the address with the intended user's. {% endhint %} \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Case 1) Auth Request Auth request is used to retrieve the EOA of a Klip user. An example is shown below: ```bash curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \ -d '{"bapp": { "name" : "My BApp" }, "callback": { "success": "mybapp:\/\/klipwallet\/success", "fail": "mybapp:\/\/klipwallet\/fail" }, "type": "auth" }' \ -H "Content-Type: application/json" ``` {% hint style="info" %} Including additional fields like `Authorization`, `Cookie` in the API request header may cause a CORS error. Make sure not to add any fields other than the ones described here. {% endhint %} If your request is successful, it returns the following: ### ```json { "request_key": "0b0ee0ad-62b3-4146-980b-531b3201265d", // random string "status": "prepared", // Return "error" in case of a problem. "expiration_time": 1600011054 //unix timestamp } ``` Set the `success` field in the `callback` object with a deep link that takes one back to the BApp after the request is processed. The `fail` field is also set with a deep link that brings one back in case of a failure due to insufficient balance. You don't have to set this up when the BApp doesn't support deep link. In this case, the process is complete when the user is brought back from Klip to BApp. ### Case 2) Send KLAY Request Send KLAY request is used to send Klip Wallet user's KLAY to designated people. ```bash curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \ -d '{"bapp": { "name" : "My BApp" }, "type": "send_klay", "transaction": { "from": "0xcD1722f2947Def4CF144679da39c4C32bDc35681", "to": "0x85c17299e9462e035c149847776e4edb7f4b2aa9", "amount": "100" } }' \ -H "Content-Type: application/json" ``` `to` takes the address to receive KLAY and `amount` is the KLAY to send. You can enter the `amount` up to the 6th decimal place. If the request is succesful, it returns the same result as that of an Auth request. ### Case 3) Send Token Request The Send Token Request is used to send a Klip user's tokens to a specified address. An example is shown below: ```bash curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \ -d '{"bapp": { "name" : "My BApp" }, "type": "send_token", "transaction": { "contract": "0xdc8c8d2CD5829dE8e8a31Fc595D69c4B403e9dD8", "from": "0xcD1722f2947Def4CF144679da39c4C32bDc35681", "to": "0x85c17299e9462e035c149847776e4edb7f4b2aa9", "amount": "100" } }' \ -H "Content-Type: application/json" ``` You need to set the `contract` field of the `transaction` object with the SCA of a token provided by Klip. A token not supported on Klip will cause an error. Set the `amount` field with the amount of the tokens to send. You can enter the `amount` up to the 6th decimal place. If the request is succesful, it returns the same result as that of an Auth request. ### Case 4) Send Card Request The Send Card Request is used to send a Klip user's Card to a specified address. An example is shown below: ```bash curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \ -d '{"bapp": { "name" : "My BApp" }, "type": "send_card", "transaction": { "contract": "0xB21F0285d27beb2373ECB5c17E119ccEAd7Ee10A", "from": "0xcD1722f2947Def4CF144679da39c4C32bDc35681", "to": "0x85c17299e9462e035c149847776e4edb7f4b2aa9", "card_id": "1234" } }' \ -H "Content-Type: application/json" ``` You need to set the `contract` field of the `transaction` object with the SCA of a Card provided by Klip. A Card not supported on Klip will cause an error. Set the `card_id` field with the ID of the Card to send. If the request is succesful, it returns the same result as that of an Auth request. ### Case 5) Execute Contract Request The Execute Contract Request is used to execute the functionf of a specified smart contract using a Klip user's signature. An example is shown below: ```bash curl -X POST "https://a2a-api.klipwallet.com/v2/a2a/prepare" \ -d '{"bapp": { "name" : "My BApp" }, "type": "execute_contract", "transaction": { "to": "0xd4fFbe967c31C29199478Be2b5A53dC69eF9B825", "value": "0", "abi": "{ \"constant\": false, \"inputs\": [ { \"name\": \"a\", \"type\": \"string\" } ], \"name\": \"testString\", \"outputs\": [], \"payable\": false, \"stateMutability\": \"nonpayable\", \"type\": \"function\" }", "params": "[\"test_string\"]" } }' \ -H "Content-Type: application/json" ``` You need to set the `contract` field of the `transaction` object with the SCA. Set the `value` field with the KLAY to send in peb. This is only possible with a payable function. Enter the ABI of the function in `abi`. Set `params` with the array of parameters that executed this function. Note that the fields `abi` and `params` are String types. If the request is succesful, it returns the same result as that of an Auth request.\ \ If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). ## Step 2: Request Request is a process of initiating a deep link to request Klip to process App2App request. When Klip is opened through a deep link, the user will see an confirm window. For an Auth request, the user will be asked to give consent to providing his/her EOA to the BApp. For transaction requests, the relevant transaction data will be displayed on the screen, and the transaction will be processed after receiving the PIN. If you set up a callback deep link in the **Prepare** step, it will redirect automatically to the BApp. Otherwise, the user will be provided with a notification message to return to the BApp. Klip provides deep links for the following environments. For all of the environments, you need to pass `request_key` as a query string, which you obtained in the **Prepare** step. \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ### Case 1) iOS Environment ``` kakaotalk://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=0b0ee0ad-62b3-4146-980b-531b3201265d ``` The `kakaotalk` URL scheme can be detected by the BApp using an API provided by iOS. The link that redirects to the KakaoTalk download link in case it is not installed is shown below: ``` itms-apps://itunes.apple.com/app/id362057947 ``` ### Case 2) Android Environment ``` intent://klipwallet/open?url=https://klipwallet.com/?target=/a2a?request_key=0b0ee0ad-62b3-4146-980b-531b3201265d#Intent;scheme=kakaotalk;package=com.kakao.talk;end ``` The `kakaotalk` URL scheme can be detected by the BApp using an API provided by Android. The link that redirects to the KakaoTalk download link in case it is not installed is shown below: ``` market://details?id=com.kakao.talk ``` {% hint style="info" %} If you are developing your BApp for mobile web, using the [Web2App](https://github.com/kakao/web2app) library can be convenient. {% endhint %} ## Step 3: Result The final status of the App2App API request can be obtained by polling the Result API. You need to pass the `request_key` as a query string which you obtained in the **Prepare** step. ```bash curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/result?request_key=0b0ee0ad-62b3-4146-980b-531b3201265d" \ -H "Content-Type: application/json" ``` If the request is successful, it returns the corresponding result for each `type` as shown below: ### Case 1) Auth Request ```json { "request_key": "0b0ee0ad-62b3-4146-980b-531b3201265d", "expiration_time": 1600011054, "status": "completed", "result": { "klaytn_address": "0x85c17299e9462e035c149847776e4edb7f4b2aa9" } } ``` ### Case 2) Requests other than Auth ```json { "request_key": "0b0ee0ad-62b3-4146-980b-531b3201265d", "expiration_time": 1600011054, "status": "completed", "result": { "tx_hash": "0x82d018556e88b8f8f43dc2c725a683afc204bfd3c17230c41252354980f77fb3", "status": "success" } } ``` For requests other than `Auth`, there is also the `result` object in the response. You can use the `tx_hash` in the `result` object to check the transaction status at [Klaytnscope](https://scope.klaytn.com/). If the `status` in `result` reads `pending`, it means that the transaction has been confirmed by the user in Klip, but is still being processed on Klaytn. Normally, you should be able to see it in a few seconds. `success` is returned when the request is successful, and `fail`은 when the request is unsuccessful. \ If you need help with this document or Klip in general, please visit our \[Developer Forum]\(). ## Get Additional Information To be able to send Cards in a BApp, you often need to retrieve the user's list of Cards and obtain the ID. You can retrieve the Card list of a user using the EOA obtained from the Auth request and the contract address as parameters. An example is shown below: ```bash curl -X GET "https://a2a-api.klipwallet.com/v2/a2a/cards?sca=0xB21F0285d27beb2373ECB5c17E119ccEAd7Ee10A&eoa=0x85c17299e9462e035c149847776e4edb7f4b2aa9&cursor=" -H "Content-Type: application/json" ``` If the request is successful, it returns the following: ```json { "name": "conan", "symbol_img": "https://media.klipwallet.com/token_icon/klay_klip.svg", "cards": [ { "created_at": 1580176787, "created_at_format": "format", "updated_at": 1580176787, "updated_at_format": "format", "owner": "0x85c17299e9462e035c149847776e4edb7f4b2aa9", "sender": "0x2412b300750f505fb2e68ddf0cd45e9d95f5378d", "sender_kakao_id": "1234" "card_id": 19, "card_uri": "https://media.klipwallet.com/card-asset/1234/19.json", "transaction_hash": "0x293a2e53ecf238109908e65a2b7ff4aad0919ce3ce54af08d6fc4323f28e935d" }, ], "next_cursor": "mrzedXOE9OeEorkAvwQXB7JdVg4LP1Rzze2kLQFxLU4C8iMOhOVulzIr5iesZoie9uv9h87UNXsWCKdhqYszXFWLsYYI7h125Rx8p56qlMKaZ20YbNW3zDGmNBJKM1wL" } ``` If the request is successful, it will return the list of Cards in a BApp and their information. * **card** from `cards`refers 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. In the example above, the response contains `cards.next_cursor`, meaning that this account holds over a 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 HTTP status codes 400 or 500. For more details, please refer to [Basics](/basics#basics-app2app).\ If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28). # Change Log This page is the changelog for the updates on Klip API. ## 2021/09/30 * Added `canceled` to the App2App's result status ## 2021/07/28 * Updated the field restrictions for animation\_url ## 2021/07/13 * Added notice for using App2App Auth. API ## 2021/07/07 * Applied company name change in App2App SDK Open Source Notice * Ground1 -> GroundX, Ground X -> GroundX ## 2021/06/28 * Added App2App authentication request button guide ## 2021/05/10 * New API * An API to upload NFT resource file * New request field for Card Minting API * You can upload video clip URL in the `animation_url` field ## 2021/03/08 * Company name change * Ground 1 -> Ground X * Company email change * -> ## 2021/02/03 * Added transaction hash field in the response for Minting/Sending APIs * New request field for Card Minting API * `secure`: You can set attributes only visible to the Card owner * `status_url`: You can set an external URL to fetch Card status * `external_link`: You can set an external URL that redirects outside of Klip * Fixed typos in the tutorial ## 2021/01/12 * New APIs * An API for checking transaction status using transaction hash * An API for returning the number of Cards minted in the current month * Fixed broken links in the Introduction ## 2020/11/30 * Added a new App2App feature based on QR code * You can now execute App2App on PC or a physically distant environment * Mobile camera app or Klip reads the QR code and process App2App requests * Added an API to send Cards using escrow * A link is created through which a Card is sent * You can claim the Card by clicking on the link ## 2020/10/26 * Added App2App API * Allows you to fetch Klip user addersses from external services * Allows you to send KLAY, FTs, or NFTs and execute smart contracts from external services using Klip ## 2020/08/26 * Added optional fields in the Card's metadata for Mint Card To User, Mint Card To Klip Member APIs * `group_name`, `group_icon`, `hashtags`, `layout`, `qr_code`, `bar_code` * Changed responses for Get Card Information By BApp, Get Card Information APIs * `bapps[i].cards.cards[i]` -> `bapps[i].cards[i]` * `bapps[i].cards.next_cursor` -> `bapps[i].cards_next_cursor` * Changed responses for Get Card Information API * `cards.cards[i]` -> `cards[i]` * `cards.next_cursor` -> `next_cursor` * Added a query parameter for Get Card Information API * `isAll` ## 2020/07/31 * Changed Mint Card API to Mint Card To User API * Mints Cards to users with EOA (Klip Member or non-member) * Uses user EOA when minting * Added Mint Card To Klip Member API * Mints Card to Klip users * Uses name and phone number of Klip users * Changed Send Card API to Send Card To User API * Sends Card to users with EOA (Klip users or non-users) * Uses user EOA when sending * Added Send Card To Klip Member API * Sends card to Klip users * Uses name and phone number of Klip users * Response parameter `failCount` changed to `fail_count` in Send Card To User, Send Card To Klip Member APIs ## 2020/07/16 * Response parameter `order_no` changed to `nft_order_no` in Get Card Information By BApp API ## 2020/06/16 * Send Card API does not use `to_klip_id` as request body parameter anymore ## 2020/05/28 * An API for [Klip Partners](https://partners.klipwallet.com/) to sign in on Klip and mint, send and browse Card (NFTs)