Deposits and Withdrawals
Deposits and withdrawals are the core movement primitives in Crypto as a Service. Use deposits to receive and fund balances. Use withdrawals to settle toward external destinations under configured compliance and coverage constraints.
Crypto funds declarations
The following fields are optional in the API schema. When operating with legal entity CRYPTO_BRL, a declaration is required for each applicable reportable crypto transfer. Company withdrawals from CREDIT or PROFIT are excluded from ACAM212 and do not require declarations, including under CRYPTO_BRL; this exemption also applies to their retry and manual confirmation. Fiat-only deposits and withdrawals do not require one. Declarations describe a single transfer, not a permanent classification of an address.
| Field | Type | Where to send it |
|---|---|---|
originDeclaration | object, optional | On synthetic creation for the incoming crypto leg: ramp-off (including partial ramp-off), crypto-funded QR/bill payments, and charges receiving crypto. Required for applicable CRYPTO_BRL crypto funding, including when company debt skips the deposit stage. |
destination.declaration | object, optional | Inside the destination object for withdrawals, ramp-on, and charge settlement to crypto. Required for crypto withdrawals under CRYPTO_BRL. |
destinationDeclaration | object, optional | On endpoints with a legacy string address, such as POST /crypto/v2/accounting/withdraws. Company CREDIT/PROFIT withdrawals do not require it, even when group is CRYPTO_BRL. Do not use this top-level field for POST /crypto/v2/withdraws; use destination.declaration. |
The company CREDIT/PROFIT exemption does not remove the declaration requirement for customer liquidations: the per-customer fake crypto withdrawals created by a liquidation are reportable and still require the destination declaration. The eventual company settlement withdrawal is not reported again.
All three use the same declaration object. If you provide it, ownerCategory and type must be present, along with the fields required by the selected type:
| Field | Type / accepted values | When to include it |
|---|---|---|
ownerCategory | VASP, NON_VASP | Every supplied declaration. Whether the wallet is associated with a virtual asset service provider, not whether the user owns it. |
type | INTERNATIONAL, PAYMENT_INSTRUMENT, SELF_CUSTODY, DOMESTIC_VASP | Every supplied declaration. |
foreignParty.name | string, up to 100 characters | Required for INTERNATIONAL and PAYMENT_INSTRUMENT: the actual foreign payer (incoming funds) or receiver (outgoing funds). |
foreignParty.country | Country enum name, e.g. ARGENTINA or UNITED_STATES | Required with foreignParty.name. Use a country name enum, not an ISO code; BRAZIL is not allowed. |
purpose | Descriptive purpose enum, e.g. VIRTUAL_ASSETS | Required for INTERNATIONAL only. The full accepted enum is in the endpoint's FundsDeclaration schema. Send the name, not a numeric regulatory code. |
relationship | SAME_ECONOMIC_GROUP, OTHER | Required for INTERNATIONAL only. |
holder.personType | REAL (individual), LEGAL (legal entity) | Required for SELF_CUSTODY only. |
holder.isNational | boolean | Required for SELF_CUSTODY only. true for a Brazilian holder; false for a foreign holder (reported as Estrangeira). |
holder.legalId | string | Required for SELF_CUSTODY only. For a Brazilian holder, a valid CPF (REAL, 11 digits) or CNPJ (LEGAL, 14 digits); otherwise a foreign document identifier of up to 25 characters. Never a blockchain address. |
SELF_CUSTODY requires ownerCategory: "NON_VASP". DOMESTIC_VASP requires ownerCategory: "VASP" and no other declaration fields. Omit foreignParty, purpose, relationship, and holder when they do not apply to the chosen type; contradictory fields are rejected.
Example withdrawal to a domestic VASP (declare the actual destination's classification):
{
"userAnyId": "10001",
"legalEntity": "CRYPTO_BRL",
"asset": "USDT",
"amount": "100.00",
"destination": {
"address": "0x4cD0820ca71Bda1A6cEfe1A6D5a2F6E50D4370f2",
"network": "ETHEREUM",
"declaration": {
"ownerCategory": "VASP",
"type": "DOMESTIC_VASP"
}
}
}Example incoming international declaration, attached to the synthetic request:
{
"originDeclaration": {
"ownerCategory": "VASP",
"type": "INTERNATIONAL",
"foreignParty": {
"name": "Example Trading SA",
"country": "ARGENTINA"
},
"purpose": "VIRTUAL_ASSETS",
"relationship": "OTHER"
}
}When available, deposit responses carry originDeclaration and withdrawal responses carry destinationDeclaration (their destination remains a string). Synthetic deposit/order stages carry originDeclaration, and withdrawal stages carry destination.declaration. These response fields are optional, including for historical records. The corresponding declaration may also appear on crypto deposit instructions in details.depositAddresses.
Deposits
Static vs dynamic deposit addresses
| Type | How it works | When to use |
|---|---|---|
| Static | A fixed address assigned to the user for a given asset/network | Long-lived integrations; user always sends to the same address |
| Dynamic | A one-time deposit request created per transaction | When you need to track individual deposits precisely |
Retrieve static deposit instructions with GET /crypto/v2/info/deposit-info/{coin}.
Create a dynamic deposit request with POST /crypto/v2/deposit-actions/deposit-request.
Test a fiat deposit in sandbox
Use POST /crypto/v2/sandbox-actions/create-deposit to simulate a fiat deposit to a user's static deposit address. Provide the public legalEntity, fiat asset, user identifier, and amount. The action returns 204 No Content and the deposit continues through the normal deposit lifecycle.
The optional sender identifies the simulated originator. If it is omitted, the user's person data is used.
curl -X POST https://sandbox.manteca.dev/crypto/v2/sandbox-actions/create-deposit \
-H "md-api-key: $MD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"legalEntity": "CRYPTO_ARG",
"asset": "ARS",
"userAnyId": "100036128",
"amount": "150.00"
}'This action is for fiat assets with static deposit addresses. Dynamic addresses belong to deposit-request flows and are not eligible for this action.
Deposit detection flow
- User sends funds to the deposit address (static or dynamic).
- Manteca detects the deposit and, for crypto, waits for the required block confirmations.
- The deposit is credited to the user's balance and Manteca emits
DEPOSIT_DETECTED.
Withdrawals
Create a withdrawal with POST /crypto/v2/withdraws. Withdrawals move through PENDING to EXECUTED or CANCELLED. For the complete status reference and state transitions, see Operation Lifecycle Statuses. Fiat withdrawals may fail for various reasons, including banking network issues, invalid destinations, etc. Crypto withdrawals can only fail if the destination address is deemed risky.
Withdraw request-time error codes
internalStatus | HTTP | Description |
|---|---|---|
NO_FUNDS | 400 | User has insufficient balance |
INVALID_ADDRESS | 400 | Withdraw address is malformed or invalid |
INVALID_DESTINATION | 400 | Destination is invalid for the selected rail |
RISKY_WITHDRAW_ADDRESS | 403 | Address flagged by compliance screening; do not retry |
USER_NF | 404 | User not found |
WITHDRAW_EXISTS | 409 | A withdraw with this externalId already exists |
OPERATION_BLOCKED | 409 | Withdrawals are blocked by policy or limits |
Webhooks
Subscribe to WITHDRAW_STATUS_UPDATE to track withdraw lifecycle without polling.
{
"event": "WITHDRAW_STATUS_UPDATE",
"data": {
"id": "65d4e5f6a7b8c9d0e1f2a3b4",
"numberId": "77001",
"externalId": "my-withdraw-001",
"network": "BANK_TRANSFER",
"networkId": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"userId": "64a1b2c3d4e5f6a7b8c9d0e2",
"userNumberId": "12345",
"userExternalId": "ext-001",
"userLegalId": "20345678901",
"sender": {
"name": "Juan Pérez",
"legalId": "20345678901"
},
"destination": "0000123456789012345678",
"status": "EXECUTED",
"statusMessage": "",
"asset": "ARS",
"amount": "15000.00",
"filledAmount": "15000.00",
"sessionId": "session-abc-123",
"creationTime": "2026-02-21T15:25:30.000Z"
}
}See Webhooks for delivery configuration and signature verification.
Endpoint references
| Action | Endpoint |
|---|---|
| Get deposit instructions | GET /crypto/v2/info/deposit-info/{coin} |
| Create dynamic deposit request | POST /crypto/v2/deposit-actions/deposit-request |
| Create sandbox fiat deposit | POST /crypto/v2/sandbox-actions/create-deposit |
| Get deposits | GET /crypto/v2/deposits |
| Get deposit by ID | GET /crypto/v2/deposits/{depositAnyId} |
| Create withdraw | POST /crypto/v2/withdraws |
| Get withdrawals | GET /crypto/v2/withdraws |
| Get withdraw by ID | GET /crypto/v2/withdraws/{withdrawAnyId} |
For third-party payout rules and recipient data, see Third party transfers.
Updated 19 days ago