Introduction

LINE Blockchain Developers provides API to make use of Finschia. LINE Blockchain Developers API allows you to tap into a series of blockchain features including creating, transferring, and burning item tokens (NFT), retrieving token information, managing metadata and integrating DOSI Wallets.

Those of you who want to develop Finschia-based services

LINE Blockchain Developers API protocol, dos and don'ts

LINE Blockchain Developers API is RESTful and uses the HTTPS protocol. Thus, you can call APIs regardless of platform if it supports HTTP.

Yet, you need a valid API Key and API secret to call an API. You can get them from the LINE Blockchain Developers console. Refer to the Request header for how to use an API key and API secret to call an API.

Endpoint

The format of LINE Blockchain Developers API endpoints is as follows.

https://{host}/{api-path}?{query-string}  

• host is the host of the API server, and it can be selected from below.
  • Testnet: test-api.blockchain.line.me
  • Mainnet: api.blockchain.line.me
• api-path is the path of the API to be called. You can check out the path in each API endpoint specification. API version is also a part of api-path.
• query-string is a set of query parameters. Each parameter is a pair of key=value, distinguished by '&'.  

Request

LINE Blockchain Developers API requests comply with the following conventions.

• All API requests are sent via HTTPS.
• Parameters can be sent as a path, query, or request body in JSON.

  From LINE Blockchain Developer v2.8.0, there is no need to do URI encoding for query parameters.

• All API requests must be signed, except for the endpoint to retrieve server time, and API requests with an invalid signature are rejected. Refer to Authentication for more information.
• Any request exceeding the rate limit will return an error.
  • The default rate limit is 50 TPS in Mainnet and 20 TPS in Testnet for all service plans.
  • Refer to the overview of API reference or each endpoint to check if they are affected by the rate limit.
  • The rate limit is subject to change.

Request header

Those API endpoints using the request body as a parameter should set Content-Type as "application/json" in the HTTP header.

Those API endpoints that require authentication should send service-api-key, signature, timestamp, and nonce in the header. Refer to Authentication for more information on corresponding values and validation methods.

The Host header when using the proxy server

In principle, Host is a header required for all HTTP/1.1 requests and should have the same base URL as the requested server. Most HTTP clients automatically enter this information, but it may change if you use a proxy server. Make sure to use the base URL of the requested server.

• Testnet: test-api.blockchain.line.me
• Mainnet: api.blockchain.line.me

You can check the details of HTTP request header Host in W3C RFC 2616.

Next is a sample request header.

Host: api.blockchain.line.me
Content-Type: application/json
service-api-key: <your api key>
signature: <the user generated message signature>
timestamp: <a timestamp for your request>
nonce: <a nonce value>

Request body

Some API endpoints can send the parameters in the request body, which should be in JSON format, using a camel case for key names.

Next is a sample request body.

{
  "ownerAddress": "link000000000000000000000000000000000000000",
  "ownerSecret": "uuOtZ+RIgn009pDlnx+fmqlH9nzYJMvoUPE9Kz37m4w=",
  "toAddress": "link000000000000000000000000000000000000000",
  "value": "1234567890"
}

Response

LINE Blockchain Developers API sends the response with HTTP status codes, response headers, and response body.

Response header

The response header can include information on the rate limit when calling API endpoints with limited requests.

Attribute	Type	Description	Required
X-RateLimit-Replenish-Rate	Integer	The number of available requests per second; Rate limit	Optional
X-RateLimit-Remaining	Integer	The number of remaining requests available in the next second	Optional

Response body

The response body is a JSON object with details on the result including the following attributes.

Attribute	Type	Description	Required
responseTime	Timestamp	Response time of the API server, displayed in milliseconds since Unix Epoch at UTC	Required
statusCode	Integer	Response result. Refer to API status code.	Required
statusMessage	String	Status message corresponding to statusCode	Required
responseData	Object	Actual data from the request	Optional

Success response

For a successful API request, the server returns the HTTP status code such as "200 OK" or "202 Accepted". In the response body of a successful API request, statusCode is set as "1000" or "1002", and actual response data are included in responseData.

Next is a sample response body of a successful API request.

{
  "responseTime": 1581866404449,
  "statusCode": 1000,
  "statusMessage": "Success",
  "responseData": {
    ...
  }
}

API requests generating a transaction return "202 Accepted" when the request is successful. This means that the request is accepted. You need to note that it doesn't mean the transaction is confirmed. Actual result of the transaction from the request can be received only when the transaction is confirmed. Refer to Callback response for more information.

Error response

When there is an error with an API request, the server treats it as a failure and returns a status code for the cause of the error. The response body of a failed API request returns information on the error without responseData.

Next is a sample response body of a failed API request.

{
    "responseTime": 1575357343316137,
    "statusCode": 4010,
    "statusMessage": "Service-api-key required"
}

Status code

LINE Blockchain Developers API provides the API status code and message per HTTP status code. Refer to the following table.

HTTP status code	statusCode	statusMessage	Description
200	1000	Success	The API is successfully requested.
202	1002	Accepted	Transaction request accepted. This is regarding transaction requests only. Transaction results should be checked with the transaction hash.
202	1020	Transaction not confirmed	The transaction with the requested txHash is not confirmed yet.
400	4000	Bad request / Bad request: ${cause}	An request sent by the client has invalid data. More detailed cause(${cause}) may be returned with the response.
400	4002	Address and UserId both in request	Both toAddress and toUserId are entered in the request body.
400	4010	Service-api-key required	service-api-key is missing in the HTTP header.
400	4011	Signature required	signature is missing in the HTTP header.
400	4016	Invalid wallet address: ${walletAddress}	Invalid wallet address is entered.
400	4017	Invalid wallet secret	Invalid wallet secret is entered.
400	4018	Owner wallet only available	ownerAddress entered doesn't match the owner wallet address.
400	4021	Timestamp required	timestamp is missing in the HTTP header.
400	4022	Invalid timestamp format	timestamp format in the HTTP header is incorrect.
400	4023	Request timestamp too late	timestamp in the HTTP header is more than 5 minutes behind the serverTime. (Server time > requested Timestamp + 5 mins)
400	4024	Request timestamp too fast	timestamp in the HTTP header is more than 5 minutes ahead of serverTime. (Server time + 5 mins < requested Timestamp)
400	4031	Nonce required	nonce is missing in the HTTP header.
400	4032	Duplicated nonce	Same nonce used within 11 minutes is reused.
400	4033	Invalid nonce format	nonce format in the HTTP header is incorrect.
400	4060	Transaction not acceptable	The format of requested transaction is incorrect.
400	4100	Please find responseData for details	An error occurred while processing the FINSCHIA Voucher API request. The cause of the error is included in responseData. (FINSCHIA Voucher API is a closed API only available to the services participating in the FINSCHIA Reward program.)
400	4295	Too many contract creation request over limit	The maximum number of item token contracts allowed for the service is exceeded.
401	4012	Service-api-key not found	service-api-key in the HTTP header is not matched with API key matching.
401	4013	Invalid signature	signature in the HTTP header is invalid.
401	4014	Service experiencing an issue. ${cause}	Service is experiencing an issue. One of the following (${cause}) may be returned. - Service_Suspended - Service_Overdue - Service_Sanction - Service_Terminated - Service_Overuse
401	4015	Service wallet not owned by the given service-api-key	The service wallet can't be used for the service with the given service-api-key.
403	4034	Item token Proxy already set up	User already set up the proxy for the item token.
403	4035	Requesting user blocked from DOSI Wallet	Transaction can't be committed as the requesting user's DOSI Wallet account is blocked.
403	4036	Authorization not completed	User hasn't completed the DOSI Wallet authority process.
403	4037	Target user blocked from DOSI Wallet: ${userId}	Target user (${userId}) can't receive as the DOSI Wallet account is blocked.
403	4039	DOSI Wallet user account locked: ${userId}	The DOSI Wallet account of the user (${userId}) is locked.
403	4082	Not registered test user: ${userId}	[Testnet only] Can't be transferred to the user who isn't registered as a test user.
403	4083	Not registered test user wallet or service wallet: ${walletAddress}	[Testnet only] Can only be transferred to either the registered test user's wallet or the service wallet.
404	4001	Service not found	Service with the given service ID is not found.
404	4038	User is not a DOSI Wallet member: ${userId}	${userId} hasn't registered with DOSI Wallet.
404	4040	Transaction not found	Transaction with the given txHash is not found.
404	4041	Service wallet not found: ${walletAddress}	Service wallet with the given ${walletAddress} is not found.
404	4042	Non-fungible token not owned	NFT with the given contractId, tokenType, and tokenIndex is not found.
404	4044	Item token contract not found	The given contractId is not found.
404	4045	Item token type not found	The given tokenType is not found in the contract.
404	4046	Item token index not found	The given tokenIndex is not found under the tokenType in the contract.
404	4048	Request session token not found	The request session token doesn't exist or is expired.
404	4049	Non fungible item token burned	The given NFT already burnt.
404	4051	User not found: ${userId}	User with the given ${user ID} is not found. (This message is also returned for users who have withdrawn from the service.)
404	4061	Multi message out of bound	Multi message size exceeded the limit.
413	4131	Payload too large	The request body exceeded the limit that the server could handle.
415	4151	Unsupported media type	Content-type in the HTTP header isn't "application/json" or the body of the HTTP request isn't in JSON format.
429	4291	Too many requests from a single wallet	There are too many transaction requests from a single wallet, so they can't be processed.
429	4292	No waiting area available	The requested transaction (message) can't be queued for processing. Try again later for an idle node.
429	4293	Rate limit exceeded	The rate limit for the service is exceeded.
429	4294	Too many request over limit	The rate limit for the service is exceeded.
500	5000	Internal server error	Testnet: An internal server error occurred, and the transaction hasn't been broadcast. Mainnet: An internal server error occurred. We won't guarantee that the transaction hasn't been broadcast in Mainnet.
500	5001	Internal server error (possible broadcast of transaction)	An internal server error occurred but the transaction might be broadcast.
501	0	Not implemented	Access to unimplemented API attempted.
503	5030	Service temporarily unavailable	Service is temporarily unavailable due to an internal problem. It will be restored soon.