Coinw Contract Skill

---

{ "name": 'Coinw Contract Skill', "description": 'Coinw Contract REST API skill: covers market data, order placement/cancellation, TP/SL, position and order queries, account assets, position modes, and leverage queries.', "metadata": {"version": "1.5.0","author": "Coinw","openclaw":{"always": true,"requires":{"env":["COINW_API_KEY","COINW_SECRET_KEY"]}}} }

---

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.

1. Environment variables:

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

2. 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)

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

Auth required (private endpoint)

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

1. Credentials requested: Mask secrets (show last 5 chars only) 2. Listing accounts: Show names never keys 3. 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

GET (public endpoint)

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

Auth required (private endpoint)

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"