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 userAnyId in 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_UPDATE for each ramp and DEPOSIT_DETECTED for each deposit, or poll GET /crypto/v2/synthetics/{syntheticAnyId}.

How it works

  1. You register the user and wait until they are ACTIVE.
  2. Optionally, you give the user a permanent deposit address of their own.
  3. The user transfers fiat from an account in their own name. Manteca credits it to the user's balance and sends DEPOSIT_DETECTED.
  4. You create a ramp-on or ramp-off synthetic: one call, and Manteca executes the order and the withdraw.
  5. SYNTHETIC_STATUS_UPDATE reports each status change until COMPLETED or CANCELLED.

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)

OptionHow 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

ModelWhat to sendBehavior
Pre-funded companydisallowDebt: 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-fundeddisallowDebt: trueOnly 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.

1

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.

  • externalId is optional but recommended, and cannot be purely numeric (400 BAD_EXTERNAL_ID).
  • legalIdNationality (the country that issued legalId) and legalIdType are optional. Send legalIdNationality when it differs from exchange: foreign legal IDs are accepted.
  • personalData.address.street is required for the personal data task to complete: without it, the task stays PENDING.

Then complete the tasks marked required: true:

What changes by country:

  • legalId is the CUIT or CUIL. Most identity data (birth date, sex, occupation) is filled in from official records.
  • Send personalData.address and phoneNumber: they are not filled in automatically.
  • Upload the front and back of the ID.

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 statusMeaning
ONBOARDINGOne or more required tasks are still pending.
ACTIVEEvery required task is COMPLETED. The user can operate.
INACTIVEBlocked, 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_VALIDATION and SECURITY_VALIDATION run automatically. If the screening flags the user, POLITICAL_CONSTRAINTS_VALIDATION still completes, and PEP_DOCUMENTATION_VALIDATION or FEP_DOCUMENTATION_VALIDATION flips to required: true with status: "PENDING" (a user can be flagged as both). Upload the user's signed sworn statement with POST /crypto/v2/onboarding-actions/upload-pep-documentation or POST /crypto/v2/onboarding-actions/upload-fep-documentation: same two steps as the ID images (userAnyId and fileName, then PUT within 90 seconds). Compliance reviews it manually.
  • Rejections. Any task, including the automatic ones, can end FAILED with a rejectionReason in 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 with define-personal-data (calling initial again returns 409), PEP or FEP documentation with its upload endpoint, liveness with a new link. The task goes back to IN_PROGRESS and a new USER_ONBOARDING_UPDATE reports the result. The API sets no retry limit.
  • Compliance block. If SECURITY_VALIDATION fails, the user becomes INACTIVE, 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.
2

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.

Per-user deposit addresses exist only in these four countries. Every country with ramp-on, and its deposit rail: Coverage.

3

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: call GET /crypto/v2/info/deposit-info/{coin} with the crypto asset and the userAnyId query 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.

4

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.

5

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.

Every country with ramp-off, its network and execution time: Coverage. All fields per country: Before the payment. Bank codes: Supported banks.

6

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"
  }
}
StatusMeaningWhat to do
STARTINGBeing set upWait.
ACTIVEWaiting for the deposit, or running a stageWait.
WAITINGBetween stages, for example while a refund runsWait.
PAUSEDHeld by Manteca while WAITINGWait.
COMPLETEDFunds delivered to the destinationFinal. Mark the operation done.
CANCELLEDTerminated. The failed stage carries the reason in errorsFinal. 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 is CANCELLED with the error in the ORDER stage. 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 WITHDRAW stage errors carries the reason, a REFUND and an ORDER_REVERSAL stage follow, and the synthetic ends CANCELLED. The user gets back the asset they started with, at the original amounts.
  • Deposit not received within 30 minutes (only without skipDeposit): CANCELLED with no errors. 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


Did this page help you?