[CaoKha]

What

The REST v3 API has a multi-market perp API under /v3/perp/*, plus GET /v3/markets. This PR adds them to the SDK.

• client.get_markets(): GET /markets
• client.perp: get_ticker(), get_candles(), get_funding_settlements()
• client.perp.isolated: new_trade(), cancel(), cancel_all(), close(), add_margin(), cash_in(), update_stoploss(), update_takeprofit(), remove_stoploss(), remove_takeprofit(), get_open_trades(), get_running_trades(), get_closed_trades(), get_canceled_trades(), get_funding_fees()

The models are in models/perp.py and models/markets.py. They follow the v3 API contract:

• Every perp call takes the market key (instrument + pair). GET and DELETE send it in the query. POST and PUT send it in the body.
• On per-user reads (open, running, closed, canceled, funding fees), the market key is optional: pass both fields or neither. Without it, the read covers every market.
• Responses include the quanto fields (quanto_adjustment_rate, quanto_adjustment_fee, sum_quanto_adjustment_fees), the notional fields and mark.
• PerpOrder.stoploss is an object {mode, value}, as in the API. The old futures route uses stoploss + stoploss_mode.
• History reads use cursor pagination. The cursor is an object ({value, id}). The client sends it as cursor[value] and cursor[id] in the query, and signs that exact query.
• Public perp routes and get_markets() sign the request when the client has credentials, so early-access markets work.

Deprecations

client.futures.get_ticker(), get_candles(), get_funding_settlements() and every client.futures.isolated method raise a DeprecationWarning. The warning names the client.perp method to use with instrument='inverse_perp', pair='btc_usd'. The methods still work.

client.futures.get_leaderboard() and client.futures.cross are not deprecated, because there is no perp route for them yet.

Fixes found on the way

• Signature bug: prepare_params turned 64000.0 into 64000 only for top-level fields. A nested value such as stoploss.value was sent as 64000.0. The server signs JSON.stringify(body), which writes 64000, so the signature did not match (401 Signature is not valid). The conversion now also handles nested values.
• Removed a debug print in futures.isolated.update_takeprofit().

Docs

• The README has a new "Perp markets" section that trades qGOLD (quanto_perp + xau_usdt). It also shows pagination and how to move off the deprecated methods.
• examples/rest_v3.py now uses client.perp. It picks a market other than BTC/USD from get_markets() when the API key has access to one.
• CHANGELOG entry and version bump to 0.3.0.

Tests

• Unit tests (no network): body and query layout, flattening and signing of the nested cursor, the nested float signature, open versus running trade parsing, the both-or-neither market filter rule, and the deprecation warning.
• Integration tests on signet (BTC/USD): markets, ticker, candles and funding settlements with a second page, a limit trade (place, list, cancel), and a market trade (stoploss and takeprofit set and remove, add margin, cash-in, close).
• Local run: ruff check, pyright: 0 errors. pytest: 62 passed, 12 skipped. The skips come from the signet account state (tier limit, low margin) and also happen on main.
• I ran the example on signet with a market trade on quanto_perp:xau_usdt: it opened the trade, set and removed the take profit, the stop loss and the trailing stop, then closed it.

After merge

Publish 0.3.0 to PyPI.

[CaoKha]

Replaced by the PR from branch feat/perp-routes.