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 CodeError CodeError 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

TermDescription

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 CodeError CodeError 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).

TermDescription

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).

PreviousIntroductionNextREST API

Last updated