Integrate investments

Let your users trade stocks, bonds, letras and CEDEARs in the Argentine market, and buy or sell USD through Dólar MEP (Broker as a Service).

At a glance

  • Users: Each user is onboarded in Broker and must be ACTIVE. Compliance and deposit limits apply to the person (their CUIT), shared across every company where that person has a user.
  • Funds: Users fund their balance with ARS or USD transfers from a bank account in their own name. Buys run against a company-level ARS/USD overdraft (debt) that is settled at end of day; see Operating model.
  • Tracking: order-status-update, synthetic-status-update and deposit-status-update webhooks, or poll GET /broker/v1/api/order/{orderAnyId}.

How it works

  1. The user answers the investor questionnaire and you create them with their personal and bank data.
  2. You follow the onboarding status until the user is ACTIVE.
  3. The user deposits ARS or USD from their own bank account.
  4. You read the instrument and its price, preview the order, and create it.
  5. The order goes to market; order-status-update reports each status until COMPLETED.

Before you start

  • Broker endpoints live under /broker/v1/api/....
  • Configure webhooks with PUT /broker/v1/api/company. Events without their own URL in webhooks go to generalWebhook. Your endpoint must accept POST over HTTPS, answer 2xx quickly and process deliveries idempotently, since failed deliveries are retried. See Broker webhooks for the signature and the retry schedule.
{
  "notificationInfo": {
    "type": "WEBHOOK",
    "secret": "your-webhook-secret",
    "generalWebhook": "https://your-domain.com/webhooks/manteca",
    "webhooks": {
      "order-status-update": "https://your-domain.com/webhooks/manteca/orders"
    }
  }
}

Webhooks are sent from four fixed IP addresses: allowlist all of them (see Broker webhooks).

1

Get the investor profile

The investor profile (investorExperience, investorType) is part of the user's personal data. To get it, fetch the questionnaire with GET /broker/v1/api/onboarding/investingQuiz, show it to the user, and send their answers. Include the resulting profile in the user's personalData in the next step.

Request POST /broker/v1/api/onboarding/investingQuiz

{
  "quiz": [
    { "question": "Tenés experiencia en operatoria/inversiones en", "answer": "Ninguna" },
    { "question": "Calificá tu situación financiera y económica actual", "answer": "Óptima" }
  ]
}

Response

{
  "investorExperience": "Limitada",
  "investorType": "Moderado"
}
2

Onboard the user

Create the user with their CUIT, personal data and at least one bank account in their name. Send as much data as you have: it increases the chance of automatic approval.

Request POST /broker/v1/api/onboarding/initial

{
  "email": "[email protected]",
  "legalId": "20300000003",
  "externalId": "inv-user-001",
  "personalData": {
    "name": "JUAN",
    "surname": "PEREZ",
    "work": "TRABAJADOR RELAC. DEPENDENCIA",
    "sex": "M",
    "maritalStatus": "Soltero",
    "isPep": false,
    "isFatca": false,
    "isUif": false,
    "phoneNumber": "1100000000",
    "nationality": "Argentina",
    "investorExperience": "Limitada",
    "investorType": "Moderado"
  },
  "banking": {
    "accounts": [
      { "cbu": "juan.perez.ars", "currency": "ARS", "description": "ARS account" },
      { "cbu": "juan.perez.usd", "currency": "USD", "description": "USD account" }
    ]
  }
}

Response (trimmed)

{
  "user": {
    "id": "6596e960e140a030749b4e23",
    "numberId": "10416",
    "externalId": "inv-user-001",
    "status": "EMAIL_VALIDATED"
  },
  "causedConflict": false
}

Any of the user's id, numberId or externalId works as userAnyId. externalId is optional; it comes back in user and in the user's webhooks.

If isPep is true, add pepData to personalData with the charge, the authority and the character: DIRECT when the person holds the office, INDIRECT when they are related to someone who does.

{ "charge": "Legal secretary", "authority": "Provincial Attorney General", "character": "DIRECT" }

The common rejections are 409 USER_EXISTS, USER_EXISTS_EMAIL or EMAIL_EXISTS (the user or the email is already registered), 409 INVALID_CBU or INACTIVE_ADDRESS (the bank account is invalid or inactive), and 400 COIN_MISMATCH or CUIT_MISMATCH (the account currency or holder does not match). See Errors and controls.

3

Wait until the user is active

GET /broker/v1/api/onboarding/status/USERANYID returns the steps still pending, each with a code, a message and, when data is missing, the fields to complete:

[
  {
    "code": "MISSING_PERSONAL_DATA",
    "message": "needs to modify person with missing data",
    "fields": ["personalData.work"]
  },
  {
    "code": "AWAITING_DNI_UPLOAD",
    "message": "awaiting upload of dni images"
  }
]

The user's status usually moves EMAIL_VALIDATED, USER_DATA_COMPLETE, VALIDATING, VALIDATED, ACTIVE, and user-status-update reports each change. The user can operate only when it is ACTIVE. VALIDATION_FAILED means the identity check failed and the documents must be uploaded again; ONBOARDING_FAILED means an external registration step failed and Manteca has to intervene. All statuses: Onboarding overview.

Compliance data is kept per person (the CUIT). When data was not sent at creation and could not be retrieved from official sources, the person stays incomplete. Read it with GET /broker/v1/api/compliance/person/{legalId} and complete it with PUT /broker/v1/api/compliance/person/{legalId}, sending only the fields to change in personalData or flags.

Upload identity documents in two steps: request a pre-signed URL with POST /broker/v1/api/compliance/documentation/uploadUrl, then send the file binary to that URL with a PUT. The body takes associatedId (the person's CUIT), associatedSubId (the numberId), fileName, docType and an optional externalId. Individuals upload DNI_FRONT, DNI_BACK and SELFIE; businesses upload BYLAWS, AUTHORITIES, STAKEHOLDERS and BALANCE, as described in Onboarding a company. DNI images must be .jpg, .jpeg, .png or .webp. Each processed document is reported with documentation-status-update, and you can read them with GET /broker/v1/api/compliance/documentation (filter by associatedId, docType or status) or GET /broker/v1/api/compliance/documentation/{documentationId}. The upload returns 409 INVALID_DOCUMENTATION_FORMAT for a wrong file type, 409 DOCUMENTATION_PENDING when a document of that type is still under review, and 409 DOCUMENTATION_EXISTS when it is already approved or the externalId was used.

4

Fund the user

The user transfers ARS or USD from a bank account in their own name (same CUIT). Manteca matches the transfer to the user and credits their balance. Only credited deposits are notified:

{
  "eventName": "deposit-status-update",
  "data": {
    "status": "ASSIGNED",
    "deposit": {
      "id": "66b2362f68e708c917d3c618",
      "userId": "6596e960e140a030749b4e23",
      "numberId": "10416",
      "amount": 1000000,
      "coin": "ARS",
      "status": "ASSIGNED"
    }
  }
}

Each person has a yearly deposit ceiling. When it is reached, deposits and operations return 403 PERSON_DEPOSIT_LIMIT until the person submits a source-of-funds document: see Deposit limits and source of funds. Read the ceiling and what was used with GET /broker/v1/api/compliance/person/{legalId}/limits; USD deposits count at the MEP rate. Read the balance with GET /broker/v1/api/balance/USERANYID.

5

Pick the instrument and read its price

List what can be traded with GET /broker/v1/api/price/instruments (filter with ?assetType=BOND, STOCK, CEDEAR, LETTER...). Each instrument has its settlement, minTradeVol, maxTradeVol and tickSize.

Request GET /broker/v1/api/price/{ticker} with ticker=AL30 and ?against=ARS&settlement=INSTANT

Response (trimmed)

{
  "ticker": "AL30 - CI",
  "buy": 62880,
  "sell": 62710,
  "last": 62880,
  "variation": { "daily": -0.00883 },
  "timestamp": 1722011191979
}

Bond prices are per 100 units of the instrument.

6

Preview the order

Show the user the fees and the estimated total before they confirm. Send exactly one of assetAmount (whole units of the instrument) or againstAmount (currency). type is MARKET or LIMIT; a LIMIT order needs price (per 100 units). settlement is INSTANT or DAY.

Request POST /broker/v1/api/info/order/preview

{
  "userAnyId": "10416",
  "side": "BUY",
  "type": "MARKET",
  "settlement": "INSTANT",
  "asset": "AL30",
  "against": "ARS",
  "assetAmount": "10"
}

Response (trimmed)

{
  "side": "BUY",
  "asset": "AL30",
  "against": "ARS",
  "price": 62730,
  "draftClaimInfo": { "asset": "ARS", "total": 6321, "base": 6273, "totalFees": 48 },
  "draftCreditInfo": { "asset": "AL30", "total": 10 }
}

draftClaimInfo is what leaves the balance and draftCreditInfo what enters it. The final amounts depend on the market execution.

7

Create the order

Send the same body to create the order, plus your externalId so a retry cannot create a second order.

Request POST /broker/v1/api/order

{
  "userAnyId": "10416",
  "side": "BUY",
  "type": "MARKET",
  "settlement": "INSTANT",
  "asset": "AL30",
  "against": "ARS",
  "assetAmount": "10",
  "externalId": "693cacbe-da94-4adc-af41-056028f988ae"
}

Response (trimmed)

{
  "id": "65bbe29cfbe4be99d4be0378",
  "numberId": "10416",
  "externalId": "693cacbe-da94-4adc-af41-056028f988ae",
  "status": "PENDING",
  "side": "BUY",
  "type": "MARKET",
  "asset": "AL30",
  "against": "ARS",
  "amount": 10,
  "filledAmount": 0,
  "finalClaimInfo": { "asset": "ARS", "total": 6321 }
}

The order is created PENDING and executes in the market afterwards. To sell, send side: "SELL". A pending order can be cancelled with DELETE /broker/v1/api/order/{orderAnyId}.

8

Track the operation

Handle order-status-update until the order reaches a final status:

{
  "eventName": "order-status-update",
  "data": {
    "status": "COMPLETED",
    "order": {
      "id": "65bbe29cfbe4be99d4be0378",
      "externalId": "693cacbe-da94-4adc-af41-056028f988ae",
      "asset": "AL30",
      "side": "BUY",
      "amount": 10,
      "filledAmount": 10,
      "status": "COMPLETED",
      "finalClaimInfo": { "asset": "ARS", "total": 6304.4 },
      "finalCreditInfo": { "asset": "AL30", "total": 10 }
    }
  }
}
StatusWhat to do
PENDINGCreated, not yet sent to market. Wait.
SENTAt market. Wait.
COMPLETEDExecuted. Use filledAmount, finalClaimInfo and finalCreditInfo as the final result.
FAILEDSent but could not complete. Show the error and let the user retry.
CANCELLEDCancelled before completing.

A partially executed order has filledAmount below amount. Poll GET /broker/v1/api/order/{orderAnyId} when a webhook is late, and deduplicate webhooks by order id and status. To reconcile, list orders with GET /broker/v1/api/order filtered by externalId, status, asset or a from/to range.

Dólar MEP

Dólar MEP buys USD with ARS (or the reverse) by buying a bond in one currency and selling it in the other. Broker runs both legs as one synthetic. Read the rate with GET /broker/v1/api/price/synthetic/mep/{asset}, then create it:

Request POST /broker/v1/api/synthetic/dolarMep

{
  "userAnyId": "10416",
  "side": "BUY",
  "asset": "AL30",
  "amount": "1000",
  "settlement": "INSTANT",
  "externalId": "mep-0001"
}

The response is a synthetic in STARTING with its two stages. synthetic-status-update reports ACTIVE while a leg is at market, WAITING during a regulatory window between legs (it resumes by itself), and COMPLETED at the end. details.operatedAmount is the amount actually traded, which can differ from the amount you sent. See Dólar MEP for all statuses and pause/resume.

Dividends and coupons

Holdings can generate income (dividends, coupons, amortizations), reported with holding-income-status-update. When the income carries fees in a currency the user has no balance in, it arrives as LOCKED_BY_FEES: once the user has the funds, confirm it with POST /broker/v1/api/holdingIncome/{holdingIncomeId}. See Dividends.

Test in sandbox

Credit a sandbox user without a bank transfer with POST /broker/v1/api/banking/deposit (sandbox only). userId is the user's id. The deposit is created already ASSIGNED.

{
  "userId": "6596e960e140a030749b4e23",
  "coin": "ARS",
  "amount": 100000,
  "externalId": "test-dep-0001"
}

Errors

Handle errors by internalStatus, not by HTTP status.

Full lists: Orders and Errors and controls.

Go deeper


Did this page help you?