Institutions, customers and accounts

How the bank and its customers are represented

Your bank is the organisation using Quant Flow. Within it, a customer is a party the bank holds accounts for, and a token account records that customer's position in one currency. A customer can have several token accounts.

The bank keeps the customer's name, due-diligence records and deposit information in its own systems. Quant Flow uses references supplied by the bank to connect token activity to those records. Operations teams need that mapping when investigating a payment or reconciling a position.

For onboarding, confirm the customer is eligible, prepare the currency and wait for account provisioning to finish before issuing or moving tokens. Removing access or deactivating a customer does not settle remaining balances or locks; review those obligations separately. Engineers can use the detailed model and lifecycle below.

The three levels

Customer and account operations use the organisation in the access token. Their references are scoped to the token's tenant_id. Do not supply another organisation to select its records. Other API areas have their own access rules; see Authentication.

Your core banking system stays the book of record. The platform stores only the references you give it. A customer record holds customerRef, a status and two timestamps. These customer records do not store names, addresses or KYC data, and it never interprets customerRef. Customer due diligence, and the link between a reference and a real person or entity, stay in your own systems.

Organisation, customer and account

%%{init: {"theme": "neutral"}}%%
flowchart TB
    Tenant["Organisation: tenant_id from token"] --> Customer["Customer: your customerRef"]
    Customer --> Account["Account: your accountRef / one asset"]
    Asset["ACTIVE asset contract"] --> Account
    Account --> Pending["202 / PENDING"]
    Pending --> Provision["Wallet provisioning"]
    Provision --> Active["ACTIVE / walletAddress"]
    Provision --> Failed["FAILED / failureReason"]

A customer can have multiple accounts. Track each account with an API read; do not submit token operations while provisioning is pending.

Register customer · Register account · Read account

Customers

You register a customer with your own reference. The reference must be unique within your organisation. A customer is ACTIVE from registration.

Customers are deactivated, never deleted, so a customerRef is never released for reuse.

Deactivating a customer also deactivates its ACTIVE accounts. Accounts that are PENDING, FAILED or already INACTIVE are not changed. Reactivating a customer does not reactivate its accounts. Each account must be reactivated individually.

Keep bank references separate from ledger addresses

Your bank owns the customer and account references and their mapping to core banking. Quant Flow provisions the account's ledger address. Use accountRef in token requests and retain walletAddress for evidence and operational diagnosis; do not replace the account reference with an address in a request field.

One customer can have several token accounts, including several for the same currency. Model that relationship explicitly in your adapter. A customer record identifies who the bank acts for; an account selects the particular holding being credited, debited or locked. Neither is the API user or machine principal submitting the instruction.

Provisioning, administrative status and on-chain controls are separate concerns. A registered account can still be pending provisioning; an inactive account retains its address and balance; a compliance freeze is not a deletion. Check the resource and operation states needed for your workflow rather than treating the presence of an account reference as readiness to pay.

Accounts

An account is one customer's holding of one asset. A customer can hold several accounts for the same asset. For that reason every token operation names an account, never a customer.

Before an account can be registered:

• the customer must exist and be ACTIVE;
• the asset must have an ACTIVE token contract. See Instruments and tokenised deposits.

Provisioning is asynchronous

Registration returns 202 Accepted with the account PENDING. The platform then provisions a wallet address for the account. When provisioning completes, the account becomes ACTIVE and carries a walletAddress. If provisioning is refused, the account becomes FAILED and failureReason says why.

Poll GET /api/accounts/{accountRef} for the authoritative provisioning status. The service also produces account.provisioned and account.provisioning_failed business events for delivery through configured webhooks. Confirm destination registration and delivery in your environment; do not rely on an untested callback.

Only ACTIVE and INACTIVE can be set through the account-status PATCH endpoint. Freeze and unfreeze are separate asynchronous controls, described below.

Accounts are deactivated, never deleted, so an accountRef is never released for reuse.

What the wallet address is. walletAddress is the account's address on the ledger. It is derived in the custody provider when the account is provisioned, and its key is held by the custody provider, never by the platform. Token operations are signed through the custody provider with keys that hold authority over the token contract, acting on behalf of the account whose tokens move. See Security and key management.

Which assets can be provisioned. A FAILED account can report an unsupported asset (the API Reference example shows Unsupported asset id 'JPY'). Custody is configured per currency during onboarding, so only currencies configured for your deployment can be provisioned. Arrange an additional asset with your platform contact before provisioning it, including contract deployment, custody and signing configuration.

Freeze and unfreeze an account

POST /api/accounts/{accountRef}/controls accepts operation: FREEZE or UNFREEZE and requires an Idempotency-Key. A freeze requires an ACTIVE account and a reason of at most 100 characters; the account becomes FROZEN immediately. An unfreeze requires a FROZEN account, takes an optional reason, and leaves the account frozen until confirmation makes it ACTIVE.

The first response is 202, a replay 200. It contains the control operation's transactionId, operation, state and timestamps, rather than the account's status. Read the operation and then the account to establish both outcomes. An unknown account returns 404; a wrong-state account or missing freeze reason returns 400. Confirm the caller's required permissions during onboarding.

POST /api/accounts/ACC-0001/controls HTTP/1.1
Host: api.qfp.quantnetwork.net
Authorization: Bearer <access token>
API-Version: 1.0.0
Content-Type: application/json
Idempotency-Key: freeze-account-0001-review-1

{
  "operation": "FREEZE",
  "reason": "Compliance review"
}

Operate the customer and account lifecycle

Keep the bank customer reference, account reference and asset mapping in your adapter. Quant Flow provisions the ledger wallet and reports account status; the bank remains responsible for customer due diligence and its deposit records. An account's existence is not proof of readiness: read ACTIVE and the wallet address, and separately confirm the currency contract and custody authority.

For a provisioning failure, retain failureReason and ask the relevant asset/custody owner to correct the cause before a supported retry. For access or compliance changes, distinguish status deactivation from asynchronous freeze/unfreeze. Read both the control transaction and account after a control request; request acceptance does not establish the final on-chain outcome.

Before retiring a customer, inventory account balances, known locks and unresolved operations. Deactivation preserves references and value; it is not a redemption or deletion workflow. Use Daily operations and monitoring and Access changes and offboarding.

Worked example

Register an account for an existing, active customer.

POST /api/accounts HTTP/1.1
Host: api.qfp.quantnetwork.net
Authorization: Bearer <access token>
API-Version: 1.0.0
Content-Type: application/json
Idempotency-Key: 7f1c2d9e-4b3a-4c8e-9f10-2a6b5d8c3e41

{
  "customerRef": "CUST-0001",
  "accountRef": "ACC-0001",
  "assetId": "GBP"
}

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "accountRef": "ACC-0001",
  "customerRef": "CUST-0001",
  "assetId": "GBP",
  "status": "PENDING",
  "createdAt": "2026-08-03T09:29:10.285Z",
  "updatedAt": "2026-08-03T09:29:10.285Z"
}

Read the account back until it leaves PENDING.

GET /api/accounts/ACC-0001 HTTP/1.1
Host: api.qfp.quantnetwork.net
Authorization: Bearer <access token>
API-Version: 1.0.0

HTTP/1.1 200 OK
Content-Type: application/json

{
  "accountRef": "ACC-0001",
  "customerRef": "CUST-0001",
  "assetId": "GBP",
  "status": "ACTIVE",
  "walletAddress": "0x4E55aD154FFfE514D7dEF1658dEbe593907121ae",
  "createdAt": "2026-08-03T09:29:10.285Z",
  "updatedAt": "2026-08-03T09:29:14.911Z"
}

A refused provisioning reads back like this:

{
  "accountRef": "ACC-0003",
  "customerRef": "CUST-0001",
  "assetId": "JPY",
  "status": "FAILED",
  "failureReason": "Unsupported asset id 'JPY'",
  "createdAt": "2026-08-03T10:05:19.663Z",
  "updatedAt": "2026-08-03T10:05:21.204Z"
}

walletAddress and failureReason are absent, not null, when they do not apply.

View in API Reference

• Register an account · POST
• Get an account · GET

Errors and edge cases

Listings of customers and accounts are ordered oldest first, with the reference as a tiebreaker. The order is fixed and there is no sort parameter. A filter that matches nothing returns an empty page, not a 404.

Follow a Recipe

Step through the code in JavaScript or Python, inspect illustrative responses, and open the connected endpoint schemas.

• Create a customer and provision an account

API Reference

Open an endpoint for request fields, response examples and the interactive API console.

Related pages

• Instruments and tokenised deposits
• Balances
• 2. Create a customer and an account
• Idempotency and retries
• Identities and entitlements

Implementation resources

Accounts code recipes.

Use Implement a backend client for request handling, durable idempotency and outcome tracking. The developer integration coverage map links every public operation to its API Reference and contract-derived code recipe. Replace example identifiers with values from your assigned environment.