Integrate ramps
Your users deposit fiat and receive crypto in a wallet (ramp-on), or sell crypto and receive fiat in their own bank account (ramp-off). Each ramp is one API call (a synthetic) that Manteca runs end to end.
At a glance
- Users: each end user is onboarded in Manteca once (End-user model) and referenced as
userAnyIdin every operation. - Funds: the user funds their own balance from an account in their name, or your company covers the operation from its pre-funded balance. See Choose how ramps are funded.
- Tracking:
SYNTHETIC_STATUS_UPDATEfor each ramp andDEPOSIT_DETECTEDfor each deposit, or pollGET /crypto/v2/synthetics/{syntheticAnyId}.
How it works
- You register the user and wait until they are
ACTIVE. - Optionally, you give the user a permanent deposit address of their own.
- The user transfers fiat from an account in their own name. Manteca credits it to the user's balance and sends
DEPOSIT_DETECTED. - You create a ramp-on or ramp-off synthetic: one call, and Manteca executes the order and the withdraw.
SYNTHETIC_STATUS_UPDATEreports each status change untilCOMPLETEDorCANCELLED.
Before you start
- Configure the webhooks this flow uses with
PATCH /crypto/v2/company. Include any URLs you already have configured, so they are kept.
{
"notificationInfo": {
"type": "WEBHOOK",
"secret": "your-webhook-secret",
"webhooks": {
"USER_ONBOARDING_UPDATE": "https://your-domain.com/webhooks/onboarding",
"USER_CRIPTO_STATUS_UPDATE": "https://your-domain.com/webhooks/user-status",
"DEPOSIT_DETECTED": "https://your-domain.com/webhooks/deposits",
"SYNTHETIC_STATUS_UPDATE": "https://your-domain.com/webhooks/synthetics",
"COMPLIANCE_NOTICE": "https://your-domain.com/webhooks/compliance"
}
}
}Every webhook is a POST with the body { "event": "...", "data": { ... } }. Your listener must verify the md-webhook-signature header (hex HMAC SHA-256 of the JSON body serialized with its keys sorted alphabetically, keyed with your secret), answer 2xx within 10 seconds and handle duplicate deliveries. See Webhooks.
Webhooks are sent from four fixed IP addresses: allowlist all of them (see Webhooks).
Choose how ramps are funded
Two independent choices. Make them once for your integration.
Where the user deposits fiat (ramp-on)
| Option | How it works |
|---|---|
| Company deposit account (default) | All your users transfer to your company's deposit account for the country. Manteca matches each transfer to the user by the sender's legal ID. Nothing to create per user. |
| Per-user deposit address (optional) | Each user gets a permanent account of their own (step 2). Every transfer to it is credited to that user. Availability by country is in Coverage. |
Who pays for the operation
| Model | What to send | Behavior |
|---|---|---|
| Pre-funded company | disallowDebt: false (default) | What the user's balance does not cover is taken from your company balance in that accounting group, and the deposit stage can be skipped. Fund it with USDT or USDC first: see Funding your account. |
| User-funded | disallowDebt: true | Only the user's balance is used. Add skipDeposit: true when the user already holds the balance: the synthetic has no deposit stage and the balance is checked at creation (400 NO_FUNDS if it does not cover the amount). Without skipDeposit, the synthetic waits for the user's deposit. |
The examples below use the user-funded model with skipDeposit: true: the user deposits first, then you convert the credited balance.
CRYPTO_BRL crypto declarations: originDeclaration (ramp-off, including partial ramp-off) and destination.declaration (ramp-on crypto withdrawal) are optional schema fields, but required for the applicable crypto leg under this legal entity. Company-funded crypto operations still need the origin declaration when debt skips the deposit stage. Fiat legs do not require one. See Funds declarations for the object fields and examples.
Register the user
POST /crypto/v2/onboarding-actions/initial creates the user. Store the returned user.numberId: you use it to query limits.
Request (Argentina)
{
"externalId": "user-001",
"email": "[email protected]",
"legalId": "20300000009",
"exchange": "ARGENTINA",
"type": "INDIVIDUAL",
"personalData": {
"name": "JOHN",
"surname": "DOE",
"phoneNumber": "1100000000",
"address": {
"street": "CALLE FALSA",
"numeration": "123",
"postalCode": "1000",
"locality": "CIUDAD EJEMPLO",
"province": "BUENOS AIRES",
"floor": "",
"apartment": ""
}
}
}The response returns the user with status: "ONBOARDING" and an onboarding object: one entry per task, each with required and status.
externalIdis optional but recommended, and cannot be purely numeric (400 BAD_EXTERNAL_ID).legalIdNationality(the country that issuedlegalId) andlegalIdTypeare optional. SendlegalIdNationalitywhen it differs fromexchange: foreign legal IDs are accepted.personalData.address.streetis required for the personal data task to complete: without it, the task staysPENDING.
Then complete the tasks marked required: true:
- ID images: call
POST /crypto/v2/onboarding-actions/upload-identity-imagewithuserAnyId,side(FRONTorBACK) andfileName. It returns a signedurl:PUTthe raw file to it within 90 seconds, with aContent-Typethat matches the file and without themd-api-keyheader. Repeat for the other side. - Missing personal data:
GET /crypto/v2/stats/onboarding/missing-personal-data/USERANYIDreturnsmissingData, the list of fields still missing (an empty list means nothing is missing). Send them withPOST /crypto/v2/onboarding-actions/define-personal-data, samepersonalDatashape, which returns204and is rejected with409once the user isACTIVE.
What changes by country:
legalIdis the CUIT or CUIL. Most identity data (birth date, sex, occupation) is filled in from official records.- Send
personalData.addressandphoneNumber: they are not filled in automatically. - Upload the front and back of the ID.
legalIdis the CPF. Identity data is filled in from official records; check missing personal data and send the address if it is reported.- Upload the front and back of the ID.
- A per-user deposit address (PIX key) also needs a liveness check: once
IDENTITY_VALIDATIONandBASIC_PERSONAL_DATA_DEFINITION_VAareCOMPLETED, callPOST /crypto/v2/onboarding-actions/perform-external-livenesswithuserAnyIdand hand the returned single-useurlto the user. It drives theEXTERNAL_LIVENESS_VALIDATIONtask. The user becomesACTIVEwithout it. BASIC_PERSONAL_DATA_DEFINITION_VAneeds the full address:street,numeration,postalCode,localityandprovince. Before both tasks areCOMPLETEDthe call returns409 USER_STATUS. If you get409 LIVENESS_URL_NOT_READY, retry after a few seconds.- The user opens the link in a browser or in-app webview and completes the capture on their device. Nothing is sent back from your side. If the user abandons it or the task ends
FAILED, call the endpoint again for a new link.
legalIdis the NUIP (10 digits), CC (6 to 10 digits) or PPT (6 to 15 letters and digits). SendlegalIdTypeso the ID is validated against the right format.- Nothing is filled in automatically: send the full
personalData(name, surname, sex, birth date, phone, nationality, marital status, address). - Upload ID images only when
IDENTITY_VALIDATIONshowsrequired: true(for example, when compliance or limit controls request it).
legalIdis the CURP (18 characters, validated with its check digit) or RFC. Nothing is filled in automatically: send the fullpersonalData, including the address.- Upload ID images only when
IDENTITY_VALIDATIONshowsrequired: true(for example, when compliance or limit controls request it).
legalIdis the RUT with its check digit, with or without dots and dash.- Required
personalData:name,surname,sex,birthDate,work,phoneNumber,nationality,maritalStatus,address.street, and theisPep,isFepandisFactadeclarations. The user does not becomeACTIVEuntil all of them are present: check missing personal data and complete it withdefine-personal-data. - Uploading the front and back of the ID right after registration is recommended. It is not needed to reach
ACTIVE, but a user without validated ID images can later be asked for them (409 USER_NEEDS_EXTRA_DOC).
Field rules for each country are in Country requirements.
Wait for ACTIVE. Tasks are validated asynchronously. USER_ONBOARDING_UPDATE fires when tasks change (data.user is the full user, data.updatedTasks lists which tasks changed), and USER_CRIPTO_STATUS_UPDATE fires when the user's status changes. Without webhooks, poll GET /crypto/v2/users/USERANYID, which returns the same status and onboarding object.
User status | Meaning |
|---|---|
ONBOARDING | One or more required tasks are still pending. |
ACTIVE | Every required task is COMPLETED. The user can operate. |
INACTIVE | Blocked, for example by a compliance block. The user cannot operate: contact support. |
Each task moves through PENDING, IN_PROGRESS (submitted, being validated), then COMPLETED or FAILED. EXPIRED means a completed task needs renewal (for example, an expired ID): resubmit it the same way.
- PEP or FEP hit.
POLITICAL_CONSTRAINTS_VALIDATIONandSECURITY_VALIDATIONrun automatically. If the screening flags the user,POLITICAL_CONSTRAINTS_VALIDATIONstill completes, andPEP_DOCUMENTATION_VALIDATIONorFEP_DOCUMENTATION_VALIDATIONflips torequired: truewithstatus: "PENDING"(a user can be flagged as both). Upload the user's signed sworn statement withPOST /crypto/v2/onboarding-actions/upload-pep-documentationorPOST /crypto/v2/onboarding-actions/upload-fep-documentation: same two steps as the ID images (userAnyIdandfileName, thenPUTwithin 90 seconds). Compliance reviews it manually. - Rejections. Any task, including the automatic ones, can end
FAILEDwith arejectionReasonin the form"<index>. <description>". The index is stable: use it to map your own messages. The description is Spanish text, and manually reviewed documents may carry free text without an index. - Resubmitting. Call the same action again with corrected data or files: ID images with
upload-identity-image, personal data withdefine-personal-data(callinginitialagain returns409), PEP or FEP documentation with its upload endpoint, liveness with a new link. The task goes back toIN_PROGRESSand a newUSER_ONBOARDING_UPDATEreports the result. The API sets no retry limit. - Compliance block. If
SECURITY_VALIDATIONfails, the user becomesINACTIVE, no reason is exposed and there is no resubmission through the API: contact support with the user's ID. Also contact support if a document keeps failing with correct documentation.
Assign a per-user deposit address (optional)
Skip this step if your users deposit to your company deposit account. Otherwise call POST /crypto/v2/user-actions/assign-deposit-address once per user, after the user is ACTIVE (before that it returns 409 USER_STATUS). The feature must be enabled for your company for the user's country; otherwise the call returns 403. externalId is your own optional identifier for the account.
Request (Mexico)
{
"userAnyId": "100109774",
"asset": "MXN",
"externalId": "user-001-mxn"
}Response
{
"id": "64b2c3d4e5f6a7b8c9d0e1f5",
"address": "012180001234567899",
"status": "ACTIVE",
"bank": "BANK_TRANSFER",
"currency": "MXN",
"externalId": "user-001-mxn"
}Share address with the user (and alias when present; it can be empty). The account is permanent: store it and reuse it for every deposit. If the response has status: "PENDING" and no address, the account is still being issued: read it later from banking.addresses in GET /crypto/v2/users/USERANYID (entry with type: "DEPOSIT" and the asset in acceptedAssets). Do not call the endpoint again: it returns 409 BANK_ACCOUNT_EXISTS.
asset: "ARS". A CVU issued in the user's name, with an alias when available.
asset: "BRL". A PIX key issued in the user's name. It is issued once the liveness check from step 1 is COMPLETED.
asset: "COP". An individualized Bre-B key: assigned only to that user, not held in their name.
asset: "MXN". An individualized CLABE (18 digits): assigned only to that user, not held in their name.
Not available. Users transfer to your company deposit account and are matched by RUT.
Per-user deposit addresses exist only in these four countries. Every country with ramp-on, and its deposit rail: Coverage.
The user funds their balance
The user transfers fiat from an account in their own name to their deposit address or to your company deposit account. No API call is needed to receive it.
- To find your company deposit account for a currency, call
GET /crypto/v2/info/deposit-info/{coin}. - On the company account, a transfer from a legal ID that is not one of your users is not credited and no webhook is sent.
- On a per-user address in Argentina and Brazil, a transfer from an account held by someone else is returned to the sender automatically, with no webhook.
- If a deposit from the user's own account is not credited, contact support with the transfer details.
- For a ramp-off, the user can send crypto to their own deposit addresses, assigned once they are
ACTIVE: callGET /crypto/v2/info/deposit-info/{coin}with the crypto asset and theuserAnyIdquery parameter to get the address for each network.
When the deposit is credited, DEPOSIT_DETECTED arrives once, whichever account it was sent to. The funds are already in the user's balance. networkId is the bank transfer reference for fiat, or the transaction hash for crypto.
{
"event": "DEPOSIT_DETECTED",
"data": {
"id": "68ab90c1e4b0f2a41d3c7712",
"numberId": "100123",
"userNumberId": "100109774",
"userExternalId": "user-001",
"asset": "ARS",
"amount": "131500.00",
"network": "BANK_TRANSFER",
"networkId": "3f6b2c1e-8a4d-4b7e-9c2a-1d5e7f9a0b3c",
"legalEntity": "CRYPTO_ARG",
"creationTime": "2026-07-28T17:20:26.764-03:00"
}
}Before creating the ramp, check that the signature is valid, data.asset is the expected currency and the deposit belongs to the expected user (data.userExternalId or data.userNumberId). Store data.id, data.networkId and data.amount, ignore ids you already processed, and answer 2xx before continuing asynchronously. To reconcile, use GET /crypto/v2/deposits (filter by userAnyId, asset, status and dates), GET /crypto/v2/deposits/{depositAnyId} and GET /crypto/v2/user-balances/USERANYID.
Create a ramp-on (fiat to crypto)
POST /crypto/v2/synthetics/ramp-on debits the fiat, buys the crypto and withdraws it to destination. Send exactly one of againstAmount (fiat to spend) or assetAmount (crypto to receive). externalId must be unique: a repeated one returns 409 SYNTHETIC_EXISTS and creates nothing.
Request
{
"externalId": "ramp-on-001",
"userAnyId": "100109774",
"asset": "USDT",
"against": "ARS",
"againstAmount": "131500.00",
"skipDeposit": true,
"disallowDebt": true,
"destination": {
"address": "0x1234567890abcdef1234567890abcdef12345678",
"network": "POLYGON"
}
}Response 201 (trimmed)
{
"id": "689dfd731927612f42af2101",
"numberId": "2401",
"externalId": "ramp-on-001",
"status": "STARTING",
"type": "RAMP_OPERATION",
"details": {
"price": "1315.00",
"priceExpireAt": "2026-08-13T18:31:00.000Z",
"effectiveWithdrawAmount": "100.00000000"
},
"currentStage": 1,
"stages": {
"1": { "stageType": "ORDER", "side": "BUY", "asset": "USDT", "against": "ARS", "assetAmount": "100.00000000" },
"2": { "stageType": "WITHDRAW", "asset": "USDT", "amount": "100.00000000" }
}
}stages is the plan: stage 1 the ORDER (BUY), stage 2 the WITHDRAW to the destination. sessionId is an optional field for your own traceability. Without a priceCode, a price is locked at creation and returned in details.price (and details.effectivePrice) with details.priceExpireAt. For an indicative quote, call GET /crypto/v2/prices/direct/{ticker} (for example USDT_ARS). To guarantee the price, lock it with POST /crypto/v2/price-locks and send its code as priceCode. The network fee of the crypto withdraw (details.withdrawCostInAsset, and withdrawCostInAgainst in fiat) is deducted from the crypto bought, so details.effectiveWithdrawAmount is what reaches the destination.
If you omit skipDeposit, the synthetic starts with a deposit stage and returns the account to fund in details.depositAddresses. The deposit must arrive within 30 minutes, otherwise the synthetic is CANCELLED.
To select a preconfigured deposit route, add "enforceDepositAddressLabel": "example-label" to the creation body. This also works for ramp-off and both partial-ramp endpoints. The label must match exactly; it filters eligible accounts without changing network selection or the normal deposit-request rules. Deposits must carry the same configured label to satisfy the deposit stage. See Select a deposit account by label for setup, static-address fallback, and matching rules.
Create a ramp-off (crypto to fiat)
POST /crypto/v2/synthetics/ramp-off sells the crypto and pays the fiat out to destination, which must be an account held by the user.
Request
{
"externalId": "ramp-off-001",
"userAnyId": "100109774",
"asset": "USDT",
"against": "ARS",
"assetAmount": "10.00000000",
"skipDeposit": true,
"disallowDebt": true,
"destination": {
"address": "john.doe.alias",
"network": "BANK_TRANSFER"
}
}The response has the same shape as the ramp-on: stage 1 is the ORDER (SELL) and stage 2 the fiat WITHDRAW, and details.effectiveWithdrawAmount is the fiat amount that reaches the account. If the user still has to send the crypto, omit skipDeposit: the synthetic returns crypto deposit addresses in details.depositAddresses and waits up to 30 minutes.
The destination depends on the country:
network: "BANK_TRANSFER", address: CBU, CVU or alias held by the user (same CUIT). BANK_TRANSFER is the only network and is applied if you omit it.
network: "PIX", address: a PIX key that belongs to the user (same CPF). Otherwise the request fails with 400 CUIT_MISMATCH. PIX is the only network and is applied if you omit it.
network is required: BREB with a Bre-B key, phone, email or CC; or BANK_TRANSFER with address (account number), accountType (CHECKING or SAVINGS) and bankCode. The destination must be held by the user.
network: "SPEI" with the user's CLABE (18 digits) in address, plus accountType (CHECKING or SAVINGS) and bankCode. Use an account held in the user's own name.
address (account number, digits only), bankCode and accountType (CHECKING, SAVINGS or VISTA; Cuenta RUT accounts, bank code 317, always use RUT), on an account under the user's RUT. network can be omitted: it is always BANK_TRANSFER. The account number and bank are validated at creation, but the holder is checked by the bank at pay-out time: a pay-out to someone else's account fails after the synthetic started (see Track the operation). Pay-outs run in batches (see Coverage).
Every country with ramp-off, its network and execution time: Coverage. All fields per country: Before the payment. Bank codes: Supported banks.
Track the operation
SYNTHETIC_STATUS_UPDATE fires on every status change, with the full synthetic in data. Correlate by externalId.
In a ramp-off, a fiat payout can be returned by the receiving bank after it was sent, and the amount goes back to the user's balance. To detect it, also subscribe to WITHDRAW_STATUS_UPDATE: the withdraw of a ramp moves from EXECUTED to CANCELLED (see Operation lifecycle statuses).
{
"event": "SYNTHETIC_STATUS_UPDATE",
"data": {
"id": "689dfd731927612f42af2101",
"externalId": "ramp-on-001",
"status": "COMPLETED",
"type": "RAMP_OPERATION",
"currentStage": 2,
"details": {
"price": "1315.00",
"assetAmountOperated": "100.00000000",
"againstAmountOperated": "131500.00"
},
"userNumberId": "100109774",
"updatedAt": "2026-08-13T18:33:19.701-03:00"
}
}| Status | Meaning | What to do |
|---|---|---|
STARTING | Being set up | Wait. |
ACTIVE | Waiting for the deposit, or running a stage | Wait. |
WAITING | Between stages, for example while a refund runs | Wait. |
PAUSED | Held by Manteca while WAITING | Wait. |
COMPLETED | Funds delivered to the destination | Final. Mark the operation done. |
CANCELLED | Terminated. The failed stage carries the reason in errors | Final. Store the reason and check the user's balance before retrying with a new externalId. |
The details fields vary with the stage. A synthetic created with 201 can still end CANCELLED:
- The conversion cannot run (the balance was spent by another operation, or
BLOCKED_UIF): it is retried a few times, then the synthetic isCANCELLEDwith the error in theORDERstage. Nothing was converted and the funds stay in the user's balance. - The pay-out is rejected by the bank (for example, the account is not the user's) or the withdraw cannot be created: the
WITHDRAWstageerrorscarries the reason, aREFUNDand anORDER_REVERSALstage follow, and the synthetic endsCANCELLED. The user gets back the asset they started with, at the original amounts. - Deposit not received within 30 minutes (only without
skipDeposit):CANCELLEDwith noerrors. Funds that arrive later are credited to the user's balance.
Pay-out error codes and how to handle them: Ramps error handling. Full state machine: Operation lifecycle statuses. To reconcile, list operations with GET /crypto/v2/synthetics and read each balance movement with GET /crypto/v2/stats/balance-activities (userAnyId query parameter).
Limits
Each user has an EXCHANGE limit over a monthly and a yearly calendar window (reset on the 1st of each month and on January 1st), applied per person. The amounts depend on the user's profile: query them instead of hardcoding them. The ramp conversion consumes the limit when it executes; a fiat deposit or pay-out alone does not. Query it with GET /crypto/v2/limits/{numberId}. Amounts are strings in the limit's asset: ARS for Argentina, USDT for the other countries. Pass the optional asset query parameter (for example asset=MXN) to convert them.
[
{
"exchangeCountry": "ARG",
"type": "EXCHANGE",
"asset": "ARS",
"monthlyLimit": "25000000",
"availableMonthlyLimit": "24800000",
"yearlyLimit": "35000000",
"availableYearlyLimit": "34500000"
}
]An operation over the limit is rejected with 400 BLOCKED_UIF. Only that operation is refused: the user can keep operating within the limit, and again once the window resets or the limit is raised. Query the limits to see which window was exceeded. The check runs at creation and again at execution, so a synthetic can be created and still end CANCELLED for this reason. COMPLIANCE_NOTICE with CLOSE_TO_OPERATION_LIMIT warns you when 10% or less remains, and OPERATION_LIMIT_UPDATED when the limit changes.
To raise a limit, the user submits proof of funds origin as a FUNDS document: request a signed URL with POST /crypto/v2/documentations/uploadUrl and PUT the file right away. Compliance reviews it manually. See Operational limits and Raise limits.
Test in sandbox
Simulate a fiat deposit to your company deposit account with POST /crypto/v2/sandbox-actions/create-deposit. It returns 204 and the deposit follows the normal lifecycle, including DEPOSIT_DETECTED. Dynamic deposit routes are not supported.
{
"legalEntity": "CRYPTO_ARG",
"asset": "ARS",
"userAnyId": "100109774",
"amount": "131500.00"
}Errors
Every error has the same body: internalStatus (the stable value to code against), message (text that can change) and, on validation failures, errors[] with field details. Full catalog: Ramps error handling. Onboarding rejections: KYC rejection troubleshooting.
Go deeper
- Ramps overview and Coverage
- Onboard a new user and Country requirements
- Operation lifecycle statuses
- Funding your account
Updated 15 days ago