Depósito y Retirada Programática
Esta guía está disponible en tres lenguajes de programación diferentes: Typescript, Kotlin y Flutter (Dart). Puedes cambiar la versión mostrada en cada página mediante los botones de arriba.
El estándar SEP-6 define una forma en que los anchors y billeteras pueden interactuar en nombre de los usuarios. Las billeteras utilizan este estándar para facilitar intercambios entre activos on-chain (como stablecoins) y activos off-chain (como fiat, u otros activos de red como BTC).
Por favor, nota que esto es para depósitos y retiradas programáticas. Para depósitos y retiradas alojados, donde el anchor interactúa con billeteras de manera interactiva usando un popup, por favor consulta Depósito y Retirada Alojados.
Obtener Información del Anchor
Comencemos creando un objeto sep6, que usaremos para todas las interacciones SEP-6:
- TypeScript
const sep6 = anchor.sep6();
Primero, obtengamos información sobre el soporte del anchor para SEP-6. Esta solicitud no requiere autenticación y devolverá información genérica, como las monedas admitidas y las características admitidas por el anchor. Puedes obtener una lista completa de los campos devueltos en la especificación SEP-6.
- TypeScript
const info = await sep6.info();
Iniciar un depósito
Antes de comenzar, asegúrate de haberte conectado al anchor y haber recibido un token de autenticación, como se describe en la guía de billetera [Stellar Authentication]. Usaremos authToken
en los ejemplos siguientes como el token de autenticación SEP-10, obtenido anteriormente.
Para iniciar una operación, necesitamos conocer un activo. Puedes codificar esto manualmente. Asegúrate de que sea uno que esté incluido en la respuesta de información anterior.
Antes de comenzar con el flujo de depósitos, asegúrate de que la cuenta de usuario haya establecido una línea de confianza para el activo con el que estás trabajando.
Comencemos con un depósito básico. Usaremos account
para representar la clave pública de nuestra cuenta.
- TypeScript
const deposit = await sep6.deposit({
authToken,
params: {
asset_code,
account,
},
});
Hay varias clases de respuestas, dependiendo de si el anchor necesita más información. Todos los depósitos y retiradas tendrán estos mismos tipos de respuesta:
1. Respuesta de éxito
Si la respuesta es exitosa (HTTP 200), entonces el anchor está procesando el depósito. Si necesita información adicional, la comunicará al proporcionar la información de la transacción.
2. Todavía procesando o denegado
Si se devuelve un HTTP 403 con datos: customer_info_status
, significa que la acción todavía está procesándose o no fue aceptada. En este caso, el campo more_info_url
debería tener un enlace que describa los siguientes pasos.
Una respuesta de ejemplo:
{
"type": "customer_info_status",
"status": "denied",
"more_info_url": "https://api.example.com/kycstatus?account=GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI"
}
3. Necesita más información KYC
Otra respuesta común es un HTTP 403, con la respuesta: non_interactive_customer_info_needed
. En este caso, el anchor necesita más información KYC a través de SEP-12.
Una respuesta de ejemplo:
{
"type": "non_interactive_customer_info_needed",
"fields" : ["family_name", "given_name", "address", "tax_id"]
}
Veamos cómo una billetera puede manejar esta situación. Primero, obtenemos el objeto de respuesta de depósito. Si la respuesta incluye este error, entonces podemos ver qué campos faltantes requiere el anchor.
- TypeScript
if (deposit.type === "non_interactive_customer_info_needed") {
// handle displaying the missing fields to the user
console.log(deposit.fields);
}
La billetera necesitará manejar la presentación al usuario de qué campos están faltando. Y para agregar esos campos, podemos usar la clase sep12 de la siguiente manera.
- TypeScript
const sep12 = await anchor.sep12(authToken);
// adding the missing kyc info (sample data)
await sep12.add({
sep9Info: {
family_name: "smith",
given_name: "john",
address: "123 street",
tax_id: "123",
},
});
Luego, podemos volver a llamar al método de depósito como antes y debería ser exitoso.
Más información sobre el envío de información KYC utilizando SEP-12 se puede encontrar en Proporcionar información KYC.
Proporcionar información KYC
Un anchor puede responder a una solicitud de depósito o retirada diciendo que necesita información KYC adicional. Para facilitar esto, SEP-6 admite agregar información KYC de un cliente a través de SEP-12. El usuario puede enviar la información requerida utilizando el objeto sep12 de la siguiente manera.
Agreguemos algo de información KYC para nuestra cuenta usando datos de muestra. Los datos binarios (por ejemplo, datos de imagen) deben enviarse en un campo separado. Los campos permitidos para enviar al anchor se describen en SEP-9.
- TypeScript
const sep12 = await anchor.sep12(authToken);
await sep12.add({
sep9Info: {
first_name: "john",
last_name: "smith",
email_address: "[email protected]",
bank_number: "12345",
bank_account_number: "12345",
},
sep9BinaryInfo: {
photo_id_front: Buffer.from("./path/to/image/front"),
photo_id_back: Buffer.from("./path/to/image/back"),
},
});
Iniciar una retirada
Iniciar una retirada es similar a un depósito y tiene los mismos tipos de respuesta que se describieron anteriormente.
- TypeScript
const resp = await sep6.withdraw({
authToken,
params: {
asset_code: "SRT",
account: accountKp.publicKey,
type: "bank_account",
dest: "123",
dest_extra: "12345",
},
});
Obtener información de intercambio
Si el anchor admite cotizaciones SEP-38, puede soportar depósitos que hagan un puente entre activos no equivalentes. Por ejemplo, un anchor recibe BRL a través de una transferencia bancaria y a cambio envía USDC (de valor equivalente menos tarifas) al usuario en Stellar.
Las funciones de intercambio sep6 permiten a un usuario iniciar un depósito o una retirada de intercambio con el anchor, y el anchor puede comunicar los siguientes pasos al usuario.
Primero, comencemos un intercambio de depósito con datos de muestra. Los activos se describen usando el esquema SEP-38.
- TypeScript
const resp = await sep6.depositExchange({
authToken,
params: {
destination_asset:
"stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
source_asset: "iso4217:USD",
amount: "10",
},
});
La respuesta sigue los mismos tipos que todos los depósitos y retiradas para SEP-6.
Ahora, creemos un intercambio de retirada, que sigue el mismo formato que el intercambio de depósito. También especificamos que es una retirada a cuenta bancaria utilizando el campo type
.
- TypeScript
const resp = await sep6.withdrawExchange({
authToken,
params: {
destination_asset: "iso4217:USD",
source_asset:
"stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
amount: "10",
type: "bank_account",
},
});
La respuesta sigue los mismos tipos que todos los depósitos y retiradas para SEP-6.
Obteniendo Información de Transacción
En el flujo típico, la billetera obtendría datos de transacción para notificar a los usuarios sobre actualizaciones de estado. Esto se hace a través del endpoint SEP-6 GET /transaction
y GET /transactions
.
Seguimiento de Transacción
Veamos cómo usar el sdk para rastrear los cambios de estado de transacción. Usaremos la clase Watcher
para este propósito. Primero, inicialicemos y comencemos a rastrear una transacción.
- TypeScript
const watcher = anchor.sep6().watcher();
const { stop, refresh } = watcher.watchOneTransaction({
authToken,
assetCode,
id: txId,
onSuccess,
onMessage,
onError,
});
Alternativamente, podemos rastrear múltiples transacciones para el mismo activo.
- TypeScript
const watcher = anchor.sep6().watcher();
const { stop, refresh } = watcher.watchAllTransactions({
authToken,
assetCode,
onMessage,
onError,
});
Recuperando Transacción
Mientras que la clase Watcher
ofrece potentes capacidades de seguimiento, a veces es necesario obtener solo una transacción (o transacciones) una vez. La clase Anchor
te permite obtener una transacción por ID, ID de transacción Stellar o ID de transacción externa:
- TypeScript
const transaction = await anchor
.sep6()
.getTransactionBy({ authToken, id: transactionId });
También es posible obtener transacciones por el activo.
- TypeScript
const transactions = await anchor.sep6().getTransactionsForAsset({
authToken,
assetCode,
});