BlockTrades

Create block trade

Changed on

Create a parent block trade for multi-party execution.

Block trades coordinate execution across multiple parties. The initiator creates a parent block trade specifying trade details and required signers, who must submit offers before execution.

Requirements:

  • Required signers must have active onboarding and block trade functionality
  • Required signers cannot be isolated margin accounts
  • Valid StarkNet signature with expiration timestamp
  • Each trade specifies market, size, price, and order details

Workflow:

  1. Initiator creates parent block trade
  2. Required signers submit offers
  3. Initiator executes with selected offers
  4. All trades processed together
post/block-trades

Request

  • Base URL
    https://api.prod.paradex.trade/v1
  • URL
    https://api.prod.paradex.trade/v1/block-trades
  • Auth
    API key in header Authorization

Request body

block_expirationinteger required

Unix timestamp in milliseconds when block expires

noncestring required

Unique nonce for this block trade request

required_signersstring[] required

List of accounts that can participate in the block trade

signaturesobject required

Map of account addresses to their signatures. Can be empty or partial.

tradesobject required

Map of market symbol to trade info (one per market)

Example request

{
  "block_expiration": 1640995800000,
  "nonce": "67890"
}

Response

Created

block_expirationinteger

Unix timestamp in milliseconds when block expires

block_idstring

Backend-generated unique identifier

block_type'DIRECT' | 'OFFER_BASED'
created_atinteger

When block was created

failure_reasonstring

Reason for failure (if status is FAILED). Names a participant by role, never by address: <maker>, <taker>, <initiator>, <participant> (a party whose side is ambiguous), or <redacted> (an identifier belonging to no participant)

initiatorstring

Account that initiated this block trade

last_updated_atinteger

When block was last updated

noncestring

Original block nonce

parent_block_idstring

Parent block ID (if offer-based)

required_signersstring[]

List of accounts that can participate in the block trade

signaturesobject

Current signatures on this block (for signature verification)

status'CREATED' | 'OFFER_COLLECTION' | 'EXECUTING' | 'PENDING_SETTLEMENT' | 'COMPLETED' | 'FAILED' | 'CANCELLED'
tradesobject

Map of market to trade details

Example response

{
  "block_expiration": 1640995800000,
  "block_id": "block_456",
  "created_at": 1640995200000,
  "initiator": "0x123...abc",
  "last_updated_at": 1640995400000,
  "nonce": "67890",
  "parent_block_id": "block_123"
}

Changes

  • f33feb7333eaRevision changes
    • warning

      added the new ADDRESS_BOOK_NOT_PARADEX_ACCOUNT enum value to the //// response property for the response status

    • warning

      added the new ADDRESS_BOOK_REPEATED_IN_IMPORT enum value to the //// response property for the response status

    • warning

      added the new STARKNET_PARENT_ONBOARDING_DISABLED enum value to the //// response property for the response status

  • ed1654c95ef8Revision changes
    • info

      removed the READY_TO_EXECUTE enum value from the //// response property for the response status