Integrate exchange and trading

Let your users deposit, buy, sell and withdraw crypto from a balance they hold in Manteca (Crypto as a Service). Each trade is a price lock followed by an order, and both run against the user's balance.

At a glance

  • Users: Each end user is onboarded in Manteca and must be ACTIVE before trading. To trade on your company's own account, send the userAnyId of your principal account in the same endpoints.
  • Funds: Users fund their balance with crypto or fiat deposits. Orders debit and credit that balance; withdrawals send it out to a wallet or a bank account.
  • Tracking: DEPOSIT_DETECTED, ORDER_STATUS_UPDATE and WITHDRAW_STATUS_UPDATE webhooks, or poll GET /crypto/v2/orders/{orderAnyId} and GET /crypto/v2/withdraws/{withdrawAnyId}.

How it works

  1. Onboard the user and wait until they are ACTIVE.
  2. The user deposits crypto or fiat. DEPOSIT_DETECTED arrives once the funds are in their balance.
  3. You read the price, lock it, and create the order with the lock code. The order comes back COMPLETED.
  4. The user withdraws the result to a crypto address or a bank account, tracked with WITHDRAW_STATUS_UPDATE.
  5. You reconcile with the user balance and the activity ledger.

The examples use a Brazilian user trading USDT against BRL. The flow is the same in every country; only the fiat currency, the onboarding data and the fiat rail change.

Before you start

  • Configure the webhooks this flow uses with PATCH /crypto/v2/company. Events without their own URL go to generalWebhook. See Webhooks for signature verification and retries.
{
  "notificationInfo": {
    "type": "WEBHOOK",
    "secret": "your-webhook-secret",
    "generalWebhook": "https://your-domain.com/webhooks/manteca",
    "webhooks": {
      "DEPOSIT_DETECTED": "https://your-domain.com/webhooks/deposits",
      "ORDER_STATUS_UPDATE": "https://your-domain.com/webhooks/orders",
      "WITHDRAW_STATUS_UPDATE": "https://your-domain.com/webhooks/withdraws"
    }
  }
}

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

1

Onboard the user

Create the user with their identity data. Send as much data as you have: the more complete the request, the more likely the user is approved automatically.

Request POST /crypto/v2/onboarding-actions/initial

{
  "externalId": "user-bra-001",
  "email": "[email protected]",
  "legalId": "12345678909",
  "exchange": "BRAZIL"
}

Response (trimmed)

{
  "user": {
    "id": "694765f1ff5ffe8047bb0361",
    "numberId": "100037056",
    "externalId": "user-bra-001",
    "exchange": "BRAZIL",
    "status": "ONBOARDING"
  }
}

In Brazil most personal data is filled in from the CPF. Check what is still missing with GET /crypto/v2/stats/onboarding/missing-personal-data/USERID, complete it, and upload the identity documents if they are required. USER_ONBOARDING_UPDATE reports each task, and the user can operate once their status is ACTIVE. Each country needs different data: see Create user and Country requirements.

Any of the user's id, numberId or externalId works as userAnyId in the next steps.

2

Receive a deposit

Give the user the address or account to fund from. Pass userAnyId so the deposit is credited to that user. Supported countries, fiat rails and crypto networks: see Coverage.

Request GET /crypto/v2/info/deposit-info/{coin} with coin=USDT and ?userAnyId=100037056

Response (trimmed): one entry per network.

{
  "ETHEREUM": {
    "address": "0x7921319332714EBea5c1219439c34309e600DF54",
    "network": "ETHEREUM"
  },
  "POLYGON": {
    "address": "0x7921319332714EBea5c1219439c34309e600DF54",
    "network": "POLYGON"
  }
}

The user must send the asset on one of the listed networks. Crypto deposits are credited after the required block confirmations.

DEPOSIT_DETECTED is sent once per deposit, when it is already credited to the user's balance:

{
  "event": "DEPOSIT_DETECTED",
  "data": {
    "id": "64c3d4e5f6a7b8c9d0e1f2a3",
    "numberId": "5507",
    "userNumberId": "100037056",
    "userExternalId": "user-bra-001",
    "asset": "USDT",
    "amount": "100.000000",
    "network": "POLYGON",
    "networkId": "0x53f25b8bb53153e29539c8660670a72f1d869b457fb4f49ca313edafacd88a24"
  }
}
3

Get a price

Read the indicative price for the pair to show it to the user. It is not guaranteed until you lock it. buy is what the user pays per unit of the asset, sell is what they receive.

Request GET /crypto/v2/prices/direct/{ticker} with ticker=USDT_BRL. Add ?userAnyId= to get effectivePrice with the fees that apply to that user. Any pair you operate works the same way (for example USDT_ARS or USDT_MXN); list them all with GET /crypto/v2/prices/direct.

Response (trimmed)

{
  "ticker": "USDT_BRL",
  "buy": "5.4210",
  "sell": "5.3980",
  "timestamp": "2026-07-02T15:30:00.000-03:00",
  "effectivePrice": {
    "buy": "5.4752",
    "sell": "5.3440"
  }
}
4

Lock the price

Lock the rate for one user, pair and side. The lock is short-lived (about 20 seconds by default): create the order before expireAt.

Request POST /crypto/v2/price-locks

{
  "userAnyId": "100037056",
  "side": "BUY",
  "asset": "USDT",
  "against": "BRL"
}

Response (trimmed)

{
  "code": "71c1a89a-7190-4287-82f6-79f0d4e17c0f",
  "side": "BUY",
  "asset": "USDT",
  "against": "BRL",
  "price": "5.4210",
  "expireAt": "2026-07-02T15:30:20.000-03:00"
}
5

Create the order

Send the lock code as priceCode, with exactly one of assetAmount (units of the asset) or againstAmount (units of the fiat). Set externalId to your own reference so a retry cannot create a second order.

If your company pre-funds its balance, what the user's balance does not cover is taken from the company balance (disallowDebt: false, the default). If the user must pay with their own funds, send disallowDebt: true: the order is then rejected with 400 NO_FUNDS when the user's balance is not enough. See Funding your account.

Request POST /crypto/v2/orders

{
  "externalId": "order-0001",
  "userAnyId": "100037056",
  "side": "BUY",
  "asset": "USDT",
  "against": "BRL",
  "againstAmount": "500.00",
  "priceCode": "71c1a89a-7190-4287-82f6-79f0d4e17c0f",
  "disallowDebt": true
}

Response (trimmed)

{
  "id": "64f1f0a5b6c7d8e9f0012345",
  "numberId": "15342",
  "externalId": "order-0001",
  "status": "COMPLETED",
  "side": "BUY",
  "asset": "USDT",
  "against": "BRL",
  "assetAmount": "91.32041340",
  "price": "5.4210",
  "effectivePrice": "5.4752",
  "finalClaimInfo": { "asset": "BRL", "total": "500.00" },
  "finalCreditInfo": { "asset": "USDT", "total": "91.32041340" }
}

The order executes during the request: a successful response is already COMPLETED, the BRL has been debited and the USDT credited. ORDER_STATUS_UPDATE is sent with the same order. finalClaimInfo is what left the balance and finalCreditInfo is what entered it, both with their fee breakdown. To sell, repeat steps 4 and 5 with side: "SELL".

6

Withdraw

Send the funds out of the user's balance. destination is an object with the address and, for crypto, the network.

Request POST /crypto/v2/withdraws

{
  "externalId": "withdraw-0001",
  "userAnyId": "100037056",
  "asset": "USDT",
  "amount": "90.00",
  "destination": {
    "address": "0x4cD0820ca71Bda1A6cEfe1A6D5a2F6E50D4370f2",
    "network": "POLYGON"
  }
}

Response (trimmed)

{
  "id": "695c7c9263f8f5a0fb931f00",
  "numberId": "100022740",
  "externalId": "withdraw-0001",
  "status": "PENDING",
  "asset": "USDT",
  "amount": "90.00",
  "destination": "0x4cD0820ca71Bda1A6cEfe1A6D5a2F6E50D4370f2",
  "network": "POLYGON"
}

The withdraw starts PENDING. Crypto withdraws can only fail if the destination address is deemed risky; fiat withdraws can also fail on the banking side.

7

Track the operation

Handle WITHDRAW_STATUS_UPDATE until the withdraw reaches a final status:

{
  "event": "WITHDRAW_STATUS_UPDATE",
  "data": {
    "id": "695c7c9263f8f5a0fb931f00",
    "numberId": "100022740",
    "externalId": "withdraw-0001",
    "status": "EXECUTED",
    "statusMessage": null,
    "asset": "USDT",
    "amount": "90.00",
    "network": "POLYGON",
    "networkId": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
  }
}
OperationStatusWhat to do
OrderCOMPLETEDShow the result. This is the normal response to a successful order.
OrderCANCELLEDOnly if the order is reverted later; the claimed funds are returned to the balance.
WithdrawPENDINGWait.
WithdrawEXECUTEDFunds sent. networkId is the on-chain hash (crypto) or the banking reference (fiat).
WithdrawCANCELLEDNot sent. statusMessage gives the reason. A fiat withdraw can move from EXECUTED to CANCELLED if the receiving bank returns it.

Deduplicate webhooks by id and status: the same event can arrive more than once.

To reconcile, read the balance per accounting group with GET /crypto/v2/user-balances/USERANYID and the movements with GET /crypto/v2/stats/user-activities (?userAnyId=&from=&to=):

{
  "data": [
    { "date": "2026-07-02T15:30:00.000-03:00", "type": "DEBIT", "activityType": "ORDER", "asset": "BRL", "amount": "500.00" },
    { "date": "2026-07-02T15:30:00.000-03:00", "type": "CREDIT", "activityType": "ORDER", "asset": "USDT", "amount": "91.32041340" }
  ]
}

For the detailed debit and credit log, with the balance left after each entry and your reference, use GET /crypto/v2/stats/balance-activities (?userAnyId=&from=&to=):

{
  "data": [
    {
      "type": "DEBIT",
      "asset": "BRL",
      "amount": "500.00",
      "reason": "ORDER_CREATION",
      "remainingBalance": "500.00",
      "externalReferenceId": "order-0001",
      "creationTime": "2026-07-02T15:30:00.000-03:00"
    }
  ]
}

Test in sandbox

Simulate a fiat deposit to a user's static deposit address with POST /crypto/v2/sandbox-actions/create-deposit. It returns 204 No Content, and the deposit follows the normal flow, including DEPOSIT_DETECTED.

{
  "legalEntity": "CRYPTO_BRL",
  "asset": "BRL",
  "userAnyId": "100037056",
  "amount": "1000.00"
}

Errors

Handle errors by internalStatus, not by HTTP status.

Full lists: Errors and controls.

Go deeper


Did this page help you?