Trading (CEDEARs, Stocks & Bonds) – Integration Guide

The Trading module allows your platform to offer users full buy and sell operations for instruments on the Argentine capital market: CEDEARs, stocks, and bonds. Integration is 100% via APIs and webhooks.

Your users can browse instruments and prices, submit buy and sell orders, track the status of their operations, and view their portfolio in real time.

Prerequisites

Onboarding

To operate Trading, the user must have an active brokerage account. The onboarding flow is the same as in all other modules:

1. POST /v2/persons → generates the person_id
2. POST /identity-documents → uploads identity documentation
3. POST /v2/investment-accounts → generates the investment_account_id
4. POST /bank-accounts → generates the bank_account_id (recommended to enable withdrawals)

Without an active brokerage account, it is not possible to trade market instruments.

Deposits (Cash In)

Before submitting orders, the user must have available balance in their brokerage account. The process is the same as in all other modules: the user transfers to the collection account and API Broker automatically credits the balance, notifying the partner via the deposit_create webhook.

Integration Flow

a. Instrument Lookup

Before trading, your platform can query the full catalog of available instruments.

Get all instruments: GET /api/instruments/market/all

Returns the complete list of CEDEARs, stocks, and bonds available for trading.

Recommendation: store the instruments in your database and refresh them periodically (e.g. once a day). Use this catalog for searches by ticker, asset type, or market.

Get instrument by ID: GET /api/instruments/market/{market_instrument_id}

b. Price Lookup

Once an instrument is selected, you can query its latest available price. GET /api/prices/market-instrumentsprices/{market_instrument_id}

Useful for displaying prices in the UI, estimating buy or sell amounts, and validating available balance before submitting orders.

c. Submitting Orders

With the instrument and price defined, submit the buy or sell order: POST /api/market/market-order

Body params:

Example body:

{
  "investment_account_id": 7403,
  "quantity": 10,
  "amount": 50000,
  "currency_id": "ARS",
  "market_instrument_id": 1234,
  "market_operation_type": "buy",
  "instrument_price": 5000,
  "term": 2,
  "external_id": "order-abc-001",
  "by_amount": false,
  "at_market_price": false
}

Possible responses:

Note on idempotency: the external_id field is required and must be unique per operation. If the same external_id is submitted again, the API will return 409 instead of creating a duplicate order.

Note on by_amount vs quantity: when by_amount is true, the system uses the amount field to determine how many units to buy at the available price. When false, it uses the quantity field directly.

d. Order Statuses

Submitted orders can go through the following statuses. It is important to distinguish temporary from final statuses in order to reflect them correctly in your UI.

e. Querying Order Status

Once the order is submitted, the partner can check its status at any time using the market_order_id returned by POST /api/market/market-order. GET /api/market/market-order/{market_order_id}

Parameters:

Possible responses:

Note: This endpoint is useful for point-in-time queries and reconciliation. For real-time tracking, implement the market_order_update webhook.

f. Retrieving Market Order Tickets

After operations are executed, the partner can retrieve the tickets (market confirmations) associated with a brokerage account. This is useful for showing receipts to the user or for reconciliation processes. GET /api/market/stock-market-confirmations/confirmations-by-investment-account/{investment_account_id}

Path params:

Optional query params:

Example: GET /api/market/stock-market-confirmations/confirmations-by-investment-account/7403?from_date=2024-09-01&to_date=2024-09-30&page=1&size=50

Possible responses:

Note: Tickets include the detail of each executed operation (instrument, price, quantity, amount). This endpoint is recommended for generating downloadable receipts for the end user.

g. Account, Balances & Holdings

Retrieve the current state of the user's brokerage account. GET /api/portfolio/account-statements/{investment_account_id}

This endpoint is key for validating balance before submitting orders, displaying the user's portfolio, and reflecting the impact of executed orders.

h. Cash Out

Once the user has available funds in their brokerage account, they can withdraw them to a same-name bank account: POST /withdraw-requests

API Broker notifies withdrawal status changes via the withdraw_request_update webhook.

Possible statuses: IN_PROGRESS → COMPLETED / REJECTED

Main Endpoints

Webhooks to Implement

Your platform must expose a URL to receive the following events:

deposit_create Notifies credited deposits: investment_account_id, currency, amount, and date.

market_order_update Notifies order status changes.

withdraw_request_update Notifies withdrawal status: IN_PROGRESS, COMPLETED, or REJECTED.

Webhooks keep operational state in sync without the need for constant polling.

Operational Considerations

• Instrument cache: store the instrument catalog and refresh it periodically. Do not query the endpoint on every operation.
• Pre-validation: checking balance and holdings before submitting orders prevents unnecessary rejections.
• Final vs temporary statuses: handle them differently in your UI to avoid confusing the user.
• Partial and expired orders: reflect them clearly in the user's portfolio.
• Market hours: account for BYMA's operating hours and daily close when managing orders.
• Idempotency: use external_id in orders to avoid duplicates on retries.

Development & Integration Support

API Broker provides direct support throughout the integration process.

Technical support: API and webhook implementation, security, order state management, joint testing on staging.

Business support: revenue share model, partner regulatory onboarding, module adoption strategy.

Operational support: order monitoring, deposit and withdrawal reconciliation, Adcap trading desk as backup.

Support is available on market business days from 9 AM to 6 PM.

Key Points to Remember

1. Onboarding is a prerequisite: without an active brokerage account, trading is not possible.
2. Balance must be available before submitting orders: always validate via account statements.
3. Distinguish temporary from final statuses: COMPLETED, REJECTED, NOT_SENT, EXPIRED, and CANCELLED are final statuses.
4. Partial orders can be temporary or final depending on whether they are from the current day or a prior day.
5. Cache the instrument catalog and refresh periodically — not on every operation.
6. Withdrawals are only to same-name accounts: third-party transfers are not allowed.
7. Everything is asynchronous: always track status via webhooks.