Transfer (Signed)

POST

order

curl -X POST https://mainnet-api1.bulk.trade/api/v1/order \
  -H "Content-Type: application/json" \
  -d '{"actions":[{"transfer":{"k":"internal","from":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","to":"8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR","marginSymbol":"USDC","marginAmount":100.0}}],"nonce":1704067200000,"account":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","signer":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","signature":"5j7s..."}'

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {
          "transfer": {
            "from": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
            "to": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
            "symbol": "USDC",
            "amount": 100
          }
        }
      ]
    }
  }
}

Transfers use the unified POST /order endpoint. Send a transaction with a single transfer action. Conceptual background lives on the Protocol Native Asset Transfer page.

A transfer is rejected if it would push the source account into liquidation territory. The protocol bounds withdrawable amount by min(equity − 1.05 × MM, marginPnl).

Transaction Envelope

{
  "actions": [Action],
  "nonce": 1704067200000,
  "account": "authorizing_pubkey_base58",
  "signer": "authorizing_pubkey_base58",
  "signature": "base58_signature"
}

The account and signer must be the authorizing account:

internal: must be the master account that owns both from and to.
external: must be the account that owns the source.

Transfer Action (`transfer`)

{
  "actions": [
    {"transfer": {
      "k": "internal",
      "from": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
      "to": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
      "marginSymbol": "USDC",
      "marginAmount": 100.0
    }}
  ],
  "nonce": 1704067200000,
  "account": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signer": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
  "signature": "5j7s..."
}

Field	Type	Description
`k`	string	Transfer kind: `"internal"` (default) or `"external"`.
`from`	string	Source account pubkey (base58).
`to`	string	Destination account pubkey (base58). For per-instrument isolated-account top-ups, use the `isoPubkey` of an `iso=true` position row.
`marginSymbol`	string	Margin asset symbol (e.g. `"USDC"`).
`marginAmount`	number	Margin amount to transfer. Must be a JSON number (unquoted), e.g. `100.0` not `"100.0"`.

Transfer Kinds

Internal

Move margin between accounts that share the same master (master to sub-account, sub-account to sub-account, master to a per-instrument isolated account, and back). No minimum amount.

{"transfer": {
  "k": "internal",
  "from": "MASTER_PUBKEY",
  "to": "SUB_OR_ISO_PUBKEY",
  "marginSymbol": "USDC",
  "marginAmount": 100.0
}}

Isolated-account top-up

To add margin to a per-instrument isolated account, set to to the isoPubkey returned on iso=true rows in the fullAccount/positions snapshot.

{"transfer": {
  "k": "internal",
  "from": "MASTER_OR_SUB_PUBKEY",
  "to": "ISO_ACCOUNT_PUBKEY",
  "marginSymbol": "USDC",
  "marginAmount": 100.0
}}

External

Move margin to any account on the network. Subject to a per-symbol minimum amount.

{"transfer": {
  "k": "external",
  "from": "MASTER_PUBKEY",
  "to": "ANY_OTHER_PUBKEY",
  "marginSymbol": "USDC",
  "marginAmount": 50.0
}}

Notes:

external supports recipient auto-create only when the destination is on-curve (a real Solana wallet).
Unknown off-curve recipients are rejected; no implicit account creation.

Response

Same OrderResponse envelope. Successful transfers emit a transfer status row; failures emit transferFailed.

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {"transfer": {
          "from": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
          "to": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
          "symbol": "USDC",
          "amount": 100.0
        }}
      ]
    }
  }
}

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [{"transferFailed": {"message": "below minimum"}}]
    }
  }
}

Status	Terminal	Fields
`transfer`	Yes	`{from, to, symbol, amount}`
`transferFailed`	Yes	`{message}`

Common Error Messages

Message	Cause
`no margin symbol`	The specified token symbol does not exist
`unknown margin symbol`	The symbol exists but is not a recognized security
`below minimum`	External transfer amount is below the per-symbol minimum
`off-curve and does not exist`	External transfer to an off-curve address with no protocol account
`not permissioned for internal transfer`	`from` or `to` is not in the signer’s account tree
`source account not found`	`from` does not exist

Failed transfers do not modify any account state.

Margin-only Refresh

transfer (along with createSubAccount with margin move and removeSubAccount) triggers a same-tick margin/risk refresh on the touched accounts. The OrderResponse is returned synchronously, so the response may arrive before the corresponding account stream delta.

Before You Start

See Transaction Signing for how to sign requests.Nonce: use a unique value (e.g. timestamp in nanoseconds): BigInt(Date.now()) * 1_000_000n.

Body

application/json

Transaction with a single transfer action

actions

transfer · object[]

required

Must contain exactly one transfer action

Show child attributes

nonce

integer<int64>

required

account

string

required

Authorizing account public key (base58)

signer

string

required

Signer public key (base58)

signature

string

required

Ed25519 signature (base58)

Response

200 - application/json

Transfer accepted

status

enum<string>

Available options:

ok,

error

response

object

Show child attributes

curl -X POST https://mainnet-api1.bulk.trade/api/v1/order \
  -H "Content-Type: application/json" \
  -d '{"actions":[{"transfer":{"k":"internal","from":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","to":"8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR","marginSymbol":"USDC","marginAmount":100.0}}],"nonce":1704067200000,"account":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","signer":"FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7","signature":"5j7s..."}'

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        {
          "transfer": {
            "from": "FuueqefENiGEW6uMqZQgmwjzgpnb85EgUcZa5Em4PQh7",
            "to": "8x7iUti9m6L6Y9yQPXkXj4zD2uP1Qx5Eo9W4vYm6cGmR",
            "symbol": "USDC",
            "amount": 100
          }
        }
      ]
    }
  }
}

Getting Started

Market Data (HTTP)

Account (HTTP - Unsigned)

Trading (HTTP - Signed)

Testnet

WebSocket API

Transaction Envelope

Transfer Action (`transfer`)

Transfer Kinds

Internal

Isolated-account top-up

External

Response

Common Error Messages

Margin-only Refresh

Before You Start

Body

Response

​Transaction Envelope

​Transfer Action (transfer)

​Transfer Kinds

​Internal

​Isolated-account top-up

​External

​Response

​Common Error Messages

​Margin-only Refresh

​Before You Start

Body

Response

Transaction Envelope

Transfer Action (`transfer`)

Transfer Kinds

Internal

Isolated-account top-up

External

Response

Common Error Messages

Margin-only Refresh

Before You Start