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.

FieldTypeWhere to send it
originDeclarationobject, optionalOn 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.declarationobject, optionalInside the destination object for withdrawals, ramp-on, and charge settlement to crypto. Required for crypto withdrawals under CRYPTO_BRL.
destinationDeclarationobject, optionalOn 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:

FieldType / accepted valuesWhen to include it
ownerCategoryVASP, NON_VASPEvery supplied declaration. Whether the wallet is associated with a virtual asset service provider, not whether the user owns it.
typeINTERNATIONAL, PAYMENT_INSTRUMENT, SELF_CUSTODY, DOMESTIC_VASPEvery supplied declaration.
foreignParty.namestring, up to 100 charactersRequired for INTERNATIONAL and PAYMENT_INSTRUMENT: the actual foreign payer (incoming funds) or receiver (outgoing funds).
foreignParty.countryCountry enum name, e.g. ARGENTINA or UNITED_STATESRequired with foreignParty.name. Use a country name enum, not an ISO code; BRAZIL is not allowed.
purposeDescriptive purpose enum, e.g. VIRTUAL_ASSETSRequired for INTERNATIONAL only. The full accepted enum is in the endpoint's FundsDeclaration schema. Send the name, not a numeric regulatory code.
relationshipSAME_ECONOMIC_GROUP, OTHERRequired for INTERNATIONAL only.
holder.personTypeREAL (individual), LEGAL (legal entity)Required for SELF_CUSTODY only.
holder.isNationalbooleanRequired for SELF_CUSTODY only. true for a Brazilian holder; false for a foreign holder (reported as Estrangeira).
holder.legalIdstringRequired 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

TypeHow it worksWhen to use
StaticA fixed address assigned to the user for a given asset/networkLong-lived integrations; user always sends to the same address
DynamicA one-time deposit request created per transactionWhen 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

  1. User sends funds to the deposit address (static or dynamic).
  2. Manteca detects the deposit and, for crypto, waits for the required block confirmations.
  3. 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

internalStatusHTTPDescription
NO_FUNDS400User has insufficient balance
INVALID_ADDRESS400Withdraw address is malformed or invalid
INVALID_DESTINATION400Destination is invalid for the selected rail
RISKY_WITHDRAW_ADDRESS403Address flagged by compliance screening; do not retry
USER_NF404User not found
WITHDRAW_EXISTS409A withdraw with this externalId already exists
OPERATION_BLOCKED409Withdrawals 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

For third-party payout rules and recipient data, see Third party transfers.


Did this page help you?