primary

Primary — Matba ROFEX 交易 API

通过 Primary Trading Platform (PTP) 在阿根廷期货与期权市场（Matba ROFEX）进行交易的 API。支持期货（美元、大豆、小麦、玉米、指数）、期货期权、股票、债券和 CEDEARs。

Base URL： https://api.remarkets.primary.com.ar

文档： github.com/matbarofex — 官方开源示例仓库。

---

身份验证

获取凭据

环境	URL	描述
REMARKET（演示）	remarkets.primary.ventures	创建免费账户以进行模拟交易
LIVE（生产）	联系 [email protected]	向 MPI 团队申请访问权限

创建 REMARKET 账户后，你将获得：

• 用户名：你注册时使用的用户名
• 密码：你设置的密码
• Account：你的账户号码（通常为 REM + 用户名的末几位数字）

获取令牌

import requests

r = requests.post("https://api.remarkets.primary.com.ar/auth/getToken",
    headers={"X-Username": tu_usuario, "X-Password": tu_password})

token = r.headers["X-Auth-Token"]

之后，所有请求都通过 X-Auth-Token 请求头发送令牌。

⚠️ 切勿将凭据硬编码。请使用环境变量或 CLI 参数。

import os
TOKEN = os.getenv("PRIMARY_TOKEN")  # Opcional: cachear token
USER = os.getenv("PRIMARY_USER")
PASS = os.getenv("PRIMARY_PASSWORD")
ACCOUNT = os.getenv("PRIMARY_ACCOUNT")  # Ej: 12345 o REM12345

续期令牌

如果收到 401 错误，说明令牌已过期。向 /auth/getToken 重新发送 POST 请求以续期。

---

交易板块

市场按交易板块（交易时段）组织。每种工具都属于一个交易板块。

交易板块	描述
DDF	金融衍生品（美元、指数期货）
DDA	农产品衍生品（大豆、小麦、玉米）
DUAL	在两个分区上市的工具
MERV	Matba ROFEX 以外的市场（BYMA）
MAE	电子开放市场
TEST	测试环境
U-DDF、U-DDA、U-DUAL、U-FIN、U-COMM、U-STOCK	用户子板块
TIVA、AVS	其他交易板块

列出交易板块

GET https://api.remarkets.primary.com.ar/rest/segment/all

r = requests.get("https://api.remarkets.primary.com.ar/rest/segment/all",
    headers={"X-Auth-Token": token})
print(r.json()["segments"])

响应：

{"status":"OK","segments":[
  {"marketSegmentId":"DDF","marketId":"ROFX"},
  {"marketSegmentId":"DDA","marketId":"ROFX"},
  ...
]}

---

工具（Securities）

工具通过其代码和 marketId 标识。示例：

代码	描述	CFI Code
DLR/JUN26	2026 年 6 月美元期货	FXXXSX
SOJ.ROS/MAY26	2026 年 5 月罗萨里奥大豆期货	FXXXSX
DLR/JUN26 1460 C	美元期货看涨期权	OCAFXS
DLR/JUN26 1420 P	美元期货看跌期权	OPAFXS
GGAL	Grupo Galicia 股票	ESXXXX

所有工具

GET https://api.remarkets.primary.com.ar/rest/instruments/all

带详情的工具

GET https://api.remarkets.primary.com.ar/rest/instruments/details

返回：symbol、segment、lowLimitPrice、highLimitPrice、minPriceIncrement、minTradeVol、maxTradeVol、tickSize、contractMultiplier、roundLot、maturityDate、currency、orderTypes、timesInForce、cficode。

单个工具详情

GET https://api.remarkets.primary.com.ar/rest/instruments/detail?symbol=DLR/JUN26&marketId=ROFX

按 CFI Code 查询

GET https://api.remarkets.primary.com.ar/rest/instruments/byCFICode?CFICode=FXXXSX

CFI Code	类型
FXXXSX	期货
FXXXXX	期货（通用）
OCAFXS	期货看涨期权
OPAFXS	期货看跌期权
OCEFXS	欧式期货看涨期权
OPEFXS	欧式期货看跌期权
ESXXXX	股票
DBXXXX	债券
EMXXXX	CEDEAR
OCASPS	股票看涨期权
OPASPS	股票看跌期权
DBXXFR	可转让债务证券

按交易板块查询

GET https://api.remarkets.primary.com.ar/rest/instruments/bySegment?MarketSegmentID=DDF&MarketID=ROFX

---

市场数据

实时（REST 快照）

GET https://api.remarkets.primary.com.ar/rest/marketdata/get
    ?marketId=ROFX
    &symbol=DLR/JUN26
    &entries=BI,OF,LA,OP,CL,SE,OI
    &depth=3

条目	含义
BI	买价（订单簿中的买入报价）
OF	卖价（订单簿中的卖出报价）
LA	最新价（最后成交价）
OP	开盘价
CL	收盘价（上一交易日收盘价）
SE	结算价（仅限期货）
HI	最高价（当日最高价）
LO	最低价（当日最低价）
TV	成交量（合约数量）
OI	未平仓量（仅限期货）
IV	指数值（仅限指数）
EV	有效成交量（仅限 BYMA）
NV	名义成交量（仅限 BYMA）
ACP	集合竞价价格（当日收盘价）

r = requests.get("https://api.remarkets.primary.com.ar/rest/marketdata/get",
    headers={"X-Auth-Token": token},
    params={"marketId": "ROFX", "symbol": "DLR/JUN26",
            "entries": "BI,OF,LA,OP,CL,SE,OI", "depth": 3})
data = r.json()["marketData"]
print(f"Bid: {data['BI']}  |  Offer: {data['OF']}")
print(f"Last: {data['LA']}  |  Settle: {data['SE']}")

历史数据（成交记录）

GET https://api.remarkets.primary.com.ar/rest/data/getTrades
    ?marketId=ROFX
    &symbol=DLR/JUN26
    &dateFrom=2026-06-01
    &dateTo=2026-06-08

参数：marketId、symbol、date（单个日期）、dateFrom/dateTo（日期范围）、external（用于外部市场）、environment（REMARKETS）。

r = requests.get("https://api.remarkets.primary.com.ar/rest/data/getTrades",
    headers={"X-Auth-Token": token},
    params={"marketId": "ROFX", "symbol": "DLR/JUN26",
            "date": "2026-06-05"})
trades = r.json()["trades"]
for t in trades[:3]:
    print(f"{t['datetime']}  {t['price']}  {t['size']}")

---

订单

订单类型

类型	描述
LIMIT	限价单
MARKET	市价单
STOP_LIMIT	触发后作为限价单执行的止损单
MARKET_TO_LIMIT	转换为限价单的市价单

注意：并非所有工具都支持 STOP_LIMIT 和 MARKET_TO_LIMIT。请在工具详情中检查 orderTypes。

有效时限（TIF）

TIF	描述
DAY	仅当日有效，交易日结束时到期
IOC	立即成交或取消
FOK	全部成交或取消
GTD	截止日期有效（需要 expireDate）

提交订单（REST）

GET https://api.remarkets.primary.com.ar/rest/order/newSingleOrder
    ?marketId=ROFX
    &symbol=DLR/JUN26
    &side=BUY
    &orderQty=10
    &ordType=LIMIT
    &price=1450.0
    &timeInForce=DAY
    &account=TU_CUENTA
    &cancelPrevious=False
    &iceberg=False

参数：

参数	类型	必填	描述
marketId	String	✅	ROFX
symbol	String	✅	工具代码
side	String	✅	BUY 或 SELL
orderQty	Integer	✅	合约数量
ordType	String	✅	LIMIT 或 MARKET
price	Float	条件必填	LIMIT 类型必填
timeInForce	String	否	DAY（默认）、IOC、FOK、GTD
account	Integer/String	✅	账户编号
cancelPrevious	Boolean	否	取消同一合约、同一方向的先前订单
iceberg	Boolean	否	冰山订单（默认：false）
displayQty	Integer	条件必填	显示数量（用于冰山订单）
expireDate	Date	条件必填	GTD 必填（格式：YYYYMMDD）

响应：

{"status":"OK","order":{"clientId":"21581341758","proprietary":"PBCP"}}

clientId 是用于查询/取消订单的 clOrdId（客户端订单 ID）。

提交订单（WebSocket）

{"type":"no","product":{"marketId":"ROFX","symbol":"DLR/JUN26"},
 "price":185,"quantity":23,"side":"BUY","account":"20","iceberg":false}

若要通过 WebSocket 识别订单，请包含 wsClOrdId：

{"type":"no","product":{"marketId":"ROFX","symbol":"DLR/JUN26"},
 "price":185,"quantity":23,"side":"BUY","account":"20",
 "iceberg":false,"wsClOrdId":"mioid-unico-123"}

WebSocket 响应（执行报告）：

{"type":"or","orderReport":{"orderId":"1128056","clOrdId":"user14545...",
 "status":"PENDING_NEW","text":"Enviada","wsClOrdId":"mioid-unico-123"}}

重要： wsClOrdId 仅出现在第一条执行报告中。之后应使用返回的 clOrdId 进行跟踪。

修改订单

GET https://api.remarkets.primary.com.ar/rest/order/replaceById
    ?clOrdId=user144733478280357
    &proprietary=api
    &price=17
    &orderQty=10

取消订单

GET https://api.remarkets.primary.com.ar/rest/order/cancelById
    ?clOrdId=ajduj3l13ieci2jr4ck
    &proprietary=PBCP

通过 WebSocket 取消

{"type":"co","clientId":"user114121092035207","proprietary":"PBCP"}

查询订单状态（REST）

端点	描述
GET /rest/order/id?clOrdId=...&proprietary=api	请求的最新状态
GET /rest/order/allById?clOrdId=...&proprietary=api	请求的所有状态
GET /rest/order/byOrderId?orderId=...	按订单 ID 查询状态
GET /rest/order/actives?accountId=10	活跃订单（NEW 或 PARTIALLY_FILLED）
GET /rest/order/filleds?accountId=10	全部或部分成交的订单
GET /rest/order/all?accountId=10	账户的所有状态
GET /rest/order/byExecId?execId=T1234567	按执行 ID 查询状态

执行报告（WebSocket）

订阅一个账户：

{"type":"os","account":{"id":"40"}}

多个账户：

{"type":"os","accounts":[{"id":"40"},{"id":"4000"}]}

所有账户：

{"type":"os"}

仅活跃订单：

{"type":"os","snapshotOnlyActive":true}

---

Risk API

Risk API 使用HTTP Basic Auth，用户名和密码相同，不使用令牌。除 X-Auth-Token 外，还需要额外提供 Authorization: Basic <base64> 请求头。

import base64
auth = base64.b64encode(f"{user}:{password}".encode()).decode()
headers = {"X-Auth-Token": token, "Authorization": f"Basic {auth}"}

账户持仓

GET https://api.remarkets.primary.com.ar/rest/risk/position/getPositions/{accountName}

r = requests.get(f"https://api.remarkets.primary.com.ar/rest/risk/position/getPositions/TU_CUENTA",
    headers=headers)
positions = r.json()["positions"]
for p in positions:
    print(f"{p['symbol']}  Buy:{p['buySize']}  Sell:{p['sellSize']}  Diff:{p['totalDiff']}")

详细持仓

GET https://api.remarkets.primary.com.ar/rest/risk/detailedPosition/{accountName}

按工具返回明细，包含：contractType、marketPrice、currency、exchangeRate、contractMultiplier、buyCurrentSize、sellCurrentSize、detailedDailyDiff。

账户报告

GET https://api.remarkets.primary.com.ar/rest/risk/accountReport/{accountName}

import base64
auth = base64.b64encode(f"{user}:{password}".encode()).decode()
headers = {"X-Auth-Token": token, "Authorization": f"Basic {auth}"}
r = requests.get(f"https://api.remarkets.primary.com.ar/rest/risk/accountReport/TU_CUENTA",
    headers=headers)
data = r.json()["accountData"]
print(f"Colateral: {data['collateral']}")
print(f"Margen: {data['margin']}")
print(f"Disponible: {data['availableToCollateral']}")
# Saldos por moneda
for moneda, saldo in data['detailedAccountReports']['0']['currencyBalance']['detailedCurrencyBalance'].items():
    print(f"  {moneda}: consumido={saldo['consumed']}  disponible={saldo['available']}")

---

WebSocket

URL： wss://api.remarkets.primary.com.ar/

WebSocket API 会接收异步消息。连接时通过请求头发送令牌：

import websocket

ws = websocket.WebSocketApp(
    "wss://api.remarkets.primary.com.ar/",
    header=[f"X-Auth-Token: {token}"],
    on_open=on_open,
    on_message=on_message,
    ...
)
ws.run_forever()

消息格式如下：

type	含义
no	New Order（发送订单）
co	Cancel Order（取消订单）
or	Order Report（收到的执行报告）
os	Order Subscription（订阅报告）
smd	Subscribe Market Data（订阅市场数据）
Md	Market Data（收到的市场数据）

通过 WebSocket 获取市场数据

{"type":"smd","level":1,"entries":["OF","BI","LA"],
 "products":[{"symbol":"DLR/JUN26","marketId":"ROFX"}],"depth":2}

响应：

{"type":"Md","instrumentId":{"marketId":"ROFX","symbol":"DLR/JUN26"},
 "marketData":{"OF":[{"price":189,"size":21},{"price":188,"size":13}]}}

---

订单状态

状态	含义
PENDING_NEW	已发送至市场，尚未处理
NEW	已接受，在订单簿中处于活动状态
PARTIALLY_FILLED	部分成交
FILLED	全部成交
CANCELLED	已取消
REJECTED	已拒绝（查看 text 了解原因）
PENDING_CANCEL	正在取消
PENDING_REPLACE	正在替换
REPLACED	已替换
PENDING_APPROVAL	等待批准

---

常见错误

错误	原因	解决方案
401 Unauthorized	令牌无效或已过期	通过 /auth/getToken 续期
"No tiene acceso a la cuenta"	Account ID 不正确	检查 accountId
"Product doesn't exist"	Symbol 不正确	通过 instruments/all 检查 symbol
"Access Denied"	没有该端点的权限	检查 segment/method
"Ruta invalida"	端点不存在	检查 URL
Bid/Offer 为空	市场已关闭或流动性不足	在交易时段内查询

---

示例脚本

请参阅 ./scripts/：

# Autenticación y token (opcional, los scripts hacen login automático)
export PRIMARY_USER="tu_usuario"
export PRIMARY_PASSWORD="tu_password"
export PRIMARY_ACCOUNT="TU_CUENTA"

# Listar segmentos e instrumentos
python scripts/instruments.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD

# Market data de un futuro
python scripts/market_data.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD \
    --symbol DLR/JUN26 --entries BI,OF,LA

# Ver reporte de cuenta
python scripts/check_account.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD \
    --account TU_CUENTA

# Ver posiciones
python scripts/check_positions.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD \
    --account TU_CUENTA

# Enviar orden (¡cuidado! orden real en live)
python scripts/place_order.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD \
    --symbol DLR/JUN26 --side BUY --qty 1 --type LIMIT --price 1450 --account TU_CUENTA

# WebSocket: Market Data en tiempo real
python scripts/websocket_md.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD \
    --symbols DLR/JUN26 --entries BI,OF,LA --depth 3

# WebSocket: Execution Reports
python scripts/websocket_orders.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD \
    --account TU_CUENTA

# WebSocket: Enviar orden (requiere suscripción a execution reports aparte)
python scripts/websocket_send_order.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD \
    --symbol DLR/JUN26 --side BUY --qty 1 --type LIMIT --price 1450 --account TU_CUENTA

# WebSocket: Cancelar orden
python scripts/websocket_send_order.py --user $PRIMARY_USER --password $PRIMARY_PASSWORD \
    --cancel --clordid user12345... --proprietary PBCP

---

字段术语表

字段	描述
clOrdId	Client Order ID — 发送至市场的请求 ID
orderId	Order ID — 市场中的订单 ID
execId	Execution ID — 单笔成交的 ID
proprietary	发送订单的 FIX 用户（PBCP 或 ISV_PBCP）
wsClOrdId	通过 WebSocket 发送的订单 ID（仅出现在第 1 份报告中）
avgPx	平均成交价格
cumQty	累计成交数量
leavesQty	剩余数量
lastPx	最新成交价格
lastQty	最新成交数量
transactTime	交易日期和时间
tickSize	最小数量增量
minPriceIncrement	最小价格增量（价格跳动单位）
contractMultiplier	合约乘数
maturityDate	到期日
priceConvertionFactor	单位价格换算系数
lowLimitPrice	最低价格限制
highLimitPrice	最高价格限制