POSTPublicfinance-internal-futures-contract

Domestic Futures Contracts

Documentation

API Introduction

This API provides a service for querying basic contract information for the domestic futures market (onshore). Developers can input a standard futures product code (symbol) to retrieve the corresponding contract list, including the contract code and its full Chinese name (e.g., "Shanghai Crude Oil 2407"). The data originates from an upstream service on Alibaba Cloud Marketplace and is suitable for business systems requiring standardized futures product identifiers.

Use Cases

Financial Terminal Development: Display standardized contract names in trading software or market quote systems.
Data Cleaning and Mapping: Convert abbreviated codes from internal systems into common Chinese contract names.
Quantitative Strategy Backtesting: Automatically match historical contract codes and names when building strategies.
Information Aggregation Platforms: Ensure that displayed futures product names comply with domestic market standards.

Request and Response Description

Request Method: POST Request Parameters:

symbol (Required, string): Futures product code. Refer to official or upstream provided code tables, e.g., "SC0".

Response Results:

code (number): Status code, 200 indicates success.
msg (string): Status description.
taskNo (string): Unique tracking number for this request.
data.list (array): Array of contract lists.
symbol (string): Contract code.
name (string): Full Chinese contract name, including product type, exchange, and expiry month information.

Integration Suggestions

Code Standardization: Ensure that the symbol passed strictly conforms to the format defined by the upstream service, as it is case-sensitive. Otherwise, the query may return empty results.
Caching Strategy: Futures contract lists change infrequently (mainly during contract rollovers or new listings). It is recommended to cache the returned results locally (e.g., with a TTL of 24 hours) to reduce API call frequency and improve response speed.
Error Handling: Always check the returned code field. If the status code is not 200, log the error or prompt the user based on the msg message to avoid null pointer exceptions when directly parsing data.

Integration Examples

Includes ready-to-use Shell, Python, Go, Java, and PHP examples for direct integration.

Request Example

{
  "symbol": "期货品种代码，详见代码表"
}

Response Example

{
  "msg": "成功",
  "taskNo": "075556736233047430019762",
  "code": 200,
  "data": {
    "list": [
      {
        "symbol": "SC0",
        "name": "上海原油2407"
      }
    ]
  }
}

Request Fields

The fields below are derived from example JSON for integration reference only.

Path	Type	Sample
type	string	object
properties	object	{...}
properties.symbol	object	{...}
properties.symbol.type	string	string
properties.symbol.description	string	期货品种代码，详见代码表
required	array	"symbol"
required[]	string	symbol

Response Fields

The fields below are derived from example JSON for integration reference only.

Path	Type	Sample
type	string	object
properties	object	{...}
properties.msg	object	{...}
properties.msg.type	string	string
properties.msg.example	string	成功
properties.msg.description	string	返回码对应描述
properties.taskNo	object	{...}

curl --request POST \ --url 'https://openapi.toolkk.com/v1/finance-internal-futures-contract' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_API_KEY' \ --data '{\n "symbol": "期货品种代码，详见代码表"\n}'

import os import requests url = "https://openapi.toolkk.com/v1/finance-internal-futures-contract" payload = { "symbol": "期货品种代码，详见代码表" } headers = { "Content-Type": "application/json", "X-API-Key": os.getenv("TOOLKK_API_KEY", "YOUR_API_KEY"), } response = requests.request("POST", url, headers=headers, json=payload, timeout=30) response.raise_for_status() print(response.json())

package main import ( "bytes" "fmt" "io" "net/http" ) func main() { endpoint := "https://openapi.toolkk.com/v1/finance-internal-futures-contract" payload := []byte("{\n \"symbol\": \"期货品种代码，详见代码表\"\n}") req, err := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload)) if err != nil { panic(err) } req.Header.Set("Content-Type", "application/json") req.Header.Set("X-API-Key", "YOUR_API_KEY") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { panic(err) } fmt.Println(string(body)) }

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class ToolkkExample { public static void main(String[] args) throws Exception { String payload = "{\n \"symbol\": \"期货品种代码，详见代码表\"\n}"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://openapi.toolkk.com/v1/finance-internal-futures-contract")) .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .header("Content-Type", "application/json") .header("X-API-Key", "YOUR_API_KEY") .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } }

<?php $endpoint = 'https://openapi.toolkk.com/v1/finance-internal-futures-contract'; $payload = "{\n \"symbol\": \"期货品种代码，详见代码表\"\n}"; $ch = curl_init($endpoint); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'X-API-Key: YOUR_API_KEY', ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); if ($response === false) { throw new RuntimeException(curl_error($ch)); } curl_close($ch); echo $response;

Domestic Futures Contracts

Documentation

API Introduction

Use Cases

Request and Response Description

Integration Suggestions

Integration Examples

Request Example

Response Example

Request Fields

Response Fields

Shell Example

Python Example

Go Example

Java Example

PHP Example

Try it online