Getting Started

From 0 to integration

This guide takes you from a fresh account to a working stablecoin integration: create a master wallet, generate an API key, hand a customer a deposit address, receive the deposit webhook, and pay out.

ℹ

What you'll need: an Octo account and your Wallet ID + API key (Step 2). The base URL is http://localhost:8080 in local development.

Create an account & master wallet

Sign up in the dashboard, then create a master wallet. On testnet it's funded automatically. You'll get back a Wallet ID and a one-time recovery phrase — store the phrase securely.

Prefer the API? Sign up and create a wallet with your login token:

cURL

# create a master wallet (login-token auth)
curl -X POST http://localhost:8080/v1/wallets \
  -H "authorization: Bearer <LOGIN_TOKEN>" \
  -H "content-type: application/json" \
  -d '{"label":"Acme treasury"}'

Generate your API key

On the wallet's Developers page, click Generate API Key. The full key (octo_sk_test_…) is shown once — copy it now. This key authorizes integration requests for this wallet.

cURL

curl -X POST http://localhost:8080/v1/wallets/<WALLET_ID>/api-key \
  -H "authorization: Bearer <LOGIN_TOKEN>"

# → { "data": { "api_key": "octo_sk_test_ab12…", "prefix": "octo_sk_test_ab12" } }

Create a deposit address for a customer

When a user wants to deposit, generate a dedicated address. Pass a customer_ref and any metadata — both are echoed back to you in webhooks for reconciliation.

cURL

curl -X POST http://localhost:8080/v1/wallets/<WALLET_ID>/addresses \
  -H "authorization: Bearer octo_sk_test_ab12…" \
  -H "content-type: application/json" \
  -d '{ "customer_ref": "user_42", "metadata": { "plan": "pro" } }'

Response

{
  "statusCode": 201,
  "message": "Created",
  "data": {
    "muxed_address": "MA7…",        // give this to your user
    "base_address": "GBYK…",        // G…+memo fallback
    "memo_id": 7,
    "customer_ref": "user_42"
  }
}

Show muxed_addressto your user as their deposit destination. If their wallet can't send to M…, give them base_address + memo memo_id instead.

Receive the deposit webhook

Register a webhook endpoint once. When a deposit confirms on-chain, Octo POSTs a signed deposit.created event to your URL, including the address metadata.

cURL — register endpoint

curl -X POST http://localhost:8080/v1/wallets/<WALLET_ID>/webhooks \
  -H "authorization: Bearer octo_sk_test_ab12…" \
  -H "content-type: application/json" \
  -d '{ "url": "https://your.app/webhooks/octo" }'

# → returns a signing secret (shown once)

Event delivered to your URL

POST https://your.app/webhooks/octo
X-Octo-Signature: <hmac-sha256 hex>

{
  "event": "deposit.created",
  "data": {
    "amount_stroops": 50000000,
    "asset_code": "native",
    "memo_id": 7,
    "status": "confirmed",
    "metadata": { "plan": "pro" }
  }
}

Verify the signature (see Webhooks), then credit your user.

Pay out (withdraw)

To send funds out of the master wallet, call withdraw. For safety, withdrawals require a dashboard login token, not an API key. An Idempotency-Key makes retries safe.

cURL

curl -X POST http://localhost:8080/v1/wallets/<WALLET_ID>/withdraw \
  -H "authorization: Bearer <LOGIN_TOKEN>" \
  -H "Idempotency-Key: payout-9f3c" \
  -H "content-type: application/json" \
  -d '{ "destination": "G…DEST", "amount_stroops": 10000000 }'

⚠

Amounts are integer stroops (1 XLM = 10,000,000 stroops). Reusing an Idempotency-Key returns the original result instead of paying twice.

That's it

You now have the full deposit → notify → withdraw loop. See the API Reference for every endpoint and the Webhooks guide for signature verification.