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:

bash

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

1. 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.nameEndpointDescriptionMethodAuthenticationInput ParametersOutput ParametersDetailed Doc URL1.1Get instrument info/v1/perpum/instrumentsQueries basic information for all instruments, including leverage, margin, TP/SL ratios, maker/taker fee, funding rate, max position size, etc.GETPublicnamebase, defaultLeverage, defaultStopLossRate, defaultStopProfitRate, indexId, leverage, makerFee, maxLeverage, minLeverage, and 37 total fieldshttps://www.coinw.com/api-doc/futures-trading/market/get-instrument-information1.2Get batch instrument info/v1/perpum/instrumentListBatch query basic information for multiple instruments in one request, including leverage, margin requirements, fee parameters, and max position size.GETPublicsymbolsbase, defaultLeverage, defaultStopLossRate, defaultStopProfitRate, indexId, leverage, makerFee, maxLeverage, minLeverage, and 38 total fieldshttps://www.coinw.com/api-doc/futures-trading/market/get-batch-instrument-information1.3Get latest ticker for one instrument/v1/perpumPublic/tickerReturns latest ticker summary for one instrument, including high/low, max leverage, volume, last price, and contract size.GETPublicinstrumentcontract_id, name, base_coin, quote_coin, price_coin, max_leverage, contract_size, last_price, high, and 13 total fieldshttps://www.coinw.com/api-doc/futures-trading/market/get-last-trade-summary-of-an-instrument1.4Get latest ticker summary in batch/v1/perpumPublic/ticker/listBatch query latest ticker summary for multiple instruments.GETPublicsymbolscontract_id, name, base_coin, quote_coin, price_coin, max_leverage, contract_size, last_price, high, and 13 total fieldshttps://www.coinw.com/api-doc/futures-trading/market/get-batch-last-trade-summary1.5Get latest ticker summary for all instruments/v1/perpumPublic/tickersReturns latest ticker summary for all instruments on the exchange.GETPublic—contract_id, name, base_coin, quote_coin, price_coin, max_leverage, contract_size, last_price, high, and 13 total fieldshttps://www.coinw.com/api-doc/futures-trading/market/get-last-trade-summary-of-all-instruments1.6Get historical K-line data by instrument/v1/perpumPublic/klinesQueries historical and latest K-line data for one instrument, including OHLC, timestamp, and volume.GETPublicSee 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 volumehttps://www.coinw.com/api-doc/futures-trading/market/get-k-line-of-an-instrument1.7Get latest settled funding rate/v1/perpum/fundingRateReturns the funding rate at the most recent settlement time. It is not necessarily related to the next settlement rate.GETPublicinstrumentdatahttps://www.coinw.com/api-doc/futures-trading/market/get-last-settelment-funding-fee-rate1.8Get order book by instrument/v1/perpumPublic/depthQueries order book depth for a specified instrument, including bids and asks.GETPublicbaseasks, bids, m, p, nhttps://www.coinw.com/api-doc/futures-trading/market/get-order-book-of-an-instrument1.9Get trade data by instrument/v1/perpumPublic/tradesQueries recent trade data for a specified instrument, including size, side, ID, timestamp, and price. Returns the latest 20 trades by default.GETPublicbasecreatedDate, piece, direction, price, quantity, idhttps://www.coinw.com/api-doc/futures-trading/market/get-trade-data-of-an-instrument1.10Get margin requirements for all instruments/v1/perpum/laddersQueries tiered margin requirements for all instruments, including initial/maintenance margin and max leverage.GETPrivateapi_key, signid, instrument, ladder, lastLadder, marginKeepRate, maxLeverage, marginStartRate, maxPiecehttps://www.coinw.com/api-doc/futures-trading/market/get-margin-requirements-of-all-instruments1.11Get historical public trades/v1/perpum/orders/tradesQueries historical public trade records for a specified instrument. Historical public trades are available via RESTful API only.GETPrivateapi_key, sign, instrument, pageSizeclosedPiece, createdDate, dealPrice, direction, idhttps://www.coinw.com/api-doc/futures-trading/market/get-historical-public-trades

Place Orders#

No.nameEndpointDescriptionMethodAuthenticationInput ParametersOutput ParametersDetailed Doc URL2.1Place order/v1/perpum/orderPlaces a contract order. Supports market, limit, and trigger order types.POSTPrivateapi_key, sign, instrument, direction, leverage, quantityUnit, quantity, positionModel, positionType, openPrice, stopProfitPrice, stopLossPrice, thirdOrderIdcode, datahttps://www.coinw.com/api-doc/futures-trading/trade/place-an-order2.2Batch place orders/v1/perpum/batchOrdersBatch places contract orders with support for market, limit, and trigger order types.POSTPrivateapi_key, sign, instrument, direction, leverage, quantityUnit, quantity, positionModel, positionType, openPrice, stopProfitPrice, stopLossPrice, triggerPrice, triggerType, thirdOrderIdcode, openId, thirdOrderIdhttps://www.coinw.com/api-doc/futures-trading/trade/place-batch-orders2.3Close position/v1/perpum/positionsPartially or fully closes an open contract position (filled order). Supports closing by fixed size or by position percentage.DELETEPrivateapi_key, sign, id, positionType, closeNum, orderPricedatahttps://www.coinw.com/api-doc/futures-trading/trade/close-a-position2.4Batch close positions/v1/perpum/batchCloseCloses multiple positions at market price in batch using thirdOrderId values.DELETEPrivateapi_key, sign, thirdOrderIdopenId, thirdOrderIdhttps://www.coinw.com/api-doc/futures-trading/trade/close-batch-positions2.5Market close all positions/v1/perpum/allpositionsCloses all positions for the specified instrument at market price.DELETEPrivateapi_key, sign—https://www.coinw.com/api-doc/futures-trading/trade/close-positions-at-market-price2.6Reverse position/v1/perpum/positions/reverseInstantly reverses an existing perpetual position by closing it and opening the same size in the opposite direction.POSTPrivateapi_key, sign, iddatahttps://www.coinw.com/api-doc/futures-trading/trade/reverse-a-position2.7Adjust margin/v1/perpum/positions/marginAdjusts margin for an existing position (filled order) by increasing or decreasing margin amount.POSTPrivateapi_key, sign, id, addMarginmsghttps://www.coinw.com/api-doc/futures-trading/trade/adjust-margin2.8Set TP/SL/v1/perpum/TPSLSets take-profit (TP) and stop-loss (SL) for filled or unfilled orders.POSTPrivateapi_key, sign, id, instrument, stopProfitPrice, stopLossPricemsghttps://www.coinw.com/api-doc/futures-trading/trade/set-stop-loss-take-profit2.9Set trailing TP/SL/v1/perpum/moveTPSLConfigures trailing TP/SL by callback rate. Applies to filled orders only.POSTPrivateapi_key, sign, openId, callbackRate, quantity, quantityUnit—https://www.coinw.com/api-doc/futures-trading/trade/set-trailing-stop-loss-take-profit2.10Batch set TP/SL/v1/perpum/addTpslBatch sets TP/SL for contract trading orders.POSTPrivateapi_key, sign, id, instrument, stopLossPrice, stopProfitPrice, priceType, stopFrom, stopType, closePiecemsghttps://www.coinw.com/api-doc/futures-trading/trade/set-stop-loss-take-profit-in-batches2.11Batch update TP/SL/v1/perpum/updateTpslBatch modifies TP/SL orders for contract trading.POSTPrivateapi_key, sign, id, instrument, stopLossPrice, stopProfitPrice, priceType, stopFrom, stopType, closePiecemsghttps://www.coinw.com/api-doc/futures-trading/trade/modify-stop-loss-take-profit-in-batches2.12Modify order/v1/perpum/orderModifies an unfilled order. Some fields (for example margin and leverage) cannot be changed via this endpoint.PUTPrivateapi_key, sign, id, instrument, direction, leverage, quantityUnit, quantity, positionModel, positionType, openPrice, stopProfitPrice, stopLossPrice, triggerPrice, triggerTypeoriginId, editIdhttps://www.coinw.com/api-doc/futures-trading/trade/modify-an-order2.13Cancel order/v1/perpum/orderCancels an unfilled order by order ID.DELETEPrivateapi_key, sign, idmsghttps://www.coinw.com/api-doc/futures-trading/trade/cancel-an-order2.14Cancel batch orders/v1/perpum/batchOrdersCancels multiple unfilled orders in batch.DELETEPrivateapi_key, sign, sourceIds—https://www.coinw.com/api-doc/futures-trading/trade/cancel-batch-orders

Query Orders#

No.nameEndpointDescriptionMethodAuthenticationInput ParametersOutput ParametersDetailed Doc URL3.1Get open orders/v1/perpum/orders/openQueries unfilled orders by instrument and order type, including direction, quantity, margin, leverage, fees, and timestamps.GETPrivateapi_key, sign, instrument, positionTypeid, userId, baseSize, createdDate, currentPiece, direction, frozenFee, indexPrice, instrument, and 28 total fieldshttps://www.coinw.com/api-doc/futures-trading/check/get-current-orders3.2Get open order count/v1/perpum/orders/openQuantityReturns total number of unfilled (pending) orders. Pending order data is available via RESTful API only.GETPrivateapi_key, signdatahttps://www.coinw.com/api-doc/futures-trading/check/get-pending-order-count3.3Get TP/SL info/v1/perpum/TPSLQueries TP/SL information for both filled and unfilled contract orders.GETPrivateapi_key, sign, openId, stopFromcurrentPiece, closePiece, direction, createdDate, updatedDate, id, indexPrice, instrument, leverage, and 24 total fieldshttps://www.coinw.com/api-doc/futures-trading/check/get-stop-loss-take-profit-information3.4Get trailing TP/SL info/v1/perpum/moveTPSLQueries trailing TP/SL details for contract trading.GETPrivateapi_key, signbaseSize, callbackRate, createdDate, currentPiece, direction, fee, instrument, leverage, margin, and 31 total fieldshttps://www.coinw.com/api-doc/futures-trading/check/get-trailing-stop-loss-take-profit-information3.5Get history orders (7 days)/v1/perpum/orders/historyReturns historical order records from the last 7 days with pagination and filters.GETPrivateapi_key, sign, page, pageSize, originType, instrumentuserId, baseSize, completeUsdt, createdDate, currentPiece, direction, entrustUsdt, havShortfall, hedgeId, and 37 total fieldshttps://www.coinw.com/api-doc/futures-trading/check/get-historical-orders-7days3.6Batch get history orders (7 days)/v1/perpum/orders/batchInsHistoryReturns historical order records from the last 7 days with batch query via symbols.GETPrivateapi_key, sign, page, pageSize, originType, symbolsuserId, baseSize, completeUsdt, createdDate, currentPiece, direction, entrustUsdt, havShortfall, hedgeId, and 37 total fieldshttps://www.coinw.com/api-doc/futures-trading/check/get-batch-historical-orders-7days3.7Get history orders (3 months)/v1/perpum/orders/archiveReturns historical order records from the last 3 months with pagination and filters.GETPrivateapi_key, sign, page, pageSize, originType, instrumentuserId, baseSize, completeUsdt, createdDate, currentPiece, direction, entrustUsdt, havShortfall, hedgeId, and 37 total fieldshttps://www.coinw.com/api-doc/futures-trading/check/get-historical-orders-3months3.8Batch get history orders (3 months)/v1/perpum/orders/batchInsArchiveReturns historical order records from the last 3 months with batch query via symbols.GETPrivateapi_key, sign, page, pageSize, originType, symbolsuserId, baseSize, completeUsdt, createdDate, currentPiece, direction, entrustUsdt, havShortfall, hedgeId, and 37 total fieldshttps://www.coinw.com/api-doc/futures-trading/check/get-batch-historical-orders-3months3.9Get order info/v1/perpum/orderReturns 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.GETPrivateapi_key, sign, positionType, sourceIdsid, baseSize, contractType, userId, fee, createdDate, currentPiece, direction, frozenFee, and 35 total fieldshttps://www.coinw.com/api-doc/futures-trading/check/get-order-information

Position Information#

No.nameEndpointDescriptionMethodAuthenticationInput ParametersOutput ParametersDetailed Doc URL4.1Get current positions/v1/perpum/positionsQueries currently open positions (filled orders) by instrument. You can also query specific positions using one or more position IDs.GETPrivateapi_key, sign, instrumentid, base, baseSize, createdDate, currentPiece, direction, fee, fundingSettle, indexPrice, and 37 total fieldshttps://www.coinw.com/api-doc/futures-trading/position/get-current-position-information4.2Get historical positions/v1/perpum/positions/historyQueries all historical positions (filled orders), with optional filtering by base/instrument and position margin mode.GETPrivateapi_key, sign, instrument, positionModelavgOpenPrice, completeUsdt, direction, entrustUsdt, fee, havShortfall, indexPrice, instrument, leverage, and 22 total fieldshttps://www.coinw.com/api-doc/futures-trading/position/get-historical-position-information4.3Get position margin rate/v1/perpum/positions/marginRateQueries margin rate for a position (filled order) by position ID.GETPrivateapi_key, sign, positionIddatahttps://www.coinw.com/api-doc/futures-trading/position/get-position-margin-rate4.4Get max contract size/v1/perpum/orders/maxSizeQueries max available contract size (long/short) by instrument, leverage, and position mode. Optional opening price can be provided.GETPrivateapi_key, sign, leverage, instrument, positionModel, orderPricemaxBuy, maxSellhttps://www.coinw.com/api-doc/futures-trading/position/get-max-contract-size4.5Get all current positions/v1/perpum/positions/allQueries all currently open positions (filled orders).GETPrivateapi_key, signid, base, baseSize, createdDate, currentPiece, closedPiece, direction, fee, fundingSettle, and 30 total fieldshttps://www.coinw.com/api-doc/futures-trading/position/get-current-positions

Account and Assets#

No.nameEndpointDescriptionMethodAuthenticationInput ParametersOutput ParametersDetailed Doc URL5.1Get max transferable balance/v1/perpum/account/availableQueries max amount transferable out from the contract account.GETPrivateapi_key, signdata.valuehttps://www.coinw.com/api-doc/futures-trading/assets/get-max-transferable-balance5.2Get deal details (3 days)/v1/perpum/orders/dealsDeal/funding details for the recent 3 days (see api-doc notes).GETPrivateapi_key, sign, instrument, page, pageSize, originType, positionModeldata.rows, nextId, prevId, totalhttps://www.coinw.com/api-doc/futures-trading/assets/get-transaction-details-3days5.3Get deal details (3 months)/v1/perpum/orders/deals/historyDeal/funding details for the recent 3 months (same fields as 5.2).GETPrivateapi_key, sign, instrument, page, pageSize, originType, positionModeldata.rows, nextId, prevId, totalhttps://www.coinw.com/api-doc/futures-trading/assets/get-transaction-details-3months5.4Get contract account assets/v1/perpum/account/getUserAssetsReturns available margin, USDT, frozen amounts, almighty-gold, and related fields (note meaning of availableMargin).GETPrivateapi_key, signavailableMargin, availableUsdt, alMargin, alFreeze, almightyGold, userId, timehttps://www.coinw.com/api-doc/futures-trading/assets/get-futures-account-assets5.5Get contract account fees/v1/perpum/account/feesQueries maker/taker fee rates.GETPrivateapi_key, signmakerFee, takerFee, userIdhttps://www.coinw.com/api-doc/futures-trading/assets/get-futures-account-fees5.6Get almighty-gold balance/v1/perpum/account/almightyGoldInfoFilters almighty-gold records by status and other criteria (GET).GETPrivateapi_key, sign, type, startTime?, endTime?data[] (id, currentAmount, totalAmount, type, etc.)https://www.coinw.com/api-doc/futures-trading/assets/get-mega-coupon-balance5.7Unit conversion/v1/perpum/pieceConvertConverts between contract pieces and coin amount.POSTPrivateapi_key, sign, convertType, faceValue, dealPiece?/baseSize?data.valuehttps://www.coinw.com/api-doc/futures-trading/assets/coin-conversion5.8Get position mode/v1/perpum/positions/typeQueries isolated/cross mode and merged/split layout (GET).GETPrivateapi_key, signlayout, positionModelhttps://www.coinw.com/api-doc/futures-trading/assets/get-margin-mode5.9Set position mode/v1/perpum/positions/typeSets isolated/cross mode and layout (POST); there must be no open orders before switching.POSTPrivateapi_key, sign, positionModel, layoutdata (TRANSACTION_SUCCESS)https://www.coinw.com/api-doc/futures-trading/assets/set-margin-mode5.10Enable/disable almighty-gold/v1/perpum/account/almightyGoldInfoEnables or disables almighty-gold (POST on same path as 5.6).POSTPrivateapi_key, sign, statuscode, msghttps://www.coinw.com/api-doc/futures-trading/assets/enable-disable-mega-coupon5.11Get user max available contract size/v1/perpum/orders/availSizeReturns available buy/sell size from the filled-position perspective (different from 4.4 maxSize use case).GETPrivateapi_key, sign, instrumentavailBuy, availSellhttps://www.coinw.com/api-doc/futures-trading/assets/get-max-users-contract-size

General#

No.nameEndpointDescriptionMethodAuthenticationInput ParametersOutput ParametersDetailed Doc URL6.1Get leverage info/v1/perpum/positions/leverageQueries leverage for one filled position ( positionId) or one unfilled order ( orderId), choose one.GETPrivateapi_key, sign, positionId or orderIddata.valuehttps://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#

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