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

Place Orders

Query Orders

Position Information

Account and Assets

General

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