# Basics

## Klip Partners API <a href="#basic-card-minting" id="basic-card-minting"></a>

{% hint style="info" %}
Klip Partners 웹사이트는 허가된 사용자만 접근 가능하나, Klip Partners 서비스가 2024년 7월 31일자로 종료되어 현재는 신규 가입 신청을 받지 않고 있습니다. 아울러 기존 사용자 역시 2024년 8월 1일부터 Klip Partners API를 호출할 수 없습니다.
{% endhint %}

### Authentication

Klip Partners API를 사용하기 위해서는 JWT 기반 액세스 토큰 발급이 필요합니다. Klip Partners 회원 가입 시 등록한 로그인 ID와 비밀번호를 통해서 토큰을 발급 받을 수 있습니다. 발급된 토큰은 24시간 동안 유효하며 보통 만료 전에 재발급이 필요합니다. 발급된 토큰은 API 요청 헤더의 Authorization 필드에 토큰을 포함하는 방식으로 사용합니다.

### Pagination

보유 카드 내역을 조회할 때 카드의 양의 많은 경우 한 번에 받으면 양이 많기 때문에 여러번 요청해야할 수 있습니다. 이를 위해서 조회 API에서는 결과값에 next\_cursor를 함께 제공합니다. 일반적으로 카드 개수가 100개를 초과한다면 1번 호출 시 100개의 결과와 next\_cursor 값을 받습니다. 나머지 카드를 조회하려면 next\_cursor 값을 query 파라미터 cursor에 전달하여 API를 다시 호출해야합니다.

예들 들어 보유하고 있는 카드를 조회하면,

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

아래와 같은 형태의 응답을 받습니다.

```json
{
  "bapps": [...],
  "next_cursor": "N2r8KY...XOadEG"
}
```

남은 카드 목록을 조회하려면 next\_cursor을 이용하여 아래와 같이 다시 호출합니다. next\_cursor가 비어있을 때까지 계속 호출하여 보유한 전체 카드 목록을 얻을 수 있습니다.

```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"
```

### Success Codes/Error Codes

요청이 성공하면 HTTP code 200을 받습니다. 만약 요청이 정상 처리되지 않으면 400, 401, 500의 HTTP code가 전달됩니다. 400은 요청이 잘못된 경우, 401은 유효하지 않은 액세스 토큰을 사용했을 때 리턴됩니다. 500은 서버에 알 수 없는 장애가 발생했을 때 리턴됩니다. 400 또는 401 에러는 구체적인 에러 코드와 메시지가 함께 전달됩니다.

에러 메시지는 JSON 포맷으로 전달되며 필드는 아래와 같습니다.

```json
{
  "code": number,
  "err": string
}
```

에러 메시지 종류는 아래와 같습니다.

| 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        | banned accounts cannot login                             |
| 401         | 422        | suspended accounts cannot login                          |
| 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                                       |

### Glossary

| 용어       | 설명                                                                                                                                          |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Kaia    | [Kaia 블록체인 플랫폼](https://www.kaia.io/) - 기존에는 Klaytn 명칭으로 운영됨                                                                                |
| 스마트 컨트랙트 | 블록체인의 특정 주소(Contract Address)에 있는 코드(functions)와 데이터(state)의 모음                                                                             |
| KAIA     | Kaia 내부에서 통용되는 기본 가상 자산으로 Kaia에 트랜잭션을 전송할 때 필요한 트랜잭션 수수료를 지불하는데 사용. 기존에는 KLAY 명칭으로 사용됨                                                      |
| FT       | 대체 가능 표준 토큰(Fungible Token) 또는 토큰, [KIP-7](https://kips.klaytn.foundation/KIPs/kip-7) 참조                                                    |
| NFT      | 대체 불가 표준 토큰(Non-fungible Token) 또는 카드, [KIP-17](https://kips.klaytn.foundation/KIPs/kip-17) 참조                                              |
| 카드       | Klip에서 사용되는 디지털 자산으로 NFT를 의미                                                                                                                |
| 계정       | 블록체인에서 가상 자산을 보유하는 주체인 동시에 다양한 종류의 트랜잭션을 블록체인 네트워크에 전송하는 주체 (Account)                                                                       |
| 트랜잭션 전송  | 블록체인의 상태를 "변화"시키는 행위이며 주로 블록체인에 데이터를 업로드, 수정, 삭제하거나 블록체인에 스마트 컨트랙트를 배포, 실행하는 행위를 의미                                                         |
| EOA      | 외부 소유 계정(Externally Owned Account)의 의미로, Kaia 상에서 KAIA, NFT, FT를 소유하고 트랜잭션을 전송하는 주체. Kaia의 [계정](https://docs.kaia.io/ko/learn/accounts/) 참조 |
| 서명       | Kaia에서 실행되는 트랜잭션이 전송자 본인에 의해 생성되었다는 것을 증명하기 위한 정보를 생성하는 행위                                                                                  |
| 계정 키     | 서명에 사용하는 계정의 키(AccountKey). 계정 키로 트랜잭션에 서명해야 서명이 정상적으로 완료됨.                                                                                 |

## App2App API <a href="#basics-app2app" id="basics-app2app"></a>

### Authentication

App2App API는 기본적으로 인증을 필요로 하지 않습니다. 하지만 BApp 별로 요청을 구분하기 위해서 request key를 발급하여 API 요청 시 사용합니다. 해당 key를 통해서 Klip 서버에서 요청 내용을 구분하여 컨텍스트를 유지하여 처리합니다. 일반적으로 request key를 발급받고 사용하는 절차는 아래와 같습니다.

* prepare API를 통해 인증 또는 서명할 내용을 전달하고 응답으로 request key를 전달 받습니다.
* 전달받은 request key를 이용하여 Deep Link(지정된 앱을 자동으로 실행하고 홈페이지가 아닌 특정 페이지로 가기 위한 URI)를 호출합니다. Klip 앱이 설치된 경우에는 Klip이 실행되고, 설치 되지 않은 경우에는 사용자가 앱을 다운로드받을 수 있습니다.
* 처리 결과는 result API를 통해서 polling하고 이 때 Query 파라미터 request\_key에 어떤 요청에 대한 처리 결과를 얻고자 하는지를 전달합니다.

### Pagination

보유 카드 내역을 조회할 때 카드의 양의 많은 경우 한 번에 받으면 양이 많기 때문에 여러번 요청해야할 수 있습니다. 이를 위해서 조회 API에서는 결과값에 next\_cursor를 함께 제공합니다. 일반적으로 카드 개수가 100개를 초과한다면 1번 호출 시 100개의 결과와 next\_cursor 값을 받습니다. 나머지 카드를 조회하려면 next\_cursor 값을 query 파라미터 cursor에 전달하여 API를 다시 호출해야합니다.

예들 들어 보유하고 있는 카드를 조회하면,

```bash
//Get card list
curl "https://api.klipwallet.com/v2/a2a/cards?chain=klaytn&sca=SCA&eoa=EOA" \
-H "Content-Type: application/json"
```

아래와 같은 형태의 응답을 받습니다.

```json
{
  "name": "KLIP",
  "symbol_img": "image url",
  "cards": [...],
  "next_cursor": "N2r8KY...XOadEG"
}
```

남은 카드 목록을 조회하려면 next\_cursor을 이용하여 아래와 같이 다시 호출합니다. next\_cursor가 비어있을 때까지 계속 호출하여 보유한 전체 카드 목록을 얻을 수 있습니다.

```bash
//Get card list
curl "https://api.klipwallet.com/v2/a2a/cards?chain=klaytn&sca=SCA&eoa=EOA&cursor=N2r8KY...XOadEG" \
-H "Content-Type: application/json"
```

### SDK

App2App API 기본적으로 REST API를 제공하지만, 각 BApp 개발환경에 맞게 사용할 수 있는 SDK를 제공합니다. 현재 지원하는 SDK 종류는 Android, iOS, 모바일 웹용 JavaScript입니다. 구체적인 내용은 [SDK 페이지](https://docs.klipwallet.com/a2a-sdk)를 참조하십시오.

### Success Codes/Error Codes <a href="#basics-a2a-return-code" id="basics-a2a-return-code"></a>

요청이 성공하면 HTTP code 200을 받습니다. 만약 요청이 정상 처리되지 않으면 400, 500의 HTTP code가 전달됩니다. 400은 요청 데이터가 잘못됐거나 유효하지 않은 request\_key를 사용했을 때 리턴됩니다. 500은 서버에 알 수 없는 장애가 발생했을 때 리턴됩니다. 400 에러는 구체적인 에러 코드와 메시지가 함께 전달됩니다. 자세한 내용은 각 API를 참조하십시오.

에러 메시지는 JSON 포맷으로 전달되며 필드는 아래와 같습니다.

```json
{
  "request_key": "random key",
  "expiration_time": unix timestamp,
  "status": "error",
  "error": {
    "code": int,
    "err": "error message"
  }
}
```

이와 별개로 카드 조회 API (/v2/a2a/cards)는 request key와 관련이 없기 때문에 아래와 같은 형태로 에러가 전달됩니다.

```json
{
  "code": number,
  "err": string
}
```

에러 메시지 종류는 아래와 같습니다.

| 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 `or` { ivalid params detail info }        |
| 400         | 6409       | invalid value                                            |
| 400         | 6410       | unknown request type                                     |
| 400         | 6411       | invalid from address                                     |
| 400         | 6412       | insufficient funds                                       |
| 400         | 6414       | { tx revert reason }                                     |
| 400         | 6416       | kas\_authorization\_key cannot be used with this request |
| 400         | 6417       | the request is not supported with this chain             |
| 400         | 6418       | invalid kas\_authorization\_key                          |
| 400         | 6500       | address is on the blacklist                              |
| 400         | 6501       | invalid user status                                      |
| 500         | 500        | internal server error                                    |

### Glossary

| Term        | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| Deep link   | 웹이나 앱에서 홈페이지가 아닌 특정 페이지로 가기위한 URI (Query 파라미터를 통해 요청할 작업을 구분하기 위한 용도로 사용)       |
| Request key | App2App API 요청을 구분하기 위한 랜덤하게 생성된 `a0fee72d-3b1b-43a3-ae0d-e277a1001bef` 형태의 문자열 |

이 문서 혹은 Klip에 관한 문의는 [개발자 포럼](https://klipforum.zendesk.com)을 방문해 도움을 받으십시오.