Integration basics

Configure OAuth and environment

Hosted networks (for example devnet + a provider such as 5n) use OAuth2 client credentials or password grants. Variables follow a shared prefix:

CANTON_CURRENT_NETWORK=devnet
CANTON_CURRENT_PROVIDER=5n

CANTON_DEVNET_5N_LEDGER_JSON_API_URI=https://…
CANTON_DEVNET_5N_LEDGER_JSON_API_CLIENT_ID=…
CANTON_DEVNET_5N_LEDGER_JSON_API_CLIENT_SECRET=…

CANTON_DEVNET_5N_VALIDATOR_API_URI=https://…
CANTON_DEVNET_5N_VALIDATOR_API_CLIENT_ID=…
CANTON_DEVNET_5N_VALIDATOR_API_CLIENT_SECRET=…

LocalNet (cn-quickstart with OAuth) narrows this: use new Canton({ network: 'localnet' }) so the SDK picks up default Keycloak URIs, validator / JSON API ports, and test client credentials — see examples/localnet-with-oauth2.ts in the repository.

To load a single API config from env in code:

import { CantonRuntime, EnvLoader, LedgerJsonApiClient } from '@fairmint/canton-node-sdk';

const config = EnvLoader.getConfig('LEDGER_JSON_API', {
  network: 'devnet',
  provider: '5n',
});

const runtime = new CantonRuntime(config);
const ledger = new LedgerJsonApiClient(runtime);

Expected outcome: EnvLoader.getConfig resolves CANTON_* keys; if required keys are missing it throws ConfigurationError with the variable names needed.

---

First authenticated request

After the runtime can obtain a token, call any method that requires auth. The Validator client is a good smoke path on LocalNet (getUserStatus). The Ledger getVersion() call proves JSON API reachability.

Unified Canton client

import { Canton } from '@fairmint/canton-node-sdk';

const canton = new Canton({ network: 'localnet' });

const version = await canton.ledger.getVersion();
console.log('Ledger API version', version.version);

const user = await canton.validator.getUserStatus();
console.log('Validator user', user);

Expected outcome: version.version is a non-empty string; getUserStatus() returns the current user envelope for your OAuth identity (exact fields depend on deployment).

---

Create a party

Use the createParty helper so onboarding matches how the Validator and Ledger interoperate on your network:

import { Canton, createParty } from '@fairmint/canton-node-sdk';

const canton = new Canton({ network: 'localnet' });

const { partyId, preapprovalContractId } = await createParty({
  ledgerClient: canton.ledger,
  validatorClient: canton.validator,
  partyName: `app-party-${Date.now()}`,
  amount: '10',
});

console.log('New party', partyId);
console.log('Preapproval CID', preapprovalContractId);

Expected outcome: A new Validator user exists; funded parties receive transfer offers and optionally a TransferPreapproval contract (preapprovalContractId when amount > 0).

Run the maintained script:

npx tsx examples/create-party.ts my-party 10

---

Related

Topic	Link
Ledger reads, submits, streams	Ledger operations
LocalNet smoke & transfers	LocalNet & transfers
Detailed env tables	Reference catalog