# Klip Partners

{% hint style="info" %}
Kaia는 기존의 Klaytn과 Finschia 블록체인 네트워크가 통합되어 운영되는 블록체인의 새 이름입니다. 이에 따라 본 문서는 대부분 Klaytn을 Kaia로 / KLAY를 KAIA로 지칭하지만, 하위 호환성을 위해 기존 호출과 응답에서 사용되던 klaytn, KLAY 등의 키워드는 동일하게 유지되는 점 참고 부탁드립니다.
{% endhint %}

## Klip Partners API Reference

### 계정 관리 <a href="#account-management" id="account-management"></a>

계정 관리 API에는 로그인(Sign In), 비밀번호 변경(Change Password), 핀 번호 변경(Change Pin)이 있습니다.

#### Sign In <a href="#sign-in" id="sign-in"></a>

## Sign In

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/partner/auth`

가입을 승인받은 후, 가입 시 입력한 이메일 주소와 비밀번호로 Klip Partners에 로그인합니다.

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| Content-Type<mark style="color:red;">\*</mark> | string | application/json |

#### Request Body

| Name                                       | Type   | Description                                                  |
| ------------------------------------------ | ------ | ------------------------------------------------------------ |
| email<mark style="color:red;">\*</mark>    | string | 가입자 이메일 주소이며 로그인 계정으로 사용됩니다.                                 |
| password<mark style="color:red;">\*</mark> | string | 가입자 로그인 비밀번호입니다. 웹사이트에 가입 시 사용한 비밀번호에 SHA256 해시를 적용하여 전송합니다. |

{% tabs %}
{% tab title="200 " %}

```
{
  "email": "ray.kim@groundx.xyz",
  "klaytn_address":0xdc6AE5861a73d852bd3cdD84a4BA7f598A5160F3,
  "contract_address": "0xc94770007dda54cF92009BFF0dE90c06F603a09f",
  "name": "Ray Kim",
  "phone": "01077777777",
  "service_name": "판타지월드레볼루션"
  "access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJI...",
  "status" : 1
  "mint_limit": 1000
  "mint_count": 1
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="406" %}

```
"not found user info in db": 계정 정보가 존재하지 않습니다.
```

{% endtab %}

{% tab title="421" %}

```
"banned accounts cannot login": 제재 계정은 로그인할 수 없습니다.
```

{% endtab %}

{% tab title="422" %}

```
"suspended accounts cannot login": 정지 계정은 로그인할 수 없습니다.
```

{% endtab %}

{% tab title="426" %}

```
"not yet approved": 아직 가입이 승인되지 않았습니다.
```

{% endtab %}

{% tab title="4004" %}

```
"invalid password": 비밀번호가 일치하지 않습니다.
```

{% endtab %}

{% tab title="기타" %}

```
로그인할 수 없습니다.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

```
```

{% endtab %}
{% endtabs %}

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

**Request Example**

```
curl -X POST "https://api.klipwallet.com/v2/partner/auth" \
-d '{"email":"ray.kim@groundx.xyz", "password":"C01069C9ABB6EA7DA49AE418A24BBEF3AD67170DDCD20AC7C76084A5A85E4057"}' \
-H "Content-Type: application/json"
```

**Response Details**

| 이름                | 타입     | 설명                                                                                            |
| ----------------- | ------ | --------------------------------------------------------------------------------------------- |
| email             | string | 가입자 이메일 주소이며 로그인 계정으로 사용됩니다.                                                                  |
| klaytn\_address   | string | 가입자 Kaia [EOA](https://docs.kaia.io/ko/learn/accounts/) 주소입니다. 호환성 유지를 위해 `klaytn` 명칭이 사용됩니다. |
| contract\_address | string | 카드를 발행하는 [SCA](https://docs.kaia.io/ko/learn/accounts/) 주소입니다.                                |
| name              | string | 가입자 이름이며 사업자 또는 법인 이름을 사용합니다.                                                                 |
| phone             | string | 가입자 전화번호입니다.                                                                                  |
| service\_name     | string | 가입자가 제공하는 BApp 서비스 이름입니다.                                                                     |
| access\_token     | string | JWT 형식으로 API 호출을 허용하기 위해 발급된 인증 토큰입니다.                                                        |
| status            | number | 계정 상태코드입니다.                                                                                   |
| mint\_limit       | number | 계정이 이번 달에 발행할 수 있는 최대 카드 개수입니다.                                                               |
| mint\_count       | number | 계정이 이번 달에 발행한 카드 개수입니다.                                                                       |

{% hint style="info" %}
`status`는 가입 승인 전에는 20, 가입 승인 후에는 1의 값을 가집니다.\
`access_token`은 발급받은 지 24시간이 지나면 만료되므로 재발급받아야 합니다.\
`mint_count`와 `mint_limit`은 매달 1일 초기화됩니다.
{% endhint %}

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#sign-in)을 확인하십시오.

#### Change Password <a href="#change-password" id="change-password"></a>

## Change Password

<mark style="color:orange;">`PUT`</mark> `https://api.klipwallet.com/v2/partner/?opt=password`

가입 시 입력한 비밀번호를 변경합니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                            | Type   | Description       |
| ----------------------------------------------- | ------ | ----------------- |
| old\_password<mark style="color:red;">\*</mark> | string | 기존에 사용하던 비밀번호입니다. |
| new\_password<mark style="color:red;">\*</mark> | string | 새롭게 사용할 비밀번호입니다.  |

{% tabs %}
{% tab title="200 " %}

```
{}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="4004" %}

```
"invalid password": 비밀번호가 일치하지 않습니다.
```

{% endtab %}

{% tab title="기타" %}

```
비밀번호 변경에 실패했습니다.
```

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

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#change-password-and-pin)을 확인하십시오.

#### Change PIN <a href="#change-pin" id="change-pin"></a>

## Change PIN

<mark style="color:orange;">`PUT`</mark> `https://api.klipwallet.com/v2/partner/pin`

가입 시 입력한 핀 번호를 변경합니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                       | Type   | Description                                      |
| ------------------------------------------ | ------ | ------------------------------------------------ |
| old\_pin<mark style="color:red;">\*</mark> | string | 기존에 사용하던 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다. |
| new\_pin<mark style="color:red;">\*</mark> | string | 새롭게 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다.  |

{% tabs %}
{% tab title="200 " %}

```
{}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="403" %}

```
"exceed pin code error count": 핀 번호 입력 오류 횟수가 지정된 한도를 초과하였습니다.
```

{% endtab %}

{% tab title="4006" %}

```
"invalid pin code": 기존 핀 번호가 일치하지 않습니다.
```

{% endtab %}

{% tab title="기타" %}

```
핀 번호를 변경하지 못했습니다.
```

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

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#change-password-and-pin)을 확인하십시오.

### 카드 관리 <a href="#card-management" id="card-management"></a>

카드 관리 API에는 카드 이미지 업로드(Upload Image), 모든 사용자에게 카드 발행(Mint Card To User), Klip 회원에게 카드 발행(Mint Card To Klip Member), 모든 사용자에게 카드 전송(Send Card To User), Klip 회원에게 카드 전송(Send Card To Klip Member), 카드 정보 불러오기(Get Card Information By Bapp, Get Card Information), 카드 삭제(Delete Card)가 있습니다.

#### Upload Image <a href="#upload-image" id="upload-image"></a>

## Upload Image

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/wallet/image`

카드에 사용할 이미지를 업로드합니다.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다.    |
| Content-Type<mark style="color:red;">\*</mark>  | string | multipart/form-data |

#### Request Body

| Name                                     | Type   | Description                       |
| ---------------------------------------- | ------ | --------------------------------- |
| upload<mark style="color:red;">\*</mark> | string | 업로드할 이미지 파일명입니다. 파일 경로를 포함해야 합니다. |

{% tabs %}
{% tab title="200 " %}

```
{"image": "https://url_path_to_img_file/image.png"}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
이미지를 업로드하지 못했습니다.
```

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

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#upload-image)을 확인하십시오.

#### Upload NFT Resource <a href="#upload-nftresource" id="upload-nftresource"></a>

## Upload NFT resource

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/wallet/nftResource`

카드에 사용할 리소스를 업로드합니다. `animation_url` 필드에 설정할 동영상 파일의 경우 크기가 10MiB로 제한됩니다.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다.    |
| Content-Type<mark style="color:red;">\*</mark>  | string | multipart/form-data |

#### Request Body

| Name                                     | Type   | Description                   |
| ---------------------------------------- | ------ | ----------------------------- |
| upload<mark style="color:red;">\*</mark> | string | 업로드할 파일명입니다. 파일 경로를 포함해야 합니다. |

{% tabs %}
{% tab title="200 " %}

```
{"url": "https://url_path_to_file/file.mp4"}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="4100" %}

```
"upload animation file limit exceeded": 동영상 파일의 경우 제한된 크기 10MiB를 넘었습니다. 파일 크기를 다시 확인하십시오.
```

{% endtab %}

{% tab title="4101" %}

```
"upload animation file extension is not support": 지원하지 않는 동영상 포맷입니다.
```

{% endtab %}

{% tab title="기타" %}

```
파일을 업로드하지 못했습니다.
```

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

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#upload-nftresource)을 확인하십시오.

#### Upload Secure NFT Resource <a href="#upload-secure-nftresource" id="upload-secure-nftresource"></a>

## Upload secure NFT resource

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/wallet/nftResource/secure`

카드에 사용할 소유자 전용 리소스를 업로드합니다. `upload` 필드에 설정할 수 있는 파일 용량은 최대 10MiB입니다. 가로x세로 각각 23000px 이하 카드 이미지를 사용해야 Klip에 정상적으로 노출됩니다.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다.    |
| Content-Type<mark style="color:red;">\*</mark>  | string | multipart/form-data |

#### Request Body

| Name                                     | Type   | Description                   |
| ---------------------------------------- | ------ | ----------------------------- |
| upload<mark style="color:red;">\*</mark> | string | 업로드할 파일명입니다. 파일 경로를 포함해야 합니다. |

{% tabs %}
{% tab title="200 " %}

```
{"filename": "{uuid}.{extension}"}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="4100" %}

```
"upload animation file limit exceeded": 동영상 파일의 경우 제한된 크기 10MiB를 넘었습니다. 파일 크기를 다시 확인하십시오.
```

{% endtab %}

{% tab title="4101" %}

```
"upload animation file extension is not support": 지원하지 않는 동영상 포맷입니다.
```

{% endtab %}

{% tab title="기타" %}

```
파일을 업로드하지 못했습니다.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

```
```

{% endtab %}
{% endtabs %}

**Request Example**

```
curl -X POST "https://api.klipwallet.com/v2/wallet/nftResource/secure" \
-F upload=@./file.mp4 \
-H "Authorization: ACCESS_TOKEN" -H "Content-Type: multipart/form-data"
```

#### Mint Card to User <a href="#mint-card-to-user" id="mint-card-to-user"></a>

## Mint Card To User

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/wallet/mint`

Klip Partners에 사용자 정보를 보내고 카드를 발행합니다. 사용자 EOA로 발행됩니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                                | Type    | Description                                                                                                                                                             |
| --------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pin<mark style="color:red;">\*</mark>               | string  | 서명에 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다.                                                                                                                         |
| to\_address<mark style="color:red;">\*</mark>       | array   | 카드를 발행받을 EOA 주소들이 담긴 `string` 배열입니다.                                                                                                                                    |
| contract\_address<mark style="color:red;">\*</mark> | string  | 카드를 발행하는 SCA 주소입니다.                                                                                                                                                     |
| name<mark style="color:red;">\*</mark>              | string  | 카드 이름입니다.                                                                                                                                                               |
| description<mark style="color:red;">\*</mark>       | string  | 카드에 관한 설명입니다.                                                                                                                                                           |
| image<mark style="color:red;">\*</mark>             | string  | 카드에 사용할 이미지 URL 주소입니다.                                                                                                                                                  |
| animation\_url                                      | string  | 카드에 사용할 동영상 URL 주소입니다. 지원하는 파일 확장자는 `.mp4`입니다. H.264 코덱이 아니거나 해상도가 `3840x2160`을 넘는 경우 재생되지 않을 수 있습니다.                                                                   |
| background\_color                                   | string  | 카드 배경에 사용할 RGB 색상 코드입니다.                                                                                                                                                |
| sendable                                            | boolean | TRUE이면 발행한 카드를 Klip에서 타인에게 전송 가능합니다.                                                                                                                                    |
| send\_friend\_only                                  | boolean | TRUE이면 발행한 카드를 Klip에서 카카오톡 친구에게만 전송 가능합니다. 현재 Klip 내에서 일시적으로 친구 전송이 제공되지 않고 있으므로 FALSE로 설정합니다.                                                                          |
| group\_name                                         | string  | 카드를 그룹핑할 때 사용하는 카드 그룹 이름입니다.                                                                                                                                            |
| group\_icon                                         | string  | 카드 그룹 아이콘으로 사용할 이미지 URL 주소입니다.                                                                                                                                          |
| hashtags                                            | array   | 해시태그들이 담긴 `string` 배열입니다. 카드에 해시태그를 달면 특정 주제, 내용을 쉽게 찾을 수 있습니다.                                                                                                         |
| layout                                              | string  | 카드를 보여주는 방식입니다. 예를 들어, 정사각형 이미지는 `general`, 가로가 더 긴 이미지는 `horizontal` 세로가 긴 이미지는 `vertical`로 설정할 수 있습니다. 기본값은 `general`입니다.                                             |
| external\_link                                      | string  | Klip 외부로 연결되는 URL 주소입니다. (최대 길이:255)                                                                                                                                    |
| custom\_links                                       | array   | Klip 외부로 연결되는 URL 주소들이 담긴 `object` 배열 입니다. `display_name`에 노출할 속성명, `value`에 속성값을 쌍을 이뤄 지정합니다. Klip의 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (배열의 최대 크기: 10개, 각 링크의 최대 길이: 255) |
| qr\_code                                            | string  | QR Code가 그려진 이미지 URL입니다 (최대 길이:255)                                                                                                                                     |
| bar\_code                                           | string  | Bar Code가 그려진 이미지 URL입니다. (최대 길이:255)                                                                                                                                   |
| attributes                                          | array   | 발행할 카드 속성값들이 담긴 `object` 배열입니다.                                                                                                                                         |
| secure                                              | object  | 카드 소유자에게만 보여줄 정보를 담은 `object`입니다. `bar_code`, `qr_code`, `images`, `animations`, 및 `attributes` 필드를 선택적으로 설정할 수 있습니다.                                                   |
| status\_url                                         | string  | 카드 상태 정보를 담고 있는 외부 URL입니다. 해당 URL에서는 JSON 값을 반환해야하고, 필수적으로 bool type의 `valid` 필드와 선택적으로 array type의 `attributes` 필드를 설정할 수 있습니다.                                        |

{% tabs %}
{% tab title="200 " %}

```
{
  "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97"
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
정상적인 카드 발행에 실패했습니다.
일부 카드는 발행되었을 수 있으니 ‘보유 카드 목록’ 에서 보유 목록을 확인하십시오.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

```
```

{% endtab %}
{% endtabs %}

```
//attributes 예시
"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 예시 ()
"secure": {
    // 일반적으로 bar_code 또는 qr_code 둘 중 하나만 설정
    "bar_code": "1234 ABCD 5678 EFGH 90IJ",
    "qr_code": "https://your-domain.com?key=1234",

    // 사전에 업로드한 secure 이미지의 UUID를 사용
    // 배열 형식이지만 현재 클립에서 소유자 전용 이미지는 한 개만 추가 노출되므로 하나만 인자로 입력
    "images": [
      {"low_resolution" : "{uploaded-filename-1}.png"}
    ],
    
    // 사전에 업로드한 secure 동영상의 UUID를 사용
    // 배열 형식이지만 현재 클립에서 소유자 전용 동영상은 한 개만 추가 노출되므로 하나만 인자로 입력
    // animations를 등록하는 경우, 반드시 images도 "썸네일" 역할로써 등록 필요
    "animations": [
      {"low_resolution" : "{uploaded-filename-2}.mp4"}
    ],

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

//status_url 호출 시 응답값 예시
{
    "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"
        }
    ]
}
```

```
custom_links: [
    {
        "display_name": "고객센터",
        "value": "https://customersupport.com"
    },
    {
        "display_name": "홈페이지",
        "value": "https://homepage.com"
    }
]
```

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

| 이름         | 타입     | 설명                                                                                                                                                                                     |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bar\_code  | string | bar code로 표시할 문자열 값입니다. 기본적으로 CODE 128 형식을 사용합니다. optional 필드입니다. (최대 길이:20, ' '(공백) 또는 '-' 문자 제외)                                                                                     |
| qr\_code   | string | qr code로 표시할 문자열 값입니다. optional 필드입니다. (최대 길이:255)                                                                                                                                     |
| attributes | array  | 카드 속성값들이 담긴 `object` 배열입니다. optional 필드입니다.                                                                                                                                            |
| images     | array  | secure 이미지 객체들의 배열입니다. 이미지 객체는 `low_resolution`과 (또는) `high_resolution` 값을 가지며 각각 저해상도 이미지, 고해상도 이미지 파일명을 기록합니다. secure 이미지 업로드 방법은 Upload Secure NFT Resource를 참조하세요. optional 필드입니다. |
| animations | array  | secure 동영상 객체들의 배열입니다. 동영상 객체는 `low_resolution`과 (또는) `high_resolution` 값을 가지며 각각 저해상도 동영상, 고해상도 동영상 파일명을 기록합니다. secure 동영상 업로드 방법은 Upload Secure NFT Resource를 참조하세요. optional 필드입니다. |

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#mint-card-to-user)을 확인하십시오.

#### Mint Card to Klip Member <a href="#mint-card-to-klip-member" id="mint-card-to-klip-member"></a>

## Mint Card To Klip Member

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/wallet/mint/person`

Klip Partners에 Klip 회원 정보를 보내고 카드를 발행합니다. `to_person`에 입력한 실명과 전화번호를 가진 Klip 회원 EOA로 발행됩니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                                | Type    | Description                                                                                                                                                             |
| --------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pin<mark style="color:red;">\*</mark>               | string  | 서명에 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다.                                                                                                                         |
| to\_person<mark style="color:red;">\*</mark>        | array   | 카드를 발행받을 실명과 전화번호 쌍이 담긴 2차원 배열입니다.                                                                                                                                      |
| contract\_address<mark style="color:red;">\*</mark> | string  | 카드를 발행하는 SCA 주소입니다.                                                                                                                                                     |
| name<mark style="color:red;">\*</mark>              | string  | 카드 이름입니다.                                                                                                                                                               |
| description<mark style="color:red;">\*</mark>       | string  | 카드에 관한 설명입니다.                                                                                                                                                           |
| image<mark style="color:red;">\*</mark>             | string  | 카드에 사용할 이미지 URL 주소입니다.                                                                                                                                                  |
| animation\_url                                      | string  | 카드에 사용할 동영상 URL 주소입니다. 지원하는 파일 확장자는 `.mp4`입니다. H.264 코덱이 아니거나 해상도가 `3840x2160`을 넘는 경우 재생되지 않을 수 있습니다.                                                                   |
| background\_color                                   | string  | 카드 배경에 사용할 RGB 색상 코드입니다.                                                                                                                                                |
| sendable                                            | boolean | TRUE이면 발행한 카드를 Klip에서 타인에게 전송 가능합니다.                                                                                                                                    |
| send\_friend\_only                                  | boolean | TRUE이면 발행한 카드를 Klip에서 카카오톡 친구에게만 전송 가능합니다. 현재 Klip 내에서 일시적으로 친구 전송이 제공되지 않고 있으므로 FALSE로 설정합니다.                                                                          |
| group\_name                                         | string  | 카드를 그룹핑할 때 사용하는 카드 그룹 이름입니다.                                                                                                                                            |
| group\_icon                                         | string  | 카드 그룹 아이콘으로 사용할 이미지 URL 주소입니다.                                                                                                                                          |
| hashtags                                            | array   | 해시태그들이 담긴 `string` 배열입니다. 카드에 해시태그를 달면 특정 주제, 내용을 쉽게 찾을 수 있습니다.                                                                                                         |
| layout                                              | string  | 카드를 보여주는 방식입니다. 예를 들어, 정사각형 이미지는 `general`, 가로가 더 긴 이미지는 `horizontal` 세로가 긴 이미지는 `vertical`로 설정할 수 있습니다. 기본값은 `general`입니다.                                             |
| external\_link                                      | string  | Klip 외부로 연결되는 URL 주소입니다. (최대 길이:255)                                                                                                                                    |
| custom\_links                                       | array   | Klip 외부로 연결되는 URL 주소들이 담긴 `object` 배열 입니다. `display_name`에 노출할 속성명, `value`에 속성값을 쌍을 이뤄 지정합니다. Klip의 NFT 상세 화면에서 외부로 연결되는 링크가 제공됩니다. (배열의 최대 크기: 10개, 각 링크의 최대 길이: 255) |
| qr\_code                                            | string  | QR Code가 그려진 이미지 URL 주소입니다. (최대 길이:255)                                                                                                                                 |
| bar\_code                                           | string  | Bar Code가 그려진 이미지 URL 주소입니다. (최대 길이:255)                                                                                                                                |
| attributes                                          | array   | 발행할 카드 속성값들이 담긴 `object` 배열입니다.                                                                                                                                         |
| secure                                              | object  | 카드 소유자에게만 보여줄 정보를 담은 `object`입니다. `bar_code`, `qr_code`, `images`, `animations`, 및 `attributes` 필드를 선택적으로 설정할 수 있습니다.                                                   |
| status\_url                                         | string  | 카드 상태 정보를 담고 있는 외부 URL입니다. 해당 URL에서는 JSON 값을 반환해야하고, 필수적으로 bool type의 `valid` 필드와 선택적으로 array type의 `attributes` 필드를 설정할 수 있습니다.                                        |

{% tabs %}
{% tab title="200 " %}

```
{
  "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97",
  "result": [["홍길동", "010-1111-2222", "success", ""], ["김춘향", "010-3333-4444", "fail", "phone number does not exist"], ...]
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
정상적인 카드 발행에 실패했습니다.
일부 카드는 발행되었을 수 있으니 ‘보유 카드 목록’ 에서 보유 목록을 확인하십시오.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

```
```

{% endtab %}
{% endtabs %}

```
//attributes 예시
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 예시
"secure": {
    // 일반적으로 bar_code 또는 qr_code 둘 중 하나만 설정
    "bar_code": "1234 ABCD 5678 EFGH 90IJ",
    "qr_code": "https://your-domain.com?key=1234",

    // 사전에 업로드한 secure 이미지의 UUID를 사용
    // 배열 형식이지만 현재 클립에서 소유자 전용 이미지는 한 개만 추가 노출되므로 하나만 인자로 입력
    "images": [
      {"low_resolution" : "{uploaded-filename-1}.png"}
    ],
    
    // 사전에 업로드한 secure 동영상의 UUID를 사용
    // 배열 형식이지만 현재 클립에서 소유자 전용 동영상은 한 개만 추가 노출되므로 하나만 인자로 입력
    // animations를 등록하는 경우, 반드시 images도 "썸네일" 역할로써 등록 필요
    "animations": [
      {"low_resolution" : "{uploaded-filename-2}.mp4"}
    ],

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

//status_url 호출 시 응답값 예시
{
    "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"
        }
    ]
}
```

```
custom_links: [
    {
        "display_name": "고객센터",
        "value": "https://customersupport.com"
    },
    {
        "display_name": "홈페이지",
        "value": "https://homepage.com"
    }
]
```

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

| 이름         | 타입     | 설명                                                                                                                                                                                     |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bar\_code  | string | bar code로 표시할 문자열 값입니다. 기본적으로 CODE 128 형식을 사용합니다. optional 필드입니다. (최대 길이:20, ' '(공백) 또는 '-' 문자 제외)                                                                                     |
| qr\_code   | string | qr code로 표시할 문자열 값입니다. optional 필드입니다. (최대 길이:255)                                                                                                                                     |
| attributes | array  | 카드 속성값들이 담긴 `object` 배열입니다. optional 필드입니다.                                                                                                                                            |
| images     | array  | secure 이미지 객체들의 배열입니다. 이미지 객체는 `low_resolution`과 (또는) `high_resolution` 값을 가지며 각각 저해상도 이미지, 고해상도 이미지 파일명을 기록합니다. secure 이미지 업로드 방법은 Upload Secure NFT Resource를 참조하세요. optional 필드입니다. |
| animations | array  | secure 동영상 객체들의 배열입니다. 동영상 객체는 `low_resolution`과 (또는) `high_resolution` 값을 가지며 각각 저해상도 동영상, 고해상도 동영상 파일명을 기록합니다. secure 동영상 업로드 방법은 Upload Secure NFT Resource를 참조하세요. optional 필드입니다. |

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#mint-card-to-klip-member)을 확인하십시오.

#### Get Mint Count <a href="#mint-count" id="mint-count"></a>

## Get Mint Count

<mark style="color:blue;">`GET`</mark> `https://api.klipwallet.com/v2/wallet/mint/count`

이번 달에 파트너 계정으로 발행한 총 카드 개수를 조회할 수 있습니다. 이 값은 매월 1일에 0으로 초기화됩니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | 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**

| 이름          | 타입     | 설명                      |
| ----------- | ------ | ----------------------- |
| mint\_count | number | 이번 달 현재까지 발행한 카드 개수입니다. |

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#mint-count)을 확인하십시오.

#### Send Card to User <a href="#send-card-to-user" id="send-card-to-user"></a>

## Send Card To User

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/wallet/nft/:nft_id/:card_id/send`

카드를 다른 사용자에게 보냅니다. 전송 시 사용자 EOA를 사용합니다.

#### Path Parameters

| Name                                       | Type   | Description                      |
| ------------------------------------------ | ------ | -------------------------------- |
| nft\_id<mark style="color:red;">\*</mark>  | string | BApp에 있는 카드를 생성한 스마트 컨트랙트 ID입니다. |
| card\_id<mark style="color:red;">\*</mark> | string | BApp에 있는 카드 ID입니다.               |

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                          | Type   | Description                                     |
| --------------------------------------------- | ------ | ----------------------------------------------- |
| pin<mark style="color:red;">\*</mark>         | string | 서명에 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다. |
| to\_address<mark style="color:red;">\*</mark> | string | 카드를 받는 상대방 EOA 주소입니다.                           |
| card\_name<mark style="color:red;">\*</mark>  | string | 보낼 카드 이름입니다.                                    |

{% tabs %}
{% tab title="200 " %}

```
//전송 성공 예시
{ to_address: "0xb1764B96da889..." , fail_count: 0, tx_hash: "0x7cf09602cebb..."}
//잘못된 핀 번호를 1회 입력 시
{fail_count: 1}
//잘못된 핀 번호를 2회 입력 시
{fail_count: 2}
//잘못된 핀 번호 입력 횟수 한도는 5회입니다. 잘못된 핀 번호를 5회 입력하고
//정확한 핀 번호를 6회째에 입력해도 다음 결과를 받음에 유의하십시오.
{fail_count: 6}
//fail_count의 max값은 현재 6입니다.
//잘못된 핀 번호를 7회 입력 시
{fail_count: 6}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
카드 전송에 실패했습니다.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

```
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Klip 사용자에게 카드를 전송 시`card_name`을 입력해야 받는 사람에게 카드 이름이 표시됩니다.
{% 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"
```

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#send-card-to-user)을 확인하십시오.

#### Send Card to Klip Member <a href="#send-card-to-klip-member" id="send-card-to-klip-member"></a>

## Send Card To Klip Member

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/wallet/nft/:nft_id/:card_id/send/person`

카드를 Klip 회원에게 보냅니다. `to_person`에 입력한 실명과 전화번호를 가진 Klip 회원 EOA로 보냅니다.

#### Path Parameters

| Name                                       | Type   | Description                      |
| ------------------------------------------ | ------ | -------------------------------- |
| nft\_id<mark style="color:red;">\*</mark>  | string | BApp에 있는 카드를 생성한 스마트 컨트랙트 ID입니다. |
| card\_id<mark style="color:red;">\*</mark> | string | BApp에 있는 카드 ID입니다.               |

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                         | Type   | Description                                     |
| -------------------------------------------- | ------ | ----------------------------------------------- |
| pin<mark style="color:red;">\*</mark>        | string | 서명에 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다. |
| to\_person<mark style="color:red;">\*</mark> | array  | 카드를 받는 상대방의 실명과 전화번호가 있는 `string` 배열입니다.        |
| card\_name<mark style="color:red;">\*</mark> | string | 보낼 카드 이름입니다.                                    |

{% tabs %}
{% tab title="200 " %}

```
//전송 성공 예시
{ fail_count: 0, tx_hash: "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97" }
//잘못된 핀 번호를 1회 입력 시
{fail_count: 1, tx_hash: ""}
//잘못된 핀 번호를 2회 입력 시
{fail_count: 2, tx_hash: ""}
//잘못된 핀 번호 입력 횟수 한도는 5회입니다. 잘못된 핀 번호를 5회 입력하고
//정확한 핀 번호를 6회째에 입력해도 다음 결과를 받음에 유의하십시오.
{fail_count: 6, tx_hash: ""}
//fail_count의 max값은 현재 6입니다.
//잘못된 핀 번호를 7회 입력 시
{fail_count: 6, tx_hash: ""}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
카드 전송에 실패했습니다.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

```
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Klip 사용자에게 카드를 전송 시`card_name`을 입력해야 받는 사람에게 카드 이름이 표시됩니다.
{% 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"
```

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#send-card-to-klip-member)을 확인하십시오.

#### (deprecated) Get Card Information by Bapp <a href="#get-card-information-by-bapp" id="get-card-information-by-bapp"></a>

{% hint style="warning" %}
본 API의 경우, 클립의 자산 리스팅 정책 변경에 따라 일부 새로운 카드는 조회가 불가능할 수도 있습니다. 대신 [App2App의 Get Card Information](/rest-api/rest-api-a2a.md#get-card-information) API 사용을 권장합니다.
{% endhint %}

## Get Card Information By BApp

<mark style="color:blue;">`GET`</mark> `https://api.klipwallet.com/v2/wallet/bapp?cursor=`

내가 소유한 카드 목록을 얻습니다. 보유한 카드들은 BApp별로 묶여 출력됩니다.

#### Query Parameters

| Name   | Type   | Description                            |
| ------ | ------ | -------------------------------------- |
| cursor | string | BApp이 100개 이상이면 다음 100개 정보를 받는 커서값입니다. |

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | 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": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
BApp별로 보유한 카드 목록을 불러오지 못했습니다.
```

{% 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]`

| 이름                  | 타입     | 설명                                            |
| ------------------- | ------ | --------------------------------------------- |
| id                  | number | 이 BApp ID입니다.                                 |
| name                | string | 이 BApp 이름입니다.                                 |
| bapp\_img           | string | 이 BApp 대표 이미지 파일 주소입니다.                       |
| category\_id        | number | 이 BApp 카테고리 분류 코드입니다.                         |
| nft\_order\_no      | number | Klip 카드 목록에서 카드 그룹이 노출되는 순서입니다.               |
| summary             | string | 이 BApp에 관한 한 줄 설명입니다.                         |
| card\_count         | number | 보유한 모든 카드중 이 BApp에서 쓰이는 카드 개수입니다.             |
| nft\_id             | number | NFT ID입니다. NFT는 이 카드를 블록체인에 구현하는 스마트 컨트랙트입니다. |
| cards               | array  | 각 카드 정보를 담은 `object` 배열입니다.                   |
| cards\_next\_cursor | string | 카드가 100개 이상이면 다음 100개 정보를 불러올 커서값입니다.         |
| next\_cursor        | string | BApp이 100개 이상이면 다음 100개 정보를 불러올 커서값입니다.       |

**Response Details for** `bapps[i].cards[i]`

| 이름                | 타입     | 설명                                                                      |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| created\_at       | number | 카드가 발행된 시간입니다.                                                          |
| updated\_at       | number | 카드가 업데이트된 시간입니다.                                                        |
| owner             | string | 이 계정 [EOA](https://docs.kaia.io/ko/learn/accounts/) 주소입니다.              |
| sender            | string | 이 계정으로 카드를 보낸 사람의 [EOA](https://docs.kaia.io/ko/learn/accounts/) 주소입니다. |
| card\_id          | number | 카드 ID입니다.                                                               |
| card\_uri         | string | 카드 메타데이터가 담긴 JSON 파일 URL입니다.                                            |
| transaction\_hash | string | 카드를 발행한 스마트 컨트랙트 트랜잭션 해시입니다.                                            |

자세한 내용은 [튜토리얼1](/tutorial/tutorial-card-minting.md#get-card-information-by-bapp), [튜토리얼2](/tutorial/tutorial-card-minting.md#get-extra-card-information)를 확인하십시오.

#### Get Card Information <a href="#get-card-information" id="get-card-information"></a>

## Get Card Information

<mark style="color:blue;">`GET`</mark> `https://api.klipwallet.com/v2/wallet/nft/:nft_id?cursor=`

소유한 카드의 상세 정보를 얻습니다.

#### Path Parameters

| Name                                      | Type   | Description                                   |
| ----------------------------------------- | ------ | --------------------------------------------- |
| nft\_id<mark style="color:red;">\*</mark> | string | NFT ID입니다. NFT는 이 카드를 블록체인에 구현하는 스마트 컨트랙트입니다. |

#### Query Parameters

| Name   | Type   | Description                                                       |
| ------ | ------ | ----------------------------------------------------------------- |
| isAll  | bool   | TRUE이면 내가 소유한 모든 카드 정보를 한 번에 받습니다. `cursor` 파라미터와는 함께 사용할 수 없습니다. |
| cursor | string | 카드 정보를 100개씩 나누어 받기 위한 커서값입니다. `isAll` 파라미터와는 함께 사용할 수 없습니다.      |

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | 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": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
카드 정보를 불러오지 못했습니다.
```

{% 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**

| 이름           | 타입     | 설명                                    |
| ------------ | ------ | ------------------------------------- |
| name         | string | 카드 이름입니다.                             |
| symbol\_img  | string | 카드에 사용하는 이미지 URL 주소입니다.               |
| cards        | array  | 각 카드 정보를 담은 `object` 배열입니다.           |
| next\_cursor | string | 카드가 100개 이상이면 다음 100개 정보를 불러올 커서값입니다. |

**Response Details for** `cards[i]`

| 이름                | 타입     | 설명                                                                      |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| created\_at       | number | 카드가 발행된 시간입니다.                                                          |
| updated\_at       | number | 카드가 업데이트된 시간입니다.                                                        |
| owner             | string | 이 계정 [EOA](https://docs.kaia.io/ko/learn/accounts/) 주소입니다.              |
| sender            | string | 이 계정으로 카드를 보낸 사람의 [EOA](https://docs.kaia.io/ko/learn/accounts/) 주소입니다. |
| card\_id          | number | 카드 ID입니다.                                                               |
| card\_uri         | string | 카드 메타데이터가 담긴 JSON 파일 URL입니다.                                            |
| transaction\_hash | string | 카드를 발행한 스마트 컨트랙트 트랜잭션 해시입니다.                                            |

자세한 내용은 [튜토리얼1](/tutorial/tutorial-card-minting.md#get-card-information), [튜토리얼2](/tutorial/tutorial-card-minting.md#get-extra-card-information)를 확인하십시오.

#### Delete Card <a href="#delete-card" id="delete-card"></a>

## Delete Card

<mark style="color:red;">`DELETE`</mark> `https://api.klipwallet.com/v2/wallet/nft`

발행한 카드를 삭제합니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                                | Type   | Description                                     |
| --------------------------------------------------- | ------ | ----------------------------------------------- |
| pin<mark style="color:red;">\*</mark>               | string | 서명에 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다. |
| card\_id<mark style="color:red;">\*</mark>          | number | 카드 ID입니다.                                       |
| contract\_address<mark style="color:red;">\*</mark> | string | 카드를 발행한 SCA 주소입니다.                              |

{% tabs %}
{% tab title="200 " %}

```
{
    "hash": "0x2d26f602cfbb4c662931592bf2c4ee18d29f09683be5b9e8d589ff935fca0b97"
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
카드 삭제에 실패하였습니다. 정확한 정보를 확인하기 위해 현재 소유한 카드 목록을 확인하십시오.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

```
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
발행한 카드만 삭제할 수 있으며, 다른 사람에게 보낸 카드는 삭제할 수 없습니다.\
카드를 삭제해도 카드 이미지는 삭제되지 않습니다.
{% 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"
```

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#delete-card)을 확인하십시오.

#### Approve Escrow <a href="#approve-escrow" id="approve-escrow"></a>

## Approve Escrow

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/escrow/approve`

카드 전송 에스크로 사용을 허용합니다. 카드 전송 에스크로 기능을 사용하기 위해서는 최초에 1회, 필수적으로 호출해야하는 API입니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                                | Type   | Description                                     |
| --------------------------------------------------- | ------ | ----------------------------------------------- |
| pin<mark style="color:red;">\*</mark>               | string | 서명에 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다. |
| contract\_address<mark style="color:red;">\*</mark> | string | 카드를 발행한 SCA 주소입니다.                              |

{% tabs %}
{% tab title="200 " %}

```
{
  "fail_count": 0,
  "tx_hash": "string"
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

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

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#approve-escrow)을 확인하십시오.

#### Get Escrow Approval Status <a href="#get-approve-escrow-information" id="get-approve-escrow-information"></a>

## Get Escrow Approval Status

<mark style="color:blue;">`GET`</mark> `https://api.klipwallet.com/v2/escrow/approve`

카드 전송 에스크로 사용 동의 여부를 조회합니다.

#### Query Parameters

| Name                                                | Type   | Description         |
| --------------------------------------------------- | ------ | ------------------- |
| contract\_address<mark style="color:red;">\*</mark> | string | 카드를 발행하는 SCA 주소입니다. |

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

{% tabs %}
{% tab title="200 " %}

```
{
  "approve": true
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

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

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#get-approve-escrow)을 확인하십시오.

#### Create Escrow <a href="#create-escrow" id="create-escrow"></a>

## Create Escrow

<mark style="color:green;">`POST`</mark> `https://api.klipwallet.com/v2/escrow`

카드 전송 에스크로를 실행하고, Klip 사용자가 카드를 지급받을 수 있는 링크가 생성됩니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                                | Type   | Description                                        |
| --------------------------------------------------- | ------ | -------------------------------------------------- |
| pin<mark style="color:red;">\*</mark>               | string | 서명에 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다.    |
| card\_ids<mark style="color:red;">\*</mark>         | array  | 카드 ID들이 담긴 `number` 배열입니다. 최대 100개의 원소를 담을 수 있습니다. |
| contract\_address<mark style="color:red;">\*</mark> | string | 카드를 발행한 SCA 주소입니다.                                 |

{% 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": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
보유중인 카드만 에스크로 전송을 실행 할 수 있으며, 다른 사람에게 보낸 카드는 전송할 수 없습니다.\
에스크로를 수행한 카드는 에스크로 카드 조회를 통해 확인할 수 있습니다.
{% 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"
```

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#create-escrow)을 확인하십시오.

#### Get Cards in Escrow <a href="#escrow-information" id="escrow-information"></a>

## Get Cards in Escrow

<mark style="color:blue;">`GET`</mark> `https://api.klipwallet.com/v2/escrow`

에스크로 카드 목록 조회.

#### Query Parameters

| Name                                                | Type   | Description                                                                                                                                                                         |
| --------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contract\_address<mark style="color:red;">\*</mark> | string | 카드를 발행하는 SCA 주소입니다.                                                                                                                                                                 |
| cursor                                              | string | 카드 개수가 100개 이상이면 다음 100개 정보를 받는 커서값입니다. 일반적으로 카드 개수가 100개를 초과한다면 1번 호출 시 100개의 결과와 `next_cursor` 값을 받습니다. 나머지 카드를 조회하려면 `next_cursor` 값을 query 파라미터 `cursor`에 전달하여 API를 다시 호출해야합니다. |

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | 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": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

```
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
cursor에 대한 자세한 내용은 [pagination](/basics.md#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**

| 이름           | 타입     | 설명                                    |
| ------------ | ------ | ------------------------------------- |
| name         | string | 카드 이름입니다.                             |
| symbol\_img  | string | 카드에 사용하는 이미지 URL 주소입니다.               |
| cards        | array  | 각 카드 정보를 담은 `object` 배열입니다.           |
| next\_cursor | string | 카드가 100개 이상이면 다음 100개 정보를 불러올 커서값입니다. |

**Response Details for** `cards[i]`

| 이름                | 타입     | 설명                                                                      |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| created\_at       | number | 카드가 발행된 시간입니다.                                                          |
| updated\_at       | number | 카드가 업데이트된 시간입니다.                                                        |
| owner             | string | 이 계정 [EOA](https://docs.kaia.io/ko/learn/accounts/) 주소입니다.              |
| sender            | string | 이 계정으로 카드를 보낸 사람의 [EOA](https://docs.kaia.io/ko/learn/accounts/) 주소입니다. |
| card\_id          | number | 카드 ID입니다.                                                               |
| card\_uri         | string | 카드 메타데이터가 담긴 JSON 파일 URL입니다.                                            |
| transaction\_hash | string | 카드를 발행한 스마트 컨트랙트 트랜잭션 해시입니다.                                            |

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#get-escrow)을 확인하십시오.

#### Cancel Escrow <a href="#cancel-escrow" id="cancel-escrow"></a>

## Cancel Escrow

<mark style="color:red;">`DELETE`</mark> `https://api.klipwallet.com/v2/escrow`

카드 전송 에스크로를 취소합니다.

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name                                                | Type   | Description                                        |
| --------------------------------------------------- | ------ | -------------------------------------------------- |
| pin<mark style="color:red;">\*</mark>               | string | 서명에 사용할 핀 번호를 해시(SHA256)한 64자리 Hex String 값입니다.    |
| card\_ids<mark style="color:red;">\*</mark>         | array  | 카드 ID들이 담긴 `number` 배열입니다. 최대 100개의 원소를 담을 수 있습니다. |
| contract\_address<mark style="color:red;">\*</mark> | string | 카드를 발행한 SCA 주소입니다.                                 |

{% tabs %}
{% tab title="200 " %}

```
{
  "fail_count": 0,
  "tx_hash": "string"
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="기타" %}

```
카드 에스크로 취소에 실패하였습니다. 정확한 정보를 확인하기 위해 현재 에스크로된 카드 목록을 확인하십시오.
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500 " %}

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

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
에스크로된 카드만 취소할 수 있으며, 이미 지급된 카드는 삭제할 수 없습니다. 취소된 카드는 보유 목록으로 반환됩니다.
{% 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"
```

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#cancel-escrow)을 확인하십시오.

#### Get Transaction Result <a href="#transasction-result" id="transasction-result"></a>

## Get Transaction Result

<mark style="color:blue;">`GET`</mark> `https://api.klipwallet.com/v2/wallet/receipt`

트랜잭션 처리 결과가 블록에 최종 성공으로 기록됐는지 여부를 조회합니다.

#### Query Parameters

| Name                                       | Type   | Description       |
| ------------------------------------------ | ------ | ----------------- |
| tx\_hash<mark style="color:red;">\*</mark> | string | 조회할 트랜잭션 해시 값입니다. |

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | JWT 형식 인증 토큰입니다. |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

{% tabs %}
{% tab title="200 " %}

```
{
  "success": true
}
```

{% endtab %}

{% tab title="400 " %}
{% tabs %}
{% tab title="400" %}

```
"bad request": 잘못된 요청입니다. Request 파라미터를 다시 확인하십시오.
```

{% endtab %}

{% tab title="4700" %}

```
"no transaction receipt": 트랜잭션 해시가 존재하지 않습니다. 아직 트랜잭션이 처리되지 않았거나 잘못된 트랜잭션 해시 값입니다.
```

{% 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**

| 이름      | 타입   | 설명             |
| ------- | ---- | -------------- |
| success | bool | 트랜잭션 성공 여부입니다. |

자세한 내용은 [튜토리얼](/tutorial/tutorial-card-minting.md#get-receipt)을 확인하십시오.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.klipwallet.com/rest-api/rest-api-card-minting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.