API 사용

ChainZ API를 사용하는 방법에 대해 설명합니다.

준비 사항

1. ChainZ Service 가입 후, 인증 정보 생성을 통해 Authorization 정보와 API 키를 갖고 있어야 합니다.

2. Authorization 정보를 이용하여 ChainZ API 인증 서버로 부터 액세스 토큰을 발급 받아야 합니다.

ChainZ 를 사용하기 위해서는 Chain ID가 필요합니다.

ChainZ 테스트넷의 Chain ID: 8768cb29-2417-4281-84b1-924b82ebb720 ChainZ 메인넷의 Chain ID: 별도 문의(support@chainz.biz)

API 사용 절차

Account API 사용하기

공통 설정

ChainZ Account API URL: account-api.chainz.biz

사전 조건

Chain ID 필요

입력 정보

액세스 토큰 & API 키
User ID - 사업자의 계정 식별 정보
Chain ID - Blockchain 식별 정보

1. 사용자의 Blockchain account를 생성하려면 터미널에서 다음과 같이 입력합니다.

# Account API(Account 생성) 사용 예시 - Request

curl -X POST \
  "https://{ChainZ Account API URL}/api/v1/accounts" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer {액세스 토큰}" \
  -H  "x-api-key: {API 키}"
  -H 'Content-Type: application/json' \
  -d '{
  "userId": "{User ID}",
  "chainId": "{Chain ID}"
}'

# Account API(Account 생성) 사용 예시 - Response

{
  "id": "e0a476e3-8a1f-41a9-b67d-98703e816fe7",
  "userId": "test",
  "chainId": "8768cb29-2417-4281-84b1-924b82ebb720",
  "address": "0x508b8bc6c521e24c2eedd0f2280c7021b752efdb",
  "status": "ACTIVE"
}

2. 사용자의 Blockchain account 정보를 보려면 터미널에서 다음과 같이 입력합니다.

# Account API(Account 조회) 사용 예시 - Request

curl -X GET \
    "https://{ChainZ Account API URL}/api/v1/accounts?userId={User ID}&chainId={Chain ID}" \
    -H  "accept: application/json" \
    -H  "Authorization: Bearer {액세스 토큰}" \
    -H  "x-api-key: {API 키}"

# Account API(Account 조회) 사용 예시 - Response

{
  "totalCount": 1,
  "data": [
    {
      "providerCode": "A1B1C1D1",
      "id": "051f3e8d-67ab-4d26-a42e-805b3b048e86",
      "userId": "user0001",
      "chainId": "5a9d9e56-ef2b-401c-a026-cedeed1ce457",
      "address": "0x5b55bac99d5d6678a35d1f9bd1ede1ad799d6902",
      "status": "ACTIVE",
      "createdAt": "2021-05-19T20:19:48.000Z",
      "updatedAt": "2021-05-20T05:19:48.000Z"
    }
  ]
}

Contract API 사용하기

공통 설정

ChainZ Contract API URL: contract-api.chainz.biz

사전 조건(Smart Contract 빌드 정보 등)

Smart Contract의 artifacts 중 ABI 및 bytecode 필요

입력 정보

액세스 토큰 & API 키
ABI - Smart Contract build artifacts
Bytecode - Smart Contract build artifacts

1. Smart Contract 빌드 정보(Artifacts) 등록

# Contract API(Smart Contract 배포)사용 예시 - Request

curl -X 'POST' \
  'https://{ChainZ Contract API URL}/api/v1/contract/artifacts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {액세스 토큰}' \
  -H 'x-api-key: {API 키}' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "storage",
  "version": "1.0.0",
  "abi": [{"inputs":[],"name":"retrieve","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"num","type":"uint256"}],"name":"store","outputs":[],"stateMutability":"nonpayable","type":"function"}],
  "bytecode": "608060405234801561001057600080fd5b5061012f806100206000396000f3fe6080604052348015600f57600080fd5b506004361060325760003560e01c80632e64cec11460375780636057361d146051575b600080fd5b603d6069565b6040516048919060c2565b60405180910390f35b6067600480360381019060639190608f565b6072565b005b60008054905090565b8060008190555050565b60008135905060898160e5565b92915050565b60006020828403121560a057600080fd5b600060ac84828501607c565b91505092915050565b60bc8160db565b82525050565b600060208201905060d5600083018460b5565b92915050565b6000819050919050565b60ec8160db565b811460f657600080fd5b5056fea264697066735822122062db17618d746a1967495ede611efc2c1e881cb29cbd6b40b23bd35a720c134c64736f6c63430008010033"
}'

# Contract API(Smart Contract 배포) 사용 예시 - Response

{
  "id": "e5024600-c7eb-4327-959a-3ef8e09f0152",
  "providerCode": "A1B1C1D1",
  "name": "storage",
  "version": "1.0.0",
  "abi": [
    {
      "inputs": [],
      "name": "retrieve",
      "outputs": [
        {
          "internalType": "uint256",
          "name": "",
          "type": "uint256"
        }
      ],
      "stateMutability": "view",
      "type": "function"
    },
    {
      "inputs": [
        {
          "internalType": "uint256",
          "name": "num",
          "type": "uint256"
        }
      ],
      "name": "store",
      "outputs": [],
      "stateMutability": "nonpayable",
      "type": "function"
    }
  ],
  "bytecode": "608060405234801561001057600080fd5b5061012f806100206000396000f3fe6080604052348015600f57600080fd5b506004361060325760003560e01c80632e64cec11460375780636057361d146051575b600080fd5b603d6069565b6040516048919060c2565b60405180910390f35b6067600480360381019060639190608f565b6072565b005b60008054905090565b8060008190555050565b60008135905060898160e5565b92915050565b60006020828403121560a057600080fd5b600060ac84828501607c565b91505092915050565b60bc8160db565b82525050565b600060208201905060d5600083018460b5565b92915050565b6000819050919050565b60ec8160db565b811460f657600080fd5b5056fea264697066735822122062db17618d746a1967495ede611efc2c1e881cb29cbd6b40b23bd35a720c134c64736f6c63430008010033",
  "upgradable": false,
  "status": "CREATED",
  "createdAt": "2021-05-31T03:33:30.531Z",
  "updatedAt": "2021-05-31T03:33:30.531Z"
}

Transaction API 사용하기하

공통 설정

ChainZ Transaction API URL: tx-api.chainz.biz

사전 조건

Chain ID 필요
서명이 필요한 Transaction 일 경우
- Account API를 통한 Account 생성(From Address)
Contract Transaction 일 경우
- Contract API 를 통해 등록된 Contract ID

입력 정보

액세스 토큰 & API 키
Chain ID - Blockchain 식별 정보
Client Request ID - Request 의 사업자 고유 식별 정보
...
Request ID - Request 의 고유한 식별 정보
Callback URL - Callback 받을 서버 HTTP Endpoint 주소. (Optional)

1. Transaction API를 사용하여 Transaction을 전송합니다. Response로 받은 ID 값(RequestID)으로 Transaction 의 처리 상태를 확인할 수 있습니다.

# Transaction API 사용 예시 - Request

curl -X POST "https://{ChainZ Transaction API URL}/api/v1/transactions/contract-deployment" \
    -H  "accept: application/json" \
    -H  "x-api-key: {API 키}" \
    -H  "Authorization: Bearer {액세스 토큰}" \
    -H  "Content-Type: application/json" \
    -d "{\"chain\":\"3033f611-5b06-4661-a4d1-d375bd8e442c\",\"clientReqId\":\"3fa85f64-5717-4562-b3fc-2c963f66aff6\",\"maxRetry\":3,\"isSync\":false,\"params\":{\"from\":\"0xceed092e9d5b134d3aff067dc049b937d0facf4a\",\"contractId\":\"e5024600-c7eb-4327-959a-3ef8e09f0152\",\"initParams\":[]}}"

clientReqId(Client Request ID) 생성 규칙은 UUID(Universally Unique IDentifier: 범용 고유 식별자) 규칙을 따릅니다. 테스트용 UUID는 다음을 참고하여 생성하시기 바랍니다.

Transaction 전송 시에 UUID는 다르게 발송해야 합니다. 여러 번 테스트가 필요하면, 기존에 쓴 UUID에서 한 두개 문자만 변경한 후 테스트를 하세요.

# Transaction API 사용 예시 - Response

{
  "status": "REQUESTED",
  "log": "{\"type\":\"CONTRACT_DEPLOYMENT\",\"isSync\":false,\"maxRetry\":3}",
  "timestamp": "2021-05-31T05:07:27.706Z",
  "id": "07b28242-735d-49f1-a05f-357ee7a86682"
}

2. Transaction의 처리 상태를 조회하려면 다음과 같이 합니다.

Transaction 조회 API(/api/v1/transactions/{reqId}/logs)를 사용하여 Log 정보를 확인합니다.

# Transaction API(Tx Receipt 조회) 사용 예시 - Request

curl -X GET "https://{ChainZ Transaction API URL}/api/v1/transactions/{Request ID}/logs" \
    -H  "accept: application/json" \
    -H  "x-api-key: {API 키}" \
    -H  "Authorization: Bearer {액세스 토큰}"

# Transaction API(Tx Receipt 조회) 사용 예시 - Response

{
  "logList": [
    {
      "status": "REQUESTED",
      "log": "{\"type\":\"CONTRACT_DEPLOYMENT\",\"isSync\":false,\"maxRetry\":3}",
      "timestamp": "2021-05-31T04:52:21.593Z"
    },
    {
      "status": "SUCCEEDED",
      "log": "{\"type\":\"CONTRACT_DEPLOYMENT\",\"isSync\":false,\"maxRetry\":3,\"txReceipt\":{\"blockHash\":\"0x7ff42b2c456eb03d57a72e5e17a83da9316c43ea5363409870686eea9f726a9b\",\"blockNumber\":\"0x2bef4\",\"contractAddress\":\"0x72ede34c09a5aa7276b8d655223d35a38fcb79ce\",\"cumulativeGasUsed\":\"0x1d023\",\"from\":\"0xceed092e9d5b134d3aff067dc049b937d0facf4a\",\"gasUsed\":\"0x1d023\",\"logs\":[],\"logsBloom\":\"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\",\"status\":\"0x1\",\"to\":null,\"transactionHash\":\"0x7b0b826c5ec221a8dd616c17648e42b1e009e0efdc224ee63b5011c24da4ae64\",\"transactionIndex\":\"0x0\"}}",
      "timestamp": "2021-05-31T04:52:23.779Z"
    }
  ],
  "requestId": "c648c217-1260-4223-ba2c-9bdd0ee9b6e8",
  "pCode": "MW012345"
}

Response Data 의 status 정보가 'SUCCEEDED' 상태인 log 정보를 JSON Parsing하면 txReceipt정보에서 Transaction Receipt 확인이 가능합니다.

status가 'SUCCEEDED' 상태인 log를 JSON Parsing한 예시

{
  "type": "CONTRACT_DEPLOYMENT",
  "isSync": false,
  "maxRetry": 3,
  "txReceipt": {
    "blockHash": "0x7ff42b2c456eb03d57a72e5e17a83da9316c43ea5363409870686eea9f726a9b",
    "blockNumber": "0x2bef4",
    "contractAddress": "0x72ede34c09a5aa7276b8d655223d35a38fcb79ce",
    "cumulativeGasUsed": "0x1d023",
    "from": "0xceed092e9d5b134d3aff067dc049b937d0facf4a",
    "gasUsed": "0x1d023",
    "logs": [],
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "status": "0x1",
    "to": null,
    "transactionHash": "0x7b0b826c5ec221a8dd616c17648e42b1e009e0efdc224ee63b5011c24da4ae64",
    "transactionIndex": "0x0"
  }
}

txReceipt 정보 중, lockHash, blockNumber, transactionHash 정보를 가지고 Block Explorer에서 상세 정보를 확인 할 수 있습니다. 자세한 사항은 Block Explorer 사용 항목을 참고하시기 바랍니다.

Token API 사용하기

공통 설정

ChainZ Token API URL: token-api.chainz.biz

토큰 컨트랙트 배포

Token Contract를 배포 하기 위해 다음과 같이 입력합니다.

사전 조건

Token API 혹은 Account API를 통한 Sender Account 생성

입력 정보

Chain ID - Blockchain 식별 정보
Client Request ID - Request 의 사업자 고유 식별 정보
Sender - 토큰 컨트랙트 배포 계정
Owner - 토큰 컨트랙트 소유 계정이며, 초기 발행량 보유
Name - 토큰 이름
Symbol - 토큰 기호
Amount - 토큰 초기 발행량

# Token API 사용 예시(Token Contract Deployment) - Request

curl -X 'POST' \
  'https://{ChainZ Token API URL}/api/v1/chains/{Chain ID}/deployments' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {액세스 토큰}' \
  -H 'x-api-key: {API 키}' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientReqId": "3fa85f64-5717-4562-b3fc-29682566afa6",
  "sender": "0xf5bea619d23d0dbd95488aa3a8e3e76a8bc7568d",
  "owner": "0xf5bea619d23d0dbd95488aa3a8e3e76a8bc7568d",
  "name": "Test Token",
  "symbol": "TST",
  "amount": 100000000000
}'

# Token API 사용 예시(Token Contract Deployment) - Response

{
  "providerCode": "BQHQ6700",
  "chainId": "{Chain ID}",
  "clientReqId": "3fa85f64-5717-4562-b3fc-29682566afa6",
  "sender": "0xf5bea619d23d0dbd95488aa3a8e3e76a8bc7568d",
  "owner": "0xf5bea619d23d0dbd95488aa3a8e3e76a8bc7568d",
  "name": "Test Token",
  "symbol": "TST",
  "amount": 100000000000,
  "contractAddress": "0x46850f87a6df4fd83a7a70f7936da4b5129ce280",
  "txHash": "0x5c1cd8bb5ac9f129b73c4434adb2f7cd11905d58f690b03b1c87babe41c41ac8",
  "blockNumber": 2072977,
  "status": "SUCCESS",
  "createdAt": "2021-07-27T00:07:52.660Z"
}

토큰 전송

보유한 Token 을 상대방에게 전송하고자 할 경우 다음과 같이 입력합니다.

사전 조건

Token Contract 배포 주소
Token API 혹은 Account API를 통한 Account 생성(sender)

입력 정보

Chain ID - Blockchain 식별 정보
Contract Address - 토큰 컨트랙트 주소
Client Request ID - Request 의 사업자 고유 식별 정보
Sender - 토큰을 보내는 계정 주소
Recipient - 토큰을 받을 계정 주소
Amount - 전송할 토큰

# Token API 사용 예시(Token transfer) - Request

curl -X 'POST' \
  'https://{ChainZ Token API URL}/api/v1/chains/{Chain ID}/contracts/0x46850f87a6df4fd83a7a70f7936da4b5129ce280/transfer' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {Access Token}' \
  -H 'x-api-key: {API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientReqId": "3fa85f64-5717-4562-b3fc-2c962326afa6",
  "sender": "0xf5bea619d23d0dbd95488aa3a8e3e76a8bc7568d",
  "recipient": "0x82567d516a119a12262737397caff457f6725700",
  "amount": 1
}'

# Token API 사용 예시(Token transfer) - Response

{
  "providerCode": "BQHQ6700",
  "contractAddress": "0x46850f87a6df4fd83a7a70f7936da4b5129ce280",
  "chainId": {Chain ID},
  "clientReqId": "3fa85f64-5717-4562-b3fc-2c962326afa6",
  "sender": "0xf5bea619d23d0dbd95488aa3a8e3e76a8bc7568d",
  "recipient": "0x82567d516a119a12262737397caff457f6725700",
  "amount": 1,
  "txHash": "0x0318cff466e5965279f873e1ba1d2b4705e2dd7695d285a0909e927614d49c52",
  "blockNumber": 2073925,
  "status": "SUCCESS",
  "createdAt": "2021-07-27T00:39:33.283Z"
}

토큰 잔액 조회

보유한 Token의 잔액을 조회 하기 위해 다음과 같이 입력합니다.

사전 조건

Token Contract 배포 주소

입력 정보

Chain ID - Blockchain 식별 정보
Contract Address - 토큰 컨트랙트 주소
Owner Address - 잔액을 조회하고자 하는 계정 주소

# Token API 사용 예시(Token balanceOf) - Request

curl -X 'GET' \
  'https://{ChainZ Token API URL}/api/v1/chains/{Chain ID}/contracts/0x46850f87a6df4fd83a7a70f7936da4b5129ce280/balanceOf/0xf5bea619d23d0dbd95488aa3a8e3e76a8bc7568d' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {Access Token}' \
  -H 'x-api-key: {API Key}'

# Token API 사용 예시(Token balanceOf) - Response

100000000000

Previous액세스 토큰 발급 NextBlock Explorer 사용

Last updated 3 years ago

Was this helpful?