Wallets

Create wallets to hold balances, scope funds by currency, and power receive, exchange, transfer, and payout flows across the Verto platform.

✅

Baseline Unlock

Standard operational wallets (for your own business) are unlocked 1-3 weeks after Stage 1 KYB completion. View Go-Live Timeline →

✅ Before you create a wallet

Complete these steps before you provision wallets:

1. Authenticate and confirm you can send authorized API requests.
2. Choose the wallet currency you need for the flow you are building.
3. If you are creating the wallet for a downstream customer, create or identify the sub-account first.
4. Use the X-Sub-Account-Id header whenever the wallet should belong to a specific sub-account.

🏗️ Core Wallet Architecture

Every wallet in Verto is more than just a balance; it is a gateway to domestic and international rail connectivity.

🚀 Atlas Multi-Tenancy Logic

How you interact with wallets depends on your integration pathway.

🏦 Atlas for Fintech

You manage Master Wallets for corporate treasury, global clearing, and wholesale FX liquidity.

• Header: Standard Bearer Authentication.
• Context: Operates on the primary tenant ledger.

🏢 Atlas for Platforms

You manage Managed Wallets on behalf of your end-users (sub-accounts).

• Header: Requires the X-Sub-Account-Id routing header.
• Context: Operates on the siloed sub-tenant ledger.

🛑

Crucial Step: For platforms, create the sub-account first, then create wallets inside that customer context with X-Sub-Account-Id. See Login as a Sub-Account →.

🛠️ Lifecycle Management

1️⃣ Creating a Wallet

Provision a new ledger entity via a simple POST request.

curl -X POST https://api.sandbox.vertofx.com/wallets \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Sub-Account-Id: sub_customer_123" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "GBP",
    "customerReferenceLabel": "Operating Wallet",
    "type": "standard"
  }'

When this request succeeds, store the returned wallet ID because you will use it in receive, exchange, transfer, statement, and payout operations.

2️⃣ Viewing Details

Fetch real-time snapshots of available liquidity with the migrated wallet service routes.

Use the companyId returned by login and the walletId returned by wallet creation or listing. Do not use the legacy api-v3-sandbox.vertofx.com/profile/v2.2/wallets routes for new wallet list or wallet detail integrations.

Use wallet queries to power balance views, determine which wallet to debit, and verify that a collection or transfer was applied to the correct ledger.

🔄 Internal Transfers & Sweeping

Move capital instantly between wallets within the same parent or sub-account context. No SWIFT/SEPA latency—transfers are atomic.

• Primary Use Case: Sweeping multi-currency revenue into a single "Sweep Wallet" for mass FX conversion.
• Latency: < 100ms (Ledger-to-Ledger).

If you sweep sub-account funds, wait until the inbound receive event is confirmed before you move value out of the wallet.

🧩 Automated Reconciliation (Statement API)

For platforms managing high-velocity flows, manual reconciliation is impossible. The Statement API allows you to programmatically match your internal ledger against the Verto system.

Reconciliation Workflow

1. Fetch Wallet ID: Identify the specific ledger you want to audit.
2. Request Statement: Call GET /v2/statements?walletId=...&format=json.
3. Listen for Webhook: (For large datasets) Verto emits the wallet.statement.generated webhook when your historic CSV or JSON payload is ready for download.
4. Parse and Match: Ingest the JSON payload. Cross-reference the clientReference field injected during the payout with the lines in the statement.

Troubleshooting

🎯 Next Steps