API Reference

KP API Documentation

AI K LINK의 KP (Key Point) 시스템 API 명세입니다. 충전, 구매, 출금, 잔액 조회, 거래 내역 5개 엔드포인트를 제공합니다. 모든 엔드포인트는 인증이 필요하며, Bearer 토큰을 Authorization 헤더에 포함해야 합니다.

Base URL

https://www.aiklink.com

인증

모든 요청에 Authorization: Bearer YOUR_TOKEN 헤더가 필요합니다. 토큰은 로그인 후 /api/auth/token에서 발급받을 수 있습니다.

POST/api/kp/chargePreparing

KP 충전

PayPal 결제 후 KP를 충전합니다. 결제 검증이 완료되면 잔액이 증가합니다.

Request Body

Field	Type	Required	Description
`userId`	string	Yes	충전 대상 사용자 ID
`amountKrw`	number	Yes	원화 결제 금액 (1,000 단위)
`paymentId`	string	Yes	PayPal 결제 ID

Response Example

{
  "success": true,
  "data": {
    "userId": "user_abc123",
    "charged": 10500,
    "newBalance": 15200,
    "transactionId": "txn_20260411_001"
  }
}

Error Codes

400amountKrw must be >= 1000

401Unauthorized

402Payment verification failed

POST/api/kp/purchasePreparing

Kit 구매

Kit 컴포넌트를 KP로 구매합니다. 잔액 부족 시 402 에러를 반환합니다.

Request Body

Field	Type	Required	Description
`userId`	string	Yes	구매자 사용자 ID
`kitSlug`	string	Yes	구매할 Kit 슬러그
`kitType`	string	Yes	Kit 타입 (agent\|skill\|hook\|...)

Response Example

{
  "success": true,
  "data": {
    "purchaseId": "pur_20260411_042",
    "kit": "planner",
    "priceKp": 30,
    "remainingBalance": 15170,
    "downloadUrl": "/api/kp/download/pur_20260411_042"
  }
}

Error Codes

400Invalid kitSlug or kitType

401Unauthorized

402Insufficient KP balance

404Kit not found

POST/api/kp/withdrawPreparing

KP 출금

판매 수익 KP를 원화로 환전하여 PayPal로 출금 요청합니다. 최소 5,000 KP 이상.

Request Body

Field	Type	Required	Description
`userId`	string	Yes	출금 요청 사용자 ID
`amountKp`	number	Yes	출금할 KP 금액 (최소 5,000)
`paypalEmail`	string	Yes	수금 PayPal 이메일

Response Example

{
  "success": true,
  "data": {
    "withdrawId": "wd_20260411_007",
    "amountKp": 50000,
    "amountKrw": 50000,
    "status": "pending",
    "estimatedArrival": "2026-04-14"
  }
}

Error Codes

400amountKp must be >= 5000

401Unauthorized

402Insufficient KP balance

422PayPal email not verified

GET/api/kp/balancePreparing

잔액 조회

현재 사용자의 KP 잔액과 원화 환산 금액을 조회합니다.

Response Example

{
  "success": true,
  "data": {
    "userId": "user_abc123",
    "balanceKp": 15200,
    "balanceKrw": 15200,
    "pendingWithdraw": 0
  }
}

Error Codes

401Unauthorized

GET/api/kp/historyPreparing

거래 내역

KP 충전, 구매, 판매 수익, 출금 등 전체 거래 내역을 페이지네이션으로 조회합니다.

Query Parameters

Field	Type	Required	Description
`page`	number	No	페이지 번호 (기본 1)
`limit`	number	No	페이지당 건수 (기본 20, 최대 100)
`type`	string	No	필터: charge \| purchase \| sale \| withdraw

Response Example

{
  "success": true,
  "data": [
    {
      "id": "txn_20260411_001",
      "type": "charge",
      "amountKp": 10500,
      "balanceAfter": 15200,
      "createdAt": "2026-04-11T10:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

Error Codes

401Unauthorized

400Invalid page or limit parameter