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:

//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:

{
  "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.

//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](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:

{
  "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](https://forum.klaytn.com/c/klip-api/28).

Glossary

Term	Description
Klaytn	Klaytn Blockchain Platform
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:

//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:

{
  "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.

//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](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:

{
  "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:

{
  "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](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. 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](https://forum.klaytn.com/c/klip-api/28).