VANK Stellar Anchor — Integration Guide

# Read the environment's stellar.toml — it is the source of truth
curl https://dev-stable-anchor.thisisvank.com/.well-known/stellar.toml   # production: anchor.thisisvank.com

# Without the SDK, SEP-10 is two calls (any language):
GET  https://dev-stable-anchor.thisisvank.com/auth?account=G...        # → { transaction, network_passphrase }
#    Verify the challenge BEFORE signing: read_challenge_transaction(xdr, toml SIGNING_KEY, passphrase, home_domain, web_auth_domain) in your language's SDK
#    Sign it with the account key (and your domain key if you sent client_domain)
POST https://dev-stable-anchor.thisisvank.com/auth   {"transaction": "<xdr firmado>"}   # → { token }  (JWT, 24 h)

yarn add @stellar/typescript-wallet-sdk

import { Wallet, SigningKeypair, DomainSigner } from "@stellar/typescript-wallet-sdk";

const HOME_DOMAIN = "dev-stable-anchor.thisisvank.com"; // sandbox · production: anchor.thisisvank.com
const CLIENT_DOMAIN = "tu-dominio.com";                 // yours, the one publishing your SIGNING_KEY

async function authenticate(authSecretKey: string) {
  const wallet = Wallet.TestNet(); // production: Wallet.MainNet()
  const anchor = wallet.anchor({ homeDomain: HOME_DOMAIN });
  const sep10 = await anchor.sep10();
  const authKey = SigningKeypair.fromSecret(authSecretKey);

  // Your backend co-signs the challenge with your domain key.
  // The SECRET key never leaves it, and never reaches the browser.
  const walletSigner = new DomainSigner("https://" + CLIENT_DOMAIN + "/sign", {});

  return await sep10.authenticate({
    accountKp: authKey,
    walletSigner,
    clientDomain: CLIENT_DOMAIN,
  });
}

// On YOUR backend. It receives the challenge, signs it with your domain key and returns it.
// POST /sign  →  { transaction, network_passphrase }
import { Transaction, Keypair } from "@stellar/stellar-sdk";

app.post("/sign", (req, res) => {
  const { transaction, network_passphrase } = req.body;
  const tx = new Transaction(transaction, network_passphrase);
  tx.sign(Keypair.fromSecret(process.env.CLIENT_DOMAIN_SECRET!)); // your SIGNING_KEY's secret
  res.json({ transaction: tx.toXDR(), network_passphrase });
});

# https://your-domain/.well-known/stellar.toml
VERSION = "2.7.0"
SIGNING_KEY = "G...YOUR_APPS_PUBLIC_KEY"

// Withdrawal (off-ramp): the user sends USDC and receives COP
const { url, id } = await anchor.sep24().withdraw({
  authToken,
  withdrawalAccount: USER_STELLAR_PUBLIC_KEY,
  assetCode: "USDC",
  lang: "en",
});
// Open `url` in a webview: VANK's UI guides the rest

// Deposit (on-ramp): the user pays COP (PSE) and receives USDC
const { url, id } = await anchor.sep24().deposit({
  authToken,
  destinationAccount: USER_STELLAR_PUBLIC_KEY,
  assetCode: "USDC",
  lang: "en",
});

const watcher = anchor.sep24().watcher();
const { stop } = watcher.watchOneTransaction({
  authToken,
  assetCode: "USDC",
  id: transactionId,
  onMessage: (tx) => {
    if (tx.status === "pending_user_transfer_start") {
      // Withdrawal: send the USDC now. Deposit: wait for the user's payment
    }
  },
  onSuccess: (tx) => { /* completed */ },
  onError: (tx) => { /* error */ },
});

# Without the SDK: start and poll (sandbox; production: anchor.thisisvank.com)
curl -X POST "https://dev-stable-anchor.thisisvank.com/sep24/transactions/deposit/interactive" \
  -H "Authorization: Bearer $SEP10_JWT" -H "Content-Type: application/json" \
  -d '{"asset_code":"USDC","account":"G...","lang":"es"}'      # or /withdraw/interactive → { url, id }

curl "https://dev-stable-anchor.thisisvank.com/sep24/transaction?id=$TRANSACTION_ID" \
  -H "Authorization: Bearer $SEP10_JWT"

npm install @stellar/stellar-sdk        # sign SEP-10 and the on-chain payment
# Nothing else: the rest of SEP-6 is plain HTTP (fetch).

const ANCHOR = "https://dev-stable-anchor.thisisvank.com";   // SEP-6 lives TODAY in the sandbox
const auth = { Authorization: `Bearer ${authToken}` };   // SEP-10 JWT (step 3)

// 1) Request the withdrawal. Returns an id; you cannot send the USDC yet.
const { id } = await fetch(
  `${ANCHOR}/sep6/withdraw?asset_code=USDC&account=${account}&amount=2&type=breb`,
  { headers: auth },
).then((r) => r.json());

// 2) Poll the transaction and REACT to its status.
const tx = async () =>
  (await fetch(`${ANCHOR}/sep6/transaction?id=${id}`, { headers: auth }).then((r) => r.json()))
    .transaction;

// Right after creation it is incomplete: wait for the engine's FIRST cycle (up to ~30s) before deciding anything. Ask only once now and you skip the next step.
let t = await tx();
while (t.status === "incomplete") { await sleep(5000); t = await tx(); }
if (t.status === "pending_customer_info_update") {
  // 3) Data is missing. ASK which — never guess.
  const need = await fetch(
    `${ANCHOR}/sep12/customer?account=${account}&transaction_id=${id}`,
    { headers: auth },
  ).then((r) => r.json());
  console.log(need.fields);   // each field carries a description for your user

  // 4) Send them BOUND to this transaction. bank_account_number = the Bre-B key.
  await fetch(`${ANCHOR}/sep12/customer`, {
    method: "PUT",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
      account,
      transaction_id: id,
      type: "sep6-withdrawal",   // withdrawal context: this is how SEP-12 knows the key is required
      // YOUR USER, the one withdrawing. Same as what they type into our form in SEP-24.
      first_name: "Ana", last_name: "Pérez",
      email_address: "ana@example.com",
      id_type: "CC", id_number: "1000000001",
      // THE BENEFICIARY: only their key. You do NOT send their name or document — we resolve them against the Bre-B directory.
      bank_account_number: "@llaveDeTuUsuario",
    }),
  });
}

// 5) POLL — do not expect an immediate answer. After the PUT, the transaction
//    can take up to ~30s to advance: our engine works in cycles.
while (["incomplete", "pending_customer_info_update"].includes((t = await tx()).status)) await sleep(5000);
// Once it reaches pending_user_transfer_start you have the destination and memo.
// t.withdraw_anchor_account · t.withdraw_memo (memo_type "id") · t.amount_out = net COP
// t.fee_details.total comes in USDC: it is the same fee the quote gave you in COP, in another unit
// t.message = the resolved beneficiary: show it to the user BEFORE signing

// 6) Send the USDC to that account with THAT memo, then keep polling until completed.

// 1) Firm quote (optional, but it is what guarantees the rate for your user)
// USDC_ISSUER: the issuer you read from the environment's stellar.toml (section 3). Never hardcoded.
const q = await fetch(`${ANCHOR}/sep38/quote`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    sell_asset: "iso4217:COP", buy_asset: `stellar:USDC:${USDC_ISSUER}`,
    sell_amount: "5000", sell_delivery_method: "bank_transfer",
    country_code: "CO", context: "sep6",
  }),
}).then((r) => r.json());
// q.price · q.buy_amount · q.fee.total  ← the fee comes SEPARATELY, not inside the price

// 2) Start the deposit with that quote.
const { id } = await fetch(
  `${ANCHOR}/sep6/deposit-exchange?amount=5000&destination_asset=USDC` +
  `&source_asset=iso4217:COP&quote_id=${q.id}&account=${account}&type=bank_transfer`,
  { headers: auth },
).then((r) => r.json());
// CAREFUL: this response does NOT carry the link. Only { how, id }.

// 3) The link lives in the TRANSACTION.
const t = await fetch(`${ANCHOR}/sep6/transaction?id=${id}`, { headers: auth })
  .then((r) => r.json()).then((r) => r.transaction);
// t.more_info_url            → open it in a webview. Its token lives 10 min; if it expires, re-read and you get a new one.
// t.user_action_required_by  → how long your user has. TODAY it comes null: use the quote's expires_at

// 4) Your user picks a bank and pays through PSE. Keep polling until completed.

# SEP-6 · deposit — does NOT need SEP-12: identity is verified in the more_info_url form
GET /sep6/deposit?asset_code=USDC&account=G...&amount=2&type=bank_transfer
#   → pay through the transaction's more_info_url (same form, same test PSE)

# SEP-6 · withdrawal — DOES need SEP-12: PUT /sep12/customer (Authorization: Bearer <SEP-10 JWT>)
{
  "account": "G...YOUR_TESTNET_ACCOUNT",
  "type": "sep6-withdrawal",
  "first_name": "Tester",                     # who withdraws: your user
  "last_name": "Sandbox",
  "email_address": "tester@example.com",
  "id_type": "CC",
  "id_number": "1000000001",
  "bank_account_number": "@alphamunKey01"     # the beneficiary: only their Bre-B key
}
GET /sep6/withdraw?asset_code=USDC&account=G...&amount=1&type=breb   # amount=1.11 → refunded

# SEP-6 · deposit — does NOT need SEP-12: identity is verified in the more_info_url form
GET /sep6/deposit?asset_code=USDC&account=G...&amount=2&type=bank_transfer
#   → pay through the transaction's more_info_url (same form, same test PSE)

# SEP-6 · withdrawal — DOES need SEP-12: PUT /sep12/customer (Authorization: Bearer <SEP-10 JWT>)
{
  "account": "G...YOUR_TESTNET_ACCOUNT",
  "type": "sep6-withdrawal",
  "first_name": "Tester",                     # who withdraws: your user
  "last_name": "Sandbox",
  "email_address": "tester@example.com",
  "id_type": "CC",
  "id_number": "1000000001",
  "bank_account_number": "@alphamunKey01"     # the beneficiary: only their Bre-B key
}
GET /sep6/withdraw?asset_code=USDC&account=G...&amount=1&type=breb   # amount=1.11 → refunded