Prepare a Spot<->Perps transfer

Prepare a Spot<->Perps transfer

post

Build an unsigned USDC transfer between a wallet's spot and perpetuals balances.

Same prepare → sign → execute flow as /api/v1/perp/order: sign the returned eip712 payload and submit it to /api/v1/perp/execute. This call moves nothing on its own.

Only the perpetuals balance can be used as margin. USDC that arrives on Hyperliquid by a direct send lands in the spot balance, where perp trading cannot see it — which is what this endpoint is for. to_perp: true moves spot → perps, false moves perps → spot. /api/v1/perp/account reports both balances, so check there when a wallet looks funded but cannot open a position.

This is a wallet-signed action, so its EIP-712 domain and types differ from an order's. Sign whatever the eip712 field contains rather than hard-coding one payload shape.

Authorizations

ApiKeyAuth

apikeystringRequired

API key for authentication

Body

application/json

USDC transfer to prepare between a wallet's spot and perpetuals balances.

wallet_addressstringRequired

Wallet address on Hyperliquid

Example: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

amountnumberRequired

USDC amount as a decimal number of USDC (not base units)

Example: 100.5

to_perpbooleanRequired

True moves spot → perpetuals (making the funds usable as margin), false moves perpetuals → spot

Example: true

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1/perp/transfer

HTTPcURLJavaScriptPython

POST /api/v1/perp/transfer HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "amount": 100.5,
  "to_perp": true
}

{
  "action": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "nonce": 1,
  "vault_address": "text",
  "eip712": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "size": 1,
  "price": 1,
  "ANY_ADDITIONAL_PROPERTY": "anything"
}