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
ACTIVEbefore trading. To trade on your company's own account, send theuserAnyIdof 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_UPDATEandWITHDRAW_STATUS_UPDATEwebhooks, or pollGET /crypto/v2/orders/{orderAnyId}andGET /crypto/v2/withdraws/{withdrawAnyId}.
How it works
- Onboard the user and wait until they are
ACTIVE. - The user deposits crypto or fiat.
DEPOSIT_DETECTEDarrives once the funds are in their balance. - You read the price, lock it, and create the order with the lock
code. The order comes backCOMPLETED. - The user withdraws the result to a crypto address or a bank account, tracked with
WITHDRAW_STATUS_UPDATE. - 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 togeneralWebhook. 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).
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.
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.
Fiat deposits go to your company deposit account, returned by the same deposit-info call with a fiat coin (for example ARS returns a BANK_TRANSFER entry).
Optionally, give each user their own deposit address with POST /crypto/v2/user-actions/assign-deposit-address. It is named in Argentina and Brazil (a PIX key in Brazil) and individualized in Colombia and Mexico. The user must be ACTIVE.
{
"userAnyId": "100037056",
"asset": "BRL",
"externalId": "user-dep-brl-001"
}In Argentina and Brazil, a transfer from an account that is not in the user's name is returned automatically, and no webhook is sent for it.
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"
}
}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"
}
}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"
}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".
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"
}
}{
"externalId": "withdraw-0002",
"userAnyId": "100037056",
"asset": "BRL",
"amount": "500.00",
"destination": {
"address": "[email protected]",
"network": "PIX"
}
}Other countries use their own rails and destination formats (bank account, alias, account type): see Coverage for the rail per country and Deposits and withdrawals. When the account belongs to someone other than the user, add recipient: see Third party transfers.
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.
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"
}
}| Operation | Status | What to do |
|---|---|---|
| Order | COMPLETED | Show the result. This is the normal response to a successful order. |
| Order | CANCELLED | Only if the order is reverted later; the claimed funds are returned to the balance. |
| Withdraw | PENDING | Wait. |
| Withdraw | EXECUTED | Funds sent. networkId is the on-chain hash (crypto) or the banking reference (fiat). |
| Withdraw | CANCELLED | Not 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
- Pricing and orders: fees, minimum order size, price lock TTLs.
- Deposits and withdrawals: static and dynamic deposits, destination formats.
- Execution tracking: webhook catalog and reconciliation endpoints.
- Coverage: fiat rails, crypto networks and assets per country.
- Country requirements: onboarding data per country.
Updated 27 days ago