--- title: "Transferencias" description: "Aprende a iniciar y gestionar transferencias desde tus billeteras." url: https://docs.fystack.io/es/withdrawals last_updated: 2026-11-13 --- > ## Documentation index > Fetch the complete documentation index at: https://docs.fystack.io/llms.txt > Use it to discover all available pages before exploring further. # Transferencias Esta guía explica cómo transferir fondos desde tus billeteras a direcciones externas. --- ## Solicitar un retiro **Endpoint:** `POST /wallets/:wallet_id/request-withdrawal` Crea una nueva solicitud de retiro desde una billetera. El retiro requerirá la aprobación de usuarios autorizados. ### Headers - `X-Idempotency-Key` (header, recommended): Un UUID que identifica este retiro para que se procese una sola vez. Si se vuelve a enviar la misma clave dentro de las 24 horas, se devuelve la respuesta almacenada en caché de la solicitud original en lugar de crear un retiro duplicado. Vincula la clave al retiro en tu propio sistema: usa tu ID interno de retiro o transferencia si es un UUID; de lo contrario, genera un UUID una sola vez al crear ese registro y guárdalo junto a él. Envía la misma clave en cada reintento. No generes una clave nueva por intento, porque cada clave nueva se trata como un retiro nuevo. ### Parámetros - `asset_id` (string, required): El UUID del activo que se va a retirar. - `amount` (string, required): El monto a retirar, como string en formato decimal. - `recipient_address` (string, required): La dirección blockchain a la que se enviarán los fondos. ### Respuesta - `id` (string): El UUID de la solicitud de retiro. - `status` (string): Estado actual del retiro: - `PENDING_APPROVAL`: a la espera de las aprobaciones de los usuarios autorizados - `PENDING`: aprobado y a la espera de ser procesado - `EXECUTED`: la transacción se envió a la blockchain - `SUCCESS`: la transacción se confirmó en la blockchain - `REJECTED`: un aprobador rechazó el retiro - `FAILED`: la transacción no se pudo ejecutar - `wallet_id` (string): El UUID de la billetera de origen. - `asset_id` (string): El UUID del activo que se retira. - `amount` (string): El monto del retiro. - `recipient_address` (string): La dirección blockchain de destino. - `creator_id` (string): El UUID del usuario que creó la solicitud de retiro. - `withdrawal_approvals` (array): Lista de los estados de aprobación de los usuarios autorizados. - `created_at` (string): Marca de tiempo de la creación de la solicitud. - `updated_at` (string): Marca de tiempo de la última actualización de estado. > **Info.** El proceso de retiro sigue este flujo: > > 1. PENDING_APPROVAL → a la espera de las aprobaciones requeridas > 2. PENDING → aprobado y en cola para su procesamiento > 3. EXECUTED → transacción enviada a la blockchain > 4. SUCCESS → transacción confirmada > > O, si se rechaza o falla: > > - REJECTED → un aprobador rechazó el retiro > - FAILED → la transacción no se pudo ejecutar **Request** `POST /wallets/:wallet_id/request-withdrawal` ```typescript import { FystackSDK, Environment } from "@fystack/sdk" const apiCredentials = { apiKey: process.env.API_KEY, apiSecret: process.env.API_SECRET } const sdk = new FystackSDK({ credentials: apiCredentials, environment: Environment.Sandbox, logger: true }) const response = await sdk.requestWithdrawal( "e0851607-417a-475a-b399-5f3aa262b81d", { assetId: "f1be472d-1338-43ff-b547-06faba7ecce7", amount: "0.001", recipientAddress: "0xe6EBF81E9C225BbCEa9b5399E0D0d0f29f30f119" } ) ``` ```bash curl -X POST https://api.fystack.io/api/v1/wallets/e0851607-417a-475a-b399-5f3aa262b81d/request-withdrawal \ -H "ACCESS-API-KEY: your_api_key" \ -H "ACCESS-TIMESTAMP: 1667836889" \ -H "ACCESS-SIGN: YourBase64EncodedSignature==" \ -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \ -H "Content-Type: application/json" \ -d '{ "asset_id": "f1be472d-1338-43ff-b547-06faba7ecce7", "amount": "0.001", "recipient_address": "0xe6EBF81E9C225BbCEa9b5399E0D0d0f29f30f119" }' ``` ```json { "success": true, "message": "success", "code": 0, "data": { "id": "0de79230-a820-4bd4-b020-883d395faa87", "wallet_id": "e0851607-417a-475a-b399-5f3aa262b81d", "asset_id": "f1be472d-1338-43ff-b547-06faba7ecce7", "amount": "1000", "recipient_address": "0x7c2BbE2e02af09F1cf9aFd4A79EC201DC841675a", "status": "PENDING_APPROVAL", "creator_id": "075243c1-962e-4803-83da-d73c78b8b060", "withdrawal_approvals": [ { "id": "9a85c312-7d3b-4c6f-9f4e-123456789abc", "withdrawal_id": "0de79230-a820-4bd4-b020-883d395faa87", "user_id": "075243c1-962e-4803-83da-d73c78b8b060", "status": "PENDING", "created_at": "2025-08-11T17:37:29.815148+07:00", "updated_at": "2025-08-11T17:37:29.815148+07:00" }, { "id": "8b74d123-9e5f-4a2d-8c3b-987654321def", "withdrawal_id": "0de79230-a820-4bd4-b020-883d395faa87", "user_id": "165243c1-962e-4803-83da-d73c78b8b070", "status": "APPROVED", "created_at": "2025-08-11T17:37:29.815148+07:00", "updated_at": "2025-08-11T17:38:15.623147+07:00" } ], "created_at": "2025-08-11T17:37:29.815148+07:00", "updated_at": "2025-08-11T17:37:29.815148+07:00" } } ``` --- ## Obtener el estado de un retiro **Endpoint:** `GET /wallets/:wallet_id/withdrawals/:withdrawal_id` Obtén el estado actual de una solicitud de retiro. ### Respuesta - `success` (boolean): Indica si la solicitud se realizó correctamente. - `data` (object): Contiene los detalles del retiro. - `id` (string): El UUID de la solicitud de retiro. - `status` (string): Estado actual del retiro. - `amount` (string): El monto del retiro. - `recipient_address` (string): La dirección blockchain de destino. - `creator` (object): Información sobre el usuario que creó el retiro. - `asset` (object): Detalles del activo que se retira. - `transaction` (object): Detalles completos de la transacción una vez ejecutada. **Request** `GET /wallets/:wallet_id/withdrawals/:withdrawal_id` ```typescript import { FystackSDK, Environment } from "@fystack/sdk" const apiCredentials = { apiKey: process.env.API_KEY, apiSecret: process.env.API_SECRET } const sdk = new FystackSDK({ credentials: apiCredentials, environment: Environment.Sandbox, logger: true }) // Get withdrawal status const withdrawal = await sdk.getWithdrawalStatus( "e0851607-417a-475a-b399-5f3aa262b81d", "4cebc6c3-1e46-4166-ab59-86a59971215f" ) // Check withdrawal status if (withdrawal.status === 'SUCCESS') { console.log('Transaction hash:', withdrawal.transaction.tx_hash) console.log('Amount:', withdrawal.amount) console.log('Asset:', withdrawal.asset.symbol) } // Check approval status const approvals = withdrawal.withdrawal_approvals const pendingApprovals = approvals.filter(a => a.status === 'PENDING') const approvedCount = approvals.filter(a => a.status === 'APPROVED').length console.log('Pending approvals:', pendingApprovals.length) console.log('Approved count:', approvedCount) ``` ```bash curl -X GET https://api.fystack.io/api/v1/wallets/e0851607-417a-475a-b399-5f3aa262b81d/withdrawals/4cebc6c3-1e46-4166-ab59-86a59971215f \ -H "ACCESS-API-KEY: your_api_key" \ -H "ACCESS-TIMESTAMP: 1667836889" \ -H "ACCESS-SIGN: YourBase64EncodedSignature==" ``` ```json { "success": true, "message": "success", "code": 0, "data": { "id": "4cebc6c3-1e46-4166-ab59-86a59971215f", "created_at": "2025-07-29T21:44:23.763113+07:00", "updated_at": "2025-07-29T21:45:07.204964+07:00", "amount": "0.000001622515351558", "status": "SUCCESS", "recipient_address": "0xf2acfF1D9d576E9b8B7C7d58A449F599A9A54edA", "creator_id": "075243c1-962e-4803-83da-d73c78b8b060", "creator": { "id": "075243c1-962e-4803-83da-d73c78b8b060", "username": "Dev team" }, "asset_id": "a469642e-5466-4d69-834d-537f33ee5c81", "asset": { "id": "a469642e-5466-4d69-834d-537f33ee5c81", "name": "Ethereum Sepolia", "symbol": "ETH", "decimals": 18, "logo_url": "https://icons.iconarchive.com/icons/cjdowner/cryptocurrency-flat/512/Ethereum-ETH-icon.png", "is_native": true, "address_type": "evm", "network_id": "23d13c03-1f3c-4e2a-9aef-1771a244b7f6" }, "withdrawal_approvals": [ { "id": "dfa94b32-83f5-4808-8091-9a3c270d4f1d", "status": "PENDING", "user": { "username": "Thi Nguyen", "email": "nguyendanganhthi247@gmail.com" } }, { "id": "776303fd-762e-4593-9f66-93631dd226e0", "status": "APPROVED", "user": { "username": "Dev team", "email": "devteam@fystack.io" } } ], "transaction": { "tx_hash": "0xa1ec8bab32baebad1211e838d655777640e78102b39b008bd00a8b3e5d1f3c00", "status": "confirmed", "block_number": 8868747, "from_address": "0xA793457d84CFD255Ed68295984300C4f799E759F", "to_address": "0xf2acfF1D9d576E9b8B7C7d58A449F599A9A54edA", "amount": "0.000001622515351558", "tx_fee": "0.000001296799854", "price_native_token": "3808.475025265875", "direction": "out", "type": "withdrawal", "method": "transfer" } } } ```