Coinw Contract Skill

connectCoinw@connectcoinw

Coinw Contract REST API skill: covers market data, order placement/cancellation, TP/SL, position and order queries, account assets, position modes, and leverage queries.

Install

openclaw skills install @connectcoinw/coinw-contract-skill

Coinw Contract Skill

Coinw Contract REST API skill: covers market data, order placement/cancellation, TP/SL, position and order queries, account assets, position modes, and leverage.

Setup Credentials

CoinW private endpoints require api_key and a request signature (sign).

Signing note: Contract endpoints must use Contract signing (HMAC-SHA256 + Base64 + timestamp headers). Do not use Spot MD5 signing for Contract APIs.

Environment variables:

bash

export COINW_API_KEY="your_api_key"
export COINW_SECRET_KEY="your_secret_key"

In chat: provide api_key/secret_key (and an account name). The agent will mask secrets when showing them back and store them securely in OpenClaw's credential storage (not inside skill markdown files).

Key Features

Market data: contract instruments, order book, K-line data, trades, margin requirements
Trading and risk control: place orders, close/reverse positions, TP/SL (including trailing)
Queries and positions: order history, TP/SL info, margin rate, and position queries
Account and general: transferable balance, deal records, account assets and fee rates, almighty-gold, unit conversion, position mode, user available size, leverage query

Quick Reference

Market Information

No.	name	Endpoint	Description	Method	Authentication	Input Parameters	Output Parameters	Detailed Doc URL
1.1	Get instrument info	`/v1/perpum/instruments`	Queries basic information for all instruments, including leverage, margin, TP/SL ratios, maker/taker fee, funding rate, max position size, etc.	GET	Public	name	base, defaultLeverage, defaultStopLossRate, defaultStopProfitRate, indexId, leverage, makerFee, maxLeverage, minLeverage, and 37 total fields	`https://www.coinw.com/api-doc/futures-trading/market/get-instrument-information`
1.2	Get batch instrument info	`/v1/perpum/instrumentList`	Batch query basic information for multiple instruments in one request, including leverage, margin requirements, fee parameters, and max position size.	GET	Public	symbols	base, defaultLeverage, defaultStopLossRate, defaultStopProfitRate, indexId, leverage, makerFee, maxLeverage, minLeverage, and 38 total fields	`https://www.coinw.com/api-doc/futures-trading/market/get-batch-instrument-information`
1.3	Get latest ticker for one instrument	`/v1/perpumPublic/ticker`	Returns latest ticker summary for one instrument, including high/low, max leverage, volume, last price, and contract size.	GET	Public	instrument	contract_id, name, base_coin, quote_coin, price_coin, max_leverage, contract_size, last_price, high, and 13 total fields	`https://www.coinw.com/api-doc/futures-trading/market/get-last-trade-summary-of-an-instrument`
1.4	Get latest ticker summary in batch	`/v1/perpumPublic/ticker/list`	Batch query latest ticker summary for multiple instruments.	GET	Public	symbols	contract_id, name, base_coin, quote_coin, price_coin, max_leverage, contract_size, last_price, high, and 13 total fields	`https://www.coinw.com/api-doc/futures-trading/market/get-batch-last-trade-summary`
1.5	Get latest ticker summary for all instruments	`/v1/perpumPublic/tickers`	Returns latest ticker summary for all instruments on the exchange.	GET	Public	—	contract_id, name, base_coin, quote_coin, price_coin, max_leverage, contract_size, last_price, high, and 13 total fields	`https://www.coinw.com/api-doc/futures-trading/market/get-last-trade-summary-of-all-instruments`
1.6	Get historical K-line data by instrument	`/v1/perpumPublic/klines`	Queries historical and latest K-line data for one instrument, including OHLC, timestamp, and volume.	GET	Public	See api-doc 1.6 (for example granularity, klineType, limit, reporting coin, and time-range params)	K-line array: each item includes timestamp, high/open/low/close, and volume	`https://www.coinw.com/api-doc/futures-trading/market/get-k-line-of-an-instrument`
1.7	Get latest settled funding rate	`/v1/perpum/fundingRate`	Returns the funding rate at the most recent settlement time. It is not necessarily related to the next settlement rate.	GET	Public	instrument	data	`https://www.coinw.com/api-doc/futures-trading/market/get-last-settelment-funding-fee-rate`
1.8	Get order book by instrument	`/v1/perpumPublic/depth`	Queries order book depth for a specified instrument, including bids and asks.	GET	Public	base	asks, bids, m, p, n	`https://www.coinw.com/api-doc/futures-trading/market/get-order-book-of-an-instrument`
1.9	Get trade data by instrument	`/v1/perpumPublic/trades`	Queries recent trade data for a specified instrument, including size, side, ID, timestamp, and price. Returns the latest 20 trades by default.	GET	Public	base	createdDate, piece, direction, price, quantity, id	`https://www.coinw.com/api-doc/futures-trading/market/get-trade-data-of-an-instrument`
1.10	Get margin requirements for all instruments	`/v1/perpum/ladders`	Queries tiered margin requirements for all instruments, including initial/maintenance margin and max leverage.	GET	Private	api_key, sign	id, instrument, ladder, lastLadder, marginKeepRate, maxLeverage, marginStartRate, maxPiece	`https://www.coinw.com/api-doc/futures-trading/market/get-margin-requirements-of-all-instruments`
1.11	Get historical public trades	`/v1/perpum/orders/trades`	Queries historical public trade records for a specified instrument. Historical public trades are available via RESTful API only.	GET	Private	api_key, sign, instrument, pageSize	closedPiece, createdDate, dealPrice, direction, id	`https://www.coinw.com/api-doc/futures-trading/market/get-historical-public-trades`

Place Orders

No.	name	Endpoint	Description	Method	Authentication	Input Parameters	Output Parameters	Detailed Doc URL
2.1	Place order	`/v1/perpum/order`	Places a contract order. Supports market, limit, and trigger order types.	POST	Private	api_key, sign, instrument, direction, leverage, quantityUnit, quantity, positionModel, positionType, openPrice, stopProfitPrice, stopLossPrice, thirdOrderId	code, data	`https://www.coinw.com/api-doc/futures-trading/trade/place-an-order`
2.2	Batch place orders	`/v1/perpum/batchOrders`	Batch places contract orders with support for market, limit, and trigger order types.	POST	Private	api_key, sign, instrument, direction, leverage, quantityUnit, quantity, positionModel, positionType, openPrice, stopProfitPrice, stopLossPrice, triggerPrice, triggerType, thirdOrderId	code, openId, thirdOrderId	`https://www.coinw.com/api-doc/futures-trading/trade/place-batch-orders`
2.3	Close position	`/v1/perpum/positions`	Partially or fully closes an open contract position (filled order). Supports closing by fixed size or by position percentage.	DELETE	Private	api_key, sign, id, positionType, closeNum, orderPrice	data	`https://www.coinw.com/api-doc/futures-trading/trade/close-a-position`
2.4	Batch close positions	`/v1/perpum/batchClose`	Closes multiple positions at market price in batch using `thirdOrderId` values.	DELETE	Private	api_key, sign, thirdOrderId	openId, thirdOrderId	`https://www.coinw.com/api-doc/futures-trading/trade/close-batch-positions`
2.5	Market close all positions	`/v1/perpum/allpositions`	Closes all positions for the specified instrument at market price.	DELETE	Private	api_key, sign	—	`https://www.coinw.com/api-doc/futures-trading/trade/close-positions-at-market-price`
2.6	Reverse position	`/v1/perpum/positions/reverse`	Instantly reverses an existing perpetual position by closing it and opening the same size in the opposite direction.	POST	Private	api_key, sign, id	data	`https://www.coinw.com/api-doc/futures-trading/trade/reverse-a-position`
2.7	Adjust margin	`/v1/perpum/positions/margin`	Adjusts margin for an existing position (filled order) by increasing or decreasing margin amount.	POST	Private	api_key, sign, id, addMargin	msg	`https://www.coinw.com/api-doc/futures-trading/trade/adjust-margin`
2.8	Set TP/SL	`/v1/perpum/TPSL`	Sets take-profit (TP) and stop-loss (SL) for filled or unfilled orders.	POST	Private	api_key, sign, id, instrument, stopProfitPrice, stopLossPrice	msg	`https://www.coinw.com/api-doc/futures-trading/trade/set-stop-loss-take-profit`
2.9	Set trailing TP/SL	`/v1/perpum/moveTPSL`	Configures trailing TP/SL by callback rate. Applies to filled orders only.	POST	Private	api_key, sign, openId, callbackRate, quantity, quantityUnit	—	`https://www.coinw.com/api-doc/futures-trading/trade/set-trailing-stop-loss-take-profit`
2.10	Batch set TP/SL	`/v1/perpum/addTpsl`	Batch sets TP/SL for contract trading orders.	POST	Private	api_key, sign, id, instrument, stopLossPrice, stopProfitPrice, priceType, stopFrom, stopType, closePiece	msg	`https://www.coinw.com/api-doc/futures-trading/trade/set-stop-loss-take-profit-in-batches`
2.11	Batch update TP/SL	`/v1/perpum/updateTpsl`	Batch modifies TP/SL orders for contract trading.	POST	Private	api_key, sign, id, instrument, stopLossPrice, stopProfitPrice, priceType, stopFrom, stopType, closePiece	msg	`https://www.coinw.com/api-doc/futures-trading/trade/modify-stop-loss-take-profit-in-batches`
2.12	Modify order	`/v1/perpum/order`	Modifies an unfilled order. Some fields (for example margin and leverage) cannot be changed via this endpoint.	PUT	Private	api_key, sign, id, instrument, direction, leverage, quantityUnit, quantity, positionModel, positionType, openPrice, stopProfitPrice, stopLossPrice, triggerPrice, triggerType	originId, editId	`https://www.coinw.com/api-doc/futures-trading/trade/modify-an-order`
2.13	Cancel order	`/v1/perpum/order`	Cancels an unfilled order by order ID.	DELETE	Private	api_key, sign, id	msg	`https://www.coinw.com/api-doc/futures-trading/trade/cancel-an-order`
2.14	Cancel batch orders	`/v1/perpum/batchOrders`	Cancels multiple unfilled orders in batch.	DELETE	Private	api_key, sign, sourceIds	—	`https://www.coinw.com/api-doc/futures-trading/trade/cancel-batch-orders`

Query Orders

No.	name	Endpoint	Description	Method	Authentication	Input Parameters	Output Parameters	Detailed Doc URL
3.1	Get open orders	`/v1/perpum/orders/open`	Queries unfilled orders by instrument and order type, including direction, quantity, margin, leverage, fees, and timestamps.	GET	Private	api_key, sign, instrument, positionType	id, userId, baseSize, createdDate, currentPiece, direction, frozenFee, indexPrice, instrument, and 28 total fields	`https://www.coinw.com/api-doc/futures-trading/check/get-current-orders`
3.2	Get open order count	`/v1/perpum/orders/openQuantity`	Returns total number of unfilled (pending) orders. Pending order data is available via RESTful API only.	GET	Private	api_key, sign	data	`https://www.coinw.com/api-doc/futures-trading/check/get-pending-order-count`
3.3	Get TP/SL info	`/v1/perpum/TPSL`	Queries TP/SL information for both filled and unfilled contract orders.	GET	Private	api_key, sign, openId, stopFrom	currentPiece, closePiece, direction, createdDate, updatedDate, id, indexPrice, instrument, leverage, and 24 total fields	`https://www.coinw.com/api-doc/futures-trading/check/get-stop-loss-take-profit-information`
3.4	Get trailing TP/SL info	`/v1/perpum/moveTPSL`	Queries trailing TP/SL details for contract trading.	GET	Private	api_key, sign	baseSize, callbackRate, createdDate, currentPiece, direction, fee, instrument, leverage, margin, and 31 total fields	`https://www.coinw.com/api-doc/futures-trading/check/get-trailing-stop-loss-take-profit-information`
3.5	Get history orders (7 days)	`/v1/perpum/orders/history`	Returns historical order records from the last 7 days with pagination and filters.	GET	Private	api_key, sign, page, pageSize, originType, instrument	userId, baseSize, completeUsdt, createdDate, currentPiece, direction, entrustUsdt, havShortfall, hedgeId, and 37 total fields	`https://www.coinw.com/api-doc/futures-trading/check/get-historical-orders-7days`
3.6	Batch get history orders (7 days)	`/v1/perpum/orders/batchInsHistory`	Returns historical order records from the last 7 days with batch query via `symbols`.	GET	Private	api_key, sign, page, pageSize, originType, symbols	userId, baseSize, completeUsdt, createdDate, currentPiece, direction, entrustUsdt, havShortfall, hedgeId, and 37 total fields	`https://www.coinw.com/api-doc/futures-trading/check/get-batch-historical-orders-7days`
3.7	Get history orders (3 months)	`/v1/perpum/orders/archive`	Returns historical order records from the last 3 months with pagination and filters.	GET	Private	api_key, sign, page, pageSize, originType, instrument	userId, baseSize, completeUsdt, createdDate, currentPiece, direction, entrustUsdt, havShortfall, hedgeId, and 37 total fields	`https://www.coinw.com/api-doc/futures-trading/check/get-historical-orders-3months`
3.8	Batch get history orders (3 months)	`/v1/perpum/orders/batchInsArchive`	Returns historical order records from the last 3 months with batch query via `symbols`.	GET	Private	api_key, sign, page, pageSize, originType, symbols	userId, baseSize, completeUsdt, createdDate, currentPiece, direction, entrustUsdt, havShortfall, hedgeId, and 37 total fields	`https://www.coinw.com/api-doc/futures-trading/check/get-batch-historical-orders-3months`
3.9	Get order info	`/v1/perpum/order`	Returns current unfilled order information. You can query by order ID list; if no instrument/order IDs are specified, all orders under the given order type are returned.	GET	Private	api_key, sign, positionType, sourceIds	id, baseSize, contractType, userId, fee, createdDate, currentPiece, direction, frozenFee, and 35 total fields	`https://www.coinw.com/api-doc/futures-trading/check/get-order-information`

Position Information

No.	name	Endpoint	Description	Method	Authentication	Input Parameters	Output Parameters	Detailed Doc URL
4.1	Get current positions	`/v1/perpum/positions`	Queries currently open positions (filled orders) by instrument. You can also query specific positions using one or more position IDs.	GET	Private	api_key, sign, instrument	id, base, baseSize, createdDate, currentPiece, direction, fee, fundingSettle, indexPrice, and 37 total fields	`https://www.coinw.com/api-doc/futures-trading/position/get-current-position-information`
4.2	Get historical positions	`/v1/perpum/positions/history`	Queries all historical positions (filled orders), with optional filtering by base/instrument and position margin mode.	GET	Private	api_key, sign, instrument, positionModel	avgOpenPrice, completeUsdt, direction, entrustUsdt, fee, havShortfall, indexPrice, instrument, leverage, and 22 total fields	`https://www.coinw.com/api-doc/futures-trading/position/get-historical-position-information`
4.3	Get position margin rate	`/v1/perpum/positions/marginRate`	Queries margin rate for a position (filled order) by position ID.	GET	Private	api_key, sign, positionId	data	`https://www.coinw.com/api-doc/futures-trading/position/get-position-margin-rate`
4.4	Get max contract size	`/v1/perpum/orders/maxSize`	Queries max available contract size (long/short) by instrument, leverage, and position mode. Optional opening price can be provided.	GET	Private	api_key, sign, leverage, instrument, positionModel, orderPrice	maxBuy, maxSell	`https://www.coinw.com/api-doc/futures-trading/position/get-max-contract-size`
4.5	Get all current positions	`/v1/perpum/positions/all`	Queries all currently open positions (filled orders).	GET	Private	api_key, sign	id, base, baseSize, createdDate, currentPiece, closedPiece, direction, fee, fundingSettle, and 30 total fields	`https://www.coinw.com/api-doc/futures-trading/position/get-current-positions`

Account and Assets

No.	name	Endpoint	Description	Method	Authentication	Input Parameters	Output Parameters	Detailed Doc URL
5.1	Get max transferable balance	`/v1/perpum/account/available`	Queries max amount transferable out from the contract account.	GET	Private	api_key, sign	data.value	`https://www.coinw.com/api-doc/futures-trading/assets/get-max-transferable-balance`
5.2	Get deal details (3 days)	`/v1/perpum/orders/deals`	Deal/funding details for the recent 3 days (see api-doc notes).	GET	Private	api_key, sign, instrument, page, pageSize, originType, positionModel	data.rows, nextId, prevId, total	`https://www.coinw.com/api-doc/futures-trading/assets/get-transaction-details-3days`
5.3	Get deal details (3 months)	`/v1/perpum/orders/deals/history`	Deal/funding details for the recent 3 months (same fields as 5.2).	GET	Private	api_key, sign, instrument, page, pageSize, originType, positionModel	data.rows, nextId, prevId, total	`https://www.coinw.com/api-doc/futures-trading/assets/get-transaction-details-3months`
5.4	Get contract account assets	`/v1/perpum/account/getUserAssets`	Returns available margin, USDT, frozen amounts, almighty-gold, and related fields (note meaning of `availableMargin`).	GET	Private	api_key, sign	availableMargin, availableUsdt, alMargin, alFreeze, almightyGold, userId, time	`https://www.coinw.com/api-doc/futures-trading/assets/get-futures-account-assets`
5.5	Get contract account fees	`/v1/perpum/account/fees`	Queries maker/taker fee rates.	GET	Private	api_key, sign	makerFee, takerFee, userId	`https://www.coinw.com/api-doc/futures-trading/assets/get-futures-account-fees`
5.6	Get almighty-gold balance	`/v1/perpum/account/almightyGoldInfo`	Filters almighty-gold records by status and other criteria (GET).	GET	Private	api_key, sign, type, startTime?, endTime?	data[] (id, currentAmount, totalAmount, type, etc.)	`https://www.coinw.com/api-doc/futures-trading/assets/get-mega-coupon-balance`
5.7	Unit conversion	`/v1/perpum/pieceConvert`	Converts between contract pieces and coin amount.	POST	Private	api_key, sign, convertType, faceValue, dealPiece?/baseSize?	data.value	`https://www.coinw.com/api-doc/futures-trading/assets/coin-conversion`
5.8	Get position mode	`/v1/perpum/positions/type`	Queries isolated/cross mode and merged/split layout (GET).	GET	Private	api_key, sign	layout, positionModel	`https://www.coinw.com/api-doc/futures-trading/assets/get-margin-mode`
5.9	Set position mode	`/v1/perpum/positions/type`	Sets isolated/cross mode and layout (POST); there must be no open orders before switching.	POST	Private	api_key, sign, positionModel, layout	data (TRANSACTION_SUCCESS)	`https://www.coinw.com/api-doc/futures-trading/assets/set-margin-mode`
5.10	Enable/disable almighty-gold	`/v1/perpum/account/almightyGoldInfo`	Enables or disables almighty-gold (POST on same path as 5.6).	POST	Private	api_key, sign, status	code, msg	`https://www.coinw.com/api-doc/futures-trading/assets/enable-disable-mega-coupon`
5.11	Get user max available contract size	`/v1/perpum/orders/availSize`	Returns available buy/sell size from the filled-position perspective (different from 4.4 maxSize use case).	GET	Private	api_key, sign, instrument	availBuy, availSell	`https://www.coinw.com/api-doc/futures-trading/assets/get-max-users-contract-size`

General

No.	name	Endpoint	Description	Method	Authentication	Input Parameters	Output Parameters	Detailed Doc URL
6.1	Get leverage info	`/v1/perpum/positions/leverage`	Queries leverage for one filled position (`positionId`) or one unfilled order (`orderId`), choose one.	GET	Private	api_key, sign, positionId or orderId	data.value	`https://www.coinw.com/api-doc/futures-trading/common/get-leverage-information`

Common Parameters and Enums

Auth and URL

Base URL: https://api.coinw.com.
Public market endpoints are mostly GET https://api.coinw.com/v1/perpum/... or .../v1/perpumPublic/....
Private endpoints require header-based auth: api_key, timestamp, sign (HMAC-SHA256 then Base64, see Reference).

Common request fields

instrument / name: contract identifier (often mixed in docs; means underlying/contract name).
symbols: comma-separated list for batch endpoints.
direction (String, required = true): trade direction, long (open long) or short (open short).
layout: 0 merged positions, 1 split positions (used with positionModel on /v1/perpum/positions/type GET/POST).
convertType: 1 piece -> coin, 2 coin -> piece (pieceConvert).
almighty-gold type (GET almightyGoldInfo): 0 pending to effective through 4 issuance failed; status (POST): 1 on / 0 off.

Standard response wrapper (common in REST)

Common top-level fields: code, msg / message, success, failed, data (actual response varies by endpoint).

Common enums and values

contractType: common value 1: USDT-margined perpetual contract (see api-doc).
positionModel: position mode: 0 isolated, 1 cross (follow api-doc wording).
quantityUnit: quantity unit for orders: 0 = quote currency (for example USDT); 1 = contract piece; 2 = base currency (for example BTC).
status: contract status examples: offline, online, pretest, settlement, preOffline.
priceType: TP/SL trigger price type: 1 = index price, 2 = last price, 3 = mark price.
processStatus: matching-engine process status: 0 = waiting, 1 = processing, 2 = success, 3 = failed.
selected: default selected status: 0 = no, 1 = yes.
stopType: TP/SL order type: 1 = limit, 2 = market, 3 = planned order.
triggerStatus: TP/SL trigger status: 0 = not triggered, 1 = triggered, 2 = canceled.
triggerType: order type when triggerPrice condition is met: 0 = limit, 1 = market.

Examples

GET (public endpoint)

bash

curl "https://api.coinw.com/v1/perpumPublic/tickers"

Auth required (private endpoint)

bash

timestamp=$(($(date +%s%N)/1000000))
method="DELETE"
api_url="/v1/perpum/allpositions"
payload="${timestamp}${method}${api_url}"
sign=$(printf "%s" "$payload" | openssl dgst -sha256 -hmac "$COINW_SECRET_KEY" -binary | openssl base64)
curl -X DELETE "https://api.coinw.com${api_url}" \
  -H "api_key: $COINW_API_KEY" \
  -H "timestamp: ${timestamp}" \
  -H "sign: ${sign}" \
  -H "Content-type: application/json"

Security

When showing credentials to users:

API Key: Show first 4 + last 5 characters: 12&*1...198I
Secret Key: Always mask, show only last 4: ***...isf1
Ask for user confirmation before any trade action.
Store user api_key and secret_key in a secure location.

Agent Behavior

Credentials requested: Mask secrets (show last 5 chars only)
Listing accounts: Show names never keys
New credentials: Prompt for name, signing mode

Adding New Accounts

When user provides new credentials:

Ask for account name, api_key, secret_key
Store the provided credentials in OpenClaw's secure credential store with masked display confirmation

Reference

Authentication./references/Authentication.md
errorcode: ./references/error-codes.md
notes: ./references/notes.md
api-key create steps: ./references/api-key-creation-steps.md