AMM Instruction API Endpoints for Automated Market Making

AMM (Automated Market Making) instructions allow you to deploy liquidity into Bullish’s on-chain AMM pools. Each instruction defines a market, an investment amount in base and quote assets, and a price range (lower and upper bounds) within which the AMM will actively make markets. AMM instructions are managed separately from orders and have their own instruction IDs. For a full conceptual guide, see the AMM Wiki.

GET /trading-api/v2/amm-instructions

Returns a paginated list of AMM instructions for the authenticated trading account. Supports pagination.

Authentication: Required. Rate limited: Yes.

Query Parameters

tradingAccountId

string

required

ID of the trading account.

symbol

string

Filter by market symbol, e.g. BTCUSD.

status

string

Filter by instruction status: OPEN or CLOSED.

_pageSize

integer

Page size. One of: 5, 25, 50, 100. Defaults to 25.

Response Fields (array of AMMInstruction objects)

instructionId

string

Unique AMM instruction ID.

liquidityId

string

Deprecated alias for instructionId.

symbol

string

Market symbol. E.g. BTCUSD.

status

string

Instruction status: OPEN or CLOSED.

statusReason

string

Human-readable status description. E.g. "Ok".

statusReasonCode

integer

Numeric status reason code.

lowerBound

string

Lower price bound for the AMM range (in quote currency). E.g. "0.0013".

upperBound

string

Upper price bound for the AMM range (in quote currency). E.g. "14000.0000".

price

string

Current AMM price. E.g. "456.7800".

basePrice

string

Current price of the base asset. E.g. "345.6700".

quotePrice

string

Current price of the quote asset. E.g. "1.0000".

baseInvestQuantity

string

Initial base asset investment. E.g. "0.00000008".

quoteInvestQuantity

string

Initial quote asset investment. E.g. "0.0009".

baseCurrentQuantity

string

Current base asset held by this instruction (only for OPEN instructions). E.g. "0.00000000".

quoteCurrentQuantity

string

Current quote asset held by this instruction (only for OPEN instructions). E.g. "0.0000".

baseWithdrawQuantity

string

Base asset returned upon termination. E.g. "0.00000010".

quoteWithdrawQuantity

string

Quote asset returned upon termination. E.g. "0.0011".

initialValue

string

USD value of invested assets at instruction creation time.

currentValue

string

Current USD value of assets held by this instruction.

finalValue

string

USD value of assets at termination (only for CLOSED instructions).

apy

string

Annualised yield percentage since instruction creation. E.g. "0.0000".

24HrApy

string

APY over the last 24 hours (only for OPEN instructions). E.g. "2.3319".

24HrYieldEarn

string

USD earned in the last 24 hours (only for OPEN instructions). E.g. "0.00".

yieldEarn

string

Total USD earned since creation.

impermanentLoss

string

Impermanent loss. E.g. "0.0000".

initialBasePrice

string

Base asset price at instruction creation. E.g. "100.0000".

initialQuotePrice

string

Quote asset price at instruction creation. E.g. "0.0100".

feeTierId

string

Fee tier identifier applied to this instruction.

baseFee

string

Base asset fee earned or charged.

quoteFee

string

Quote asset fee earned or charged.

dislocationEnabled

boolean

Whether dislocation is enabled for this instruction.

staticSpreadFee

string

Static spread fee applied to the instruction.

lastDistributedPrice

string

(Perpetual markets only) The price used at settlement time. Used for calculating mtmPnl and actual PnL.

requestId

string

Unique request ID assigned by the exchange.

createdAtDatetime

string

ISO 8601 datetime when the instruction was acknowledged.

createdAtTimestamp

string

Millisecond EPOCH timestamp when the instruction was acknowledged.

updatedAtDateTime

string

ISO 8601 datetime of the most recent update.

updatedAtTimestamp

string

Millisecond EPOCH timestamp of the most recent update.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v2/amm-instructions?tradingAccountId=111000000000001&status=OPEN" \
  -H "Authorization: Bearer <JWT>"

Example Response

{
  "data": [
    {
      "instructionId": "390755652232282200",
      "symbol": "BTCUSD",
      "status": "OPEN",
      "statusReason": "Ok",
      "statusReasonCode": 1001,
      "lowerBound": "40000.0000",
      "upperBound": "60000.0000",
      "price": "50200.0000",
      "basePrice": "50200.0000",
      "quotePrice": "1.0000",
      "baseInvestQuantity": "0.50000000",
      "quoteInvestQuantity": "25000.0000",
      "baseCurrentQuantity": "0.48000000",
      "quoteCurrentQuantity": "25100.0000",
      "apy": "3.1200",
      "feeTierId": "1",
      "dislocationEnabled": false,
      "createdAtDatetime": "2024-10-01T08:00:00.000Z",
      "createdAtTimestamp": "1727769600000"
    }
  ]
}

POST /trading-api/v2/amm-instructions

Creates a new AMM instruction. A 200 response confirms the command was acknowledged — check GET /trading-api/v2/amm-instructions/ to confirm the final status.

Authentication: Required. Rate limited: Yes.

Request Headers

Authorization

string

required

Bearer <JWT>

BX-SIGNATURE

string

required

Request signature generated using the signing format.

BX-TIMESTAMP

string

required

Milliseconds since EPOCH.

BX-NONCE

string

required

Client-side incremented unsigned 64-bit integer as a string.

Request Body Fields

commandType

string

required

Must be "V3CreateAMMInstruction".

symbol

string

required

Market symbol to invest liquidity in. E.g. "BTCUSD".

baseQuantity

string

required

Base asset quantity to invest. Strict precision not required. Use "0" to invest only quote.

quoteQuantity

string

required

Quote asset quantity to invest. E.g. "50000.1".

upperBound

string

required

Upper price bound of the AMM range in quote currency. E.g. "25000".

lowerBound

string

required

Lower price bound of the AMM range in quote currency. E.g. "20000".

feeTierId

string

required

Fee tier identifier to apply to this instruction.

tradingAccountId

string

required

ID of the trading account.

Response Fields

message

string

Acknowledgement message. E.g. "Command acknowledged - CreateAMMInstruction".

requestId

string

Unique request ID assigned by the exchange.

instructionId

string

Unique AMM instruction ID — use this to query the instruction status.

Example Request

curl -X POST "https://api.exchange.bullish.com/trading-api/v2/amm-instructions" \
  -H "Authorization: Bearer <JWT>" \
  -H "BX-SIGNATURE: <SIGNATURE>" \
  -H "BX-TIMESTAMP: 1728028800000" \
  -H "BX-NONCE: 1728028800000001" \
  -H "Content-Type: application/json" \
  -d '{
    "commandType": "V3CreateAMMInstruction",
    "symbol": "BTCUSD",
    "baseQuantity": "0",
    "quoteQuantity": "50000.1",
    "upperBound": "25000",
    "lowerBound": "20000",
    "feeTierId": "1",
    "tradingAccountId": "111000000000001"
  }'

Example Response

{
  "message": "Command acknowledged - CreateAMMInstruction",
  "requestId": "633910976353665024",
  "instructionId": "633910775316480002"
}

GET /trading-api/v2/amm-instructions/

Retrieves a specific AMM instruction by its unique instruction ID.

Authentication: Required. Rate limited: Yes.

Path Parameters

instructionId

number

required

Unique AMM instruction ID returned at creation.

Query Parameters

tradingAccountId

string

required

ID of the trading account that owns the instruction.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v2/amm-instructions/633910775316480002?tradingAccountId=111000000000001" \
  -H "Authorization: Bearer <JWT>"

Example Response

{
  "instructionId": "633910775316480002",
  "symbol": "BTCUSD",
  "status": "OPEN",
  "statusReason": "Ok",
  "statusReasonCode": 1001,
  "lowerBound": "20000",
  "upperBound": "25000",
  "price": "22500.0000",
  "baseInvestQuantity": "0.00000000",
  "quoteInvestQuantity": "50000.1",
  "baseCurrentQuantity": "0.00000000",
  "quoteCurrentQuantity": "50000.1",
  "apy": "0.0000",
  "feeTierId": "1",
  "dislocationEnabled": false,
  "createdAtDatetime": "2024-10-04T08:00:00.000Z",
  "createdAtTimestamp": "1728028800000"
}

Terminating an AMM Instruction

To terminate an active AMM instruction, submit a V3TerminateAMMInstruction command via POST /trading-api/v2/command.

{
  "commandType": "V3TerminateAMMInstruction",
  "instructionId": "633910775316480002",
  "symbol": "BTCUSD",
  "tradingAccountId": "111000000000001"
}

Trading API

Custody API

Aggregator API

AMM Instruction API Endpoints for Automated Market Making

GET /trading-api/v2/amm-instructions

Query Parameters

Response Fields (array of AMMInstruction objects)

Example Request

Example Response

POST /trading-api/v2/amm-instructions

Request Headers

Request Body Fields

Response Fields

Example Request

Example Response

GET /trading-api/v2/amm-instructions/

Path Parameters

Query Parameters

Example Request

Example Response

Terminating an AMM Instruction

Build docs developers (and LLMs) love

Trading API

Custody API

Aggregator API

Documentation Index

​GET /trading-api/v2/amm-instructions

​Query Parameters

​Response Fields (array of AMMInstruction objects)

​Example Request

​Example Response

​POST /trading-api/v2/amm-instructions

​Request Headers

​Request Body Fields

​Response Fields

​Example Request

​Example Response

​GET /trading-api/v2/amm-instructions/

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Terminating an AMM Instruction

Build docs developers (and LLMs) love

GET /trading-api/v2/amm-instructions

Query Parameters

Response Fields (array of AMMInstruction objects)

Example Request

Example Response

POST /trading-api/v2/amm-instructions

Request Headers

Request Body Fields

Response Fields

Example Request

Example Response

GET /trading-api/v2/amm-instructions/

Path Parameters

Query Parameters

Example Request

Example Response

Terminating an AMM Instruction