链上 API 命令列表

本文档描述了交易系统支持的所有链上 DEX REST API 命令及其请求/响应格式。

API 接口概览

• Sync: 同步命令
• Async: 异步命令
• WebSocket: 订阅事件

区块操作

接口	Sync	Async	WebSocket
Slot	√		√
SlotTimestamp	√

账号操作

接口	Sync	Async	WebSocket
Balances	√
Balance			√
Accounts	√

行情操作

接口	Sync	Async	WebSocket
JupQuote	√

交易操作

接口	Sync	Async	WebSocket
JupSwap	√

API 接口详情

完整的请求体

请求参数

参数	类型	是否必须	描述
account_id	Number	是	账户 ID
cmd/sub	Object	是	指令/事件

{
  "account_id": 0,
  "cmd": {
    "Sync": {
      "Dex": {
        "Accounts": ["SOL", "USDC", "USDT"]
      }
    },
    "Async": {
      "Dex": {
        "Balances": ["SOL", "USDC", "USDT"]
      }
    }
  },
  "sub": {
    "SubscribeDex": {
      "WebSocket": {
        "Slot": True
      }
    }
  }
}

区块操作

Slot (cmd)

获取最新区块高度

请求参数:

参数	类型	是否必须	描述
Slot	Bool	是	True/False

请求示例:

{
    "Sync": {
        "Dex": {
            "Slot": True
        }
    }
}

响应字段:

参数	类型	是否必须	描述
Ok	Number	是	区块高度

响应示例:

{
  "type": "Slot",
  "data": {
    "Ok": 123456789
  }
}

错误示例:

{
	"type": "Slot",
	"data": {
		"Err": {
			"error": "Slot params is nil",
			"location": ""
		}
	}
}

SlotTimestamp (cmd)

获取最新区块高度和时间戳

请求参数:

参数	类型	是否必须	描述
SlotTimestamp	Bool	是	True/False

请求示例:

{
    "Sync": {
        "Dex": {
            "SlotTimestamp": True
        }
    }
}

响应字段:

参数	类型	是否必须	描述
slot	Number	是	区块高度
timestamp	String	是	区块时间戳

响应示例:

{
  "type": "SlotTimestamp",
  "data": {
    "Ok": {
      "slot": 123456789,
      "timestamp": "100"
    }
  }
}

错误示例:

{
  "type": "SlotTimestamp",
  "data": {
    "Err": {
      "error": "SlotTimestamp params is nil",
      "location": ""
    }
  }
}

Slot (ws)

订阅最新区块高度事件

请求参数:

参数	类型	是否必须	描述
Slot	Bool	是	True/False

请求示例:

{
  "sub": {
    "SubscribeDex": {
      "WebSocket": {
        "Slot": true
      }
    }
  }
}

响应字段:

参数	类型	是否必须	描述
data	Number	是	区块高度

响应示例:

{
  "type": "Slot",
  "data": 123456789
}

账号操作

Balances (cmd)

获取链上账户的代币余额

请求参数:

参数	类型	是否必须	描述
Balances	[]String 数组	是	代币名称

请求示例:

{
  "Sync": {
    "Dex": {
      "Balances": ["SOL", "USDC"]
    }
  }
}

响应字段:

参数	类型	是否必须	描述
SOL	Float	是	SOL 代币余额
USDC	Float	是	USDC 余额

响应示例:

{
  "type": "Balances",
  "data": {
    "Ok": {
      "SOL": 1.068527248,
      "USDC": 8.09647
    }
  }
}

错误示例:

{
  "type": "Balances",
  "data": {
    "Err": {
      "error": "Balances params is nil",
      "location": ""
    }
  }
}

Balance (ws)

订阅最新区块高度事件

请求参数:

参数	类型	是否必须	描述
Balance	[]String 数组	是	代币名称

请求示例:

{
  "sub": {
    "SubscribeDex": {
      "WebSocket": {
        "Balance": ["SOL"]
      }
    }
  }
}

响应字段:

参数	类型	是否必须	描述
amount	Float	是	代币余额
symbol	String	是	代币名称
slot	Number	是	区块高度

响应示例:

{
  "type": "Balance",
  "data": {
    "Ok": {
      "amount": 0.1,
      "symbol": "SOL",
      "slot": 123456789
    }
  }
}

Accounts (cmd)

获取链上代币开户情况，否则无法交易代币

请求参数:

参数	类型	是否必须	描述
Accounts	[]String 数组	是	代币名称

请求示例:

{
  "Sync": {
    "Dex": {
      "Accounts": ["USDC", "USDT"]
    }
  }
}

响应字段:

参数	类型	是否必须	描述
Ok	[]String 数组	是	开户代币的数组

响应示例:

{
  "type": "Accounts",
  "data": {
    "Ok": ["USDC", "USDT"]
  }
}

错误示例:

{
  "type": "Accounts",
  "data": {
    "Err": {
      "error": "Accounts params is nil",
      "location": ""
    }
  }
}

行情操作

JupQuote (cmd)

进行代币链上询价

请求参数:

参数	类型	是否必须	描述
quoteId	String	是	询价 ID
inputToken	String	是	卖出代币名称
outputToken	String	是	买入代币名称
inAmount	Float	是	卖出代币数量

请求示例:

{
  "Sync": {
    "Dex": {
      "JupQuote": {
        "quoteId": "1",
        "inputToken": "USDC",
        "outputToken": "SOL",
        "inAmount": 10.1
      }
    }
  }
}

响应字段:

参数	类型	是否必须	描述
quoteId	String	是	询价 ID
inputToken	String	是	卖出代币名称
outputToken	String	是	买入代币名称
inAmount	Float	是	卖出代币数量
outAmount	Float	是	可买入代币数量
slippageBps	Number	是	建议交易滑点
contextSlot	Number	是	当前询价区块

响应示例:

{
  "type": "JupQuote",
  "data": {
    "Ok": {
      "quoteId": "1",
      "inputToken": "USDC",
      "outputToken": "SOL",
      "inAmount": 1,
      "outAmount": 0.005259052,
      "slippageBps": 10,
      "contextSlot": 314107835
    }
  }
}

错误示例:

{
  "type": "JupQuote",
  "data": {
    "Err": {
      "error": "JupQuote params is nil",
      "location": "1"
    }
  }
}

交易操作

JupSwap (cmd)

进行代币链上询价

请求参数:

参数	类型	是否必须	描述
quoteId	String	是	询价 ID
maxSlippageBps	Number	是	交易最大滑点，比如：300 = 3%滑点
gasFee	Number	是	交易费

请求示例:

{
  "Sync": {
    "Dex": {
      "JupSwap": {
        "quoteId": "1",
        "maxSlippageBps": 100,
        "gasFee": 100000
      }
    }
  }
}

响应字段:

参数	类型	是否必须	描述
Ok	String	是	交易 hash

响应示例:

{
  "type": "JupSwap",
  "data": {
    "Ok": "tx_hash"
  }
}

错误示例:

{
  "type": "JupSwap",
  "data": {
    "Err": {
      "error": "JupSwap params is nil",
      "location": "1"
    }
  }
}

错误处理

所有 API 在发生错误时会返回以下格式:

错误响应示例:

{
  "type": {
    "data": {
      "Err": {
        "error": "错误描述",
        "location": "错误位置"
      }
    }
  }
}