> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Spot ↔ Perp transfer | Hyperliquid exchange
> Transfers USDC between your spot wallet and perpetual wallet on Hyperliquid. Spot ↔ Perp transfer on Hyperliquid exchange via Chainstack.
You can only use this endpoint on the official Hyperliquid public API. It is not available through Chainstack, as the open-source node implementation does not support it yet. See [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown.
This endpoint requires signature authentication. See our comprehensive [Authentication via Signatures guide](/docs/hyperliquid-authentication-guide) for implementation details.
Transfers USDC between your spot wallet and perpetual wallet on Hyperliquid. This allows you to move collateral between different trading modes without withdrawing from the platform.
## Parameters
### Required parameters
* `action` (object, required) — The transfer action object containing:
* `type` (string) — Must be `"spotUser"`
* `classTransfer` (object) — Transfer details:
* `usdc` (number) — Amount to transfer in USDC with 6 decimals (e.g., 100000000 = 100 USDC)
* `toPerp` (boolean) — Direction of transfer:
* `true` — Transfer from spot to perp
* `false` — Transfer from perp to spot
* `nonce` (number, required) — Current timestamp in milliseconds (must be recent)
* `signature` (object, required) — EIP-712 signature of the action
### Optional parameters
* `vaultAddress` (string, optional) — Address when trading on behalf of a vault or subaccount
* `expiresAfter` (number, optional) — Timestamp in milliseconds after which the request is rejected
## Transfer direction
* **Spot → Perp** (`toPerp: true`)
* Moves USDC from spot wallet to perpetual trading account
* Required for perpetual trading and margin
* **Perp → Spot** (`toPerp: false`)
* Moves USDC from perpetual account to spot wallet
* Required for spot trading or token purchases
## Returns
Returns an object with transfer status:
* `status` — `"ok"` if successful
* `response` — Contains transfer details:
* `type` — `"default"`
## Example request
```shell cURL theme={"system"}
# Transfer 100 USDC from spot to perp
curl -X POST https://api.hyperliquid.xyz/exchange \
-H "Content-Type: application/json" \
-d '{
"action": {
"type": "spotUser",
"classTransfer": {
"usdc": 100000000,
"toPerp": true
}
},
"nonce": 1234567890123,
"signature": {...}
}'
# Transfer 50 USDC from perp to spot
curl -X POST https://api.hyperliquid.xyz/exchange \
-H "Content-Type: application/json" \
-d '{
"action": {
"type": "spotUser",
"classTransfer": {
"usdc": 50000000,
"toPerp": false
}
},
"nonce": 1234567890123,
"signature": {...}
}'
```
```python hyperliquid-python-sdk theme={"system"}
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
import eth_account
# Initialize with your private key
account = eth_account.Account.from_key("0x...")
exchange = Exchange(account, constants.MAINNET_API_URL)
# Transfer 100 USDC from spot to perp
to_perp = exchange.usd_class_transfer(
amount=100.0,
to_perp=True,
)
# Transfer 50 USDC from perp to spot
to_spot = exchange.usd_class_transfer(
amount=50.0,
to_perp=False,
)
print(to_perp)
```
```typescript @nktkas/hyperliquid theme={"system"}
import { ExchangeClient, HttpTransport } from "@nktkas/hyperliquid";
import { privateKeyToAccount } from "viem/accounts";
// Initialize with your private key
const wallet = privateKeyToAccount("0x...");
const transport = new HttpTransport();
const exchange = new ExchangeClient({ transport, wallet });
// Transfer 100 USDC from spot to perp
const toPerp = await exchange.usdClassTransfer({
amount: "100",
toPerp: true,
});
// Transfer 50 USDC from perp to spot
const toSpot = await exchange.usdClassTransfer({
amount: "50",
toPerp: false,
});
console.log(toPerp);
```
## Response example
```json theme={"system"}
{
"status": "ok",
"response": {
"type": "default"
}
}
```
## Important considerations
* **Balance requirements** — Must have sufficient balance in the source wallet
* **Instant transfer** — Transfers are immediate within Hyperliquid
* **No fees** — Internal transfers between spot and perp are free
* **Position checks** — Cannot transfer from perp if it would cause liquidation
## Use cases
* **Trading mode switch** — Move funds between spot and perpetual trading
* **Capital allocation** — Optimize fund distribution across trading strategies
* **Risk management** — Move profits from perp to spot for safer storage
* **Liquidity management** — Quickly reallocate capital based on opportunities
USDC in the spot wallet can be used for spot trading and token purchases. USDC in the perp wallet is used as collateral for perpetual positions.
When transferring from perp to spot, ensure you maintain sufficient margin for any open perpetual positions to avoid liquidation.
## OpenAPI
````yaml openapi/hyperliquid_node_api/hypercore_exchange/exchange_spot_perp_transfer.json post /exchange
openapi: 3.0.0
info:
title: Hyperliquid Exchange API
version: 1.0.0
description: >-
API for trading operations on Hyperliquid exchange requiring authentication.
⚠️ WARNING: These endpoints require EIP-712 signatures for authentication.
The example values provided will NOT work without proper cryptographic
signing. You must implement EIP-712 signing to use these endpoints
successfully.
servers:
- url: https://api.hyperliquid.xyz
security: []
paths:
/exchange:
post:
tags:
- hyperliquid exchange
summary: Transfer between spot and perp accounts
operationId: transferSpotPerp
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
action:
type: object
properties:
type:
type: string
default: usdClassTransfer
enum:
- usdClassTransfer
description: Action type for transferring between spot and perp
hyperliquidChain:
type: string
description: Chain identifier
default: Mainnet
enum:
- Mainnet
- Testnet
signatureChainId:
type: string
description: EIP-712 signature chain ID
default: '0xa4b1'
amount:
type: string
description: Amount to transfer as a decimal string
toPerp:
type: boolean
description: >-
true to transfer from spot to perp, false for perp to
spot
nonce:
type: integer
description: Current timestamp in milliseconds
required:
- type
- hyperliquidChain
- signatureChainId
- amount
- toPerp
- nonce
nonce:
type: integer
description: Current timestamp in milliseconds
signature:
type: object
description: EIP-712 signature of the action with r, s, v components
properties:
r:
type: string
description: ECDSA signature r component (hex string)
example: >-
0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
s:
type: string
description: ECDSA signature s component (hex string)
example: >-
0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321
v:
type: integer
description: ECDSA recovery id (27 or 28)
example: 27
required:
- r
- s
- v
vaultAddress:
type: string
description: >-
Address when trading on behalf of a vault or subaccount
(optional)
nullable: true
required:
- action
- nonce
- signature
example:
action:
type: usdClassTransfer
hyperliquidChain: Mainnet
signatureChainId: '0xa4b1'
amount: '250.0'
toPerp: true
nonce: 1705234567890
nonce: 1705234567890
signature:
r: >-
0x0000000000000000000000000000000000000000000000000000000000000000
s: >-
0x0000000000000000000000000000000000000000000000000000000000000000
v: 27
vaultAddress: null
responses:
'200':
description: Spot/Perp transfer result
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Request status
response:
type: object
properties:
type:
type: string
data:
type: object
properties:
status:
type: string
description: Transfer status
example:
status: ok
response:
type: spotUser
data:
status: success
````