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](https://forum.klaytn.com/c/klip-api/28).
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:
You will get the following response:
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.
If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).
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:
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](https://forum.klaytn.com/c/klip-api/28).
Glossary
Term | Description |
---|---|
Klaytn | |
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 for more. |
NFT | Non-fungible Token, or Card. See 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 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.
If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).
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](https://forum.klaytn.com/c/klip-api/28).
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:
You will get the following response:
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.
If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).
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 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:
Since the Get Card Information API (/v2/a2a/cards) is not relevant to request_key
, an error looks like this:
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](https://forum.klaytn.com/c/klip-api/28).
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. |
If you need help with this document or Klip in general, please visit our [Developer Forum](https://forum.klaytn.com/c/klip-api/28).
Last updated