# Configuration (/developers/reference/configuration) One file per network at `config/.json`, validated against a Zod schema on load. See [Networks and configuration](/developers/concepts/networks-and-configuration) for how the file is found and what loading checks. ## Top level [#top-level] | Field | Type | Meaning | | ------------- | ------------------------------------- | -------------------------------------------------------------- | | `network` | `"mainnet" \| "preprod" \| "preview"` | Must match the network the file is loaded as. | | `providers` | object | Chain access. | | `assets` | array, at least one | The asset registry for this network. | | `venues` | array | Every venue, enabled or not. | | `oracle` | object | Pyth configuration. | | `settlement` | object | This project's settlement validator deployment. | | `tagging` | object | The CIP-20 label and project name. | | `routing` | object | Routing parameters. | | `chainLimits` | object | Fallback chain limits, asserted against live values by a test. | ## `providers` [#providers] | Field | Type | Meaning | | ------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------- | | `primary` | `"koios" \| "blockfrost"` | The provider that is built and used. | | `fallback` | same, or `null` | Built when configured and its credentials are present. Never a silent substitute for the primary. | | `koios.baseUrl` | URL | For example `https://preprod.koios.rest/api/v1`. | | `koios.bearerTokenEnv` | string or `null` | Name of the variable holding an optional bearer token. | | `blockfrost.baseUrl` | URL | For example `https://cardano-preprod.blockfrost.io/api/v0`. | | `blockfrost.projectIdEnv` | string | Name of the variable holding the project id. | | `ogmios.url` | string or `null` | Websocket URL, or null when none is configured. | | `kupo.url` | string or `null` | As above. | Credentials are never inlined. The configuration holds the **name** of the environment variable. ## `assets[]` [#assets] | Field | Type | Meaning | | -------------------- | ------------------- | ------------------------------------------------------ | | `symbol` | string | Unique per network. Used by `--in` and `--out`. | | `policyId` | 56 hex chars | 28 byte policy hash, lower case. | | `assetNameHex` | hex, up to 64 chars | Asset name, lower case hex. | | `decimals` | integer 0 to 30 | Base unit exponent. | | `fingerprint` | `asset1...` | CIP-14 fingerprint, recomputed and compared on load. | | `stablecoin` | boolean | The product routes this asset as user input or output. | | `verifiedStablecoin` | boolean | Only true with a signed Cardano Token Registry entry. | | `decimalsSource` | enum | Where the decimal count came from. | | `decimalsEvidence` | URL or `null` | Required when `decimalsSource` is `issuer-declared`. | | `note` | string, optional | Free text recorded with the entry. | ### `decimalsSource` [#decimalssource] | Value | Meaning | | ------------------------- | --------------------------------------------------------------------------------------- | | `token-registry` | The signed Cardano Token Registry entry from `tokens.cardano.org`. | | `provider-token-registry` | Registry metadata a chain provider serves for a network the public host does not cover. | | `issuer-declared` | The issuer's own published constant. Requires `decimalsEvidence`. | | `undeclared` | Nobody has declared it. `decimals` must then be 0, so amounts are shown in base units. | Three refinements are enforced by the schema: * An `issuer-declared` entry must record its evidence URL. * Only a `token-registry` entry may be a verified stablecoin. * An `undeclared` entry must carry `decimals: 0`. ## `venues[]` [#venues] | Field | Type | Meaning | | ---------------------- | ---------------------------------- | ------------------------------------------------------------------ | | `id` | string | Stable venue identifier, for example `danogo-clmm`. | | `displayName` | string | Shown in the interface and in savings claims. | | `executionClass` | `"kernel" \| "commitment"` | Must match the adapter's own declaration. | | `enabled` | boolean | False keeps a venue defined but out of routing here. | | `poolScriptHash` | 56 hex chars or `null` | Null means not deployed on this network, and the venue is skipped. | | `poolScriptAddress` | bech32 or `null` | | | `orderScriptHash` | 56 hex chars or `null` | Commitment class venues only. | | `orderScriptAddress` | bech32 or `null` | | | `poolScriptRef` | `txHash#index` or `null` | Published reference script, so the transaction does not embed it. | | `orderScriptRef` | `txHash#index` or `null` | | | `referenceUtxos` | record of `txHash#index` or `null` | Venue specific references, for example a protocol config UTxO. | | `executionFeeLovelace` | decimal string or `null` | Execution or batcher fee. | | `depositLovelace` | decimal string or `null` | Refundable deposit. | | `params` | record | Venue specific values the adapter interprets. | ## `oracle.pyth` [#oraclepyth] | Field | Type | Meaning | | ----------------------- | ------------------------ | --------------------------------------------------------------------------------- | | `enabled` | boolean | | | `withdrawScriptHash` | 56 hex chars or `null` | Pyth's own published withdraw script. | | `storageAddress` | bech32 or `null` | Where the published price UTxO sits. A different script from the withdraw script. | | `rewardAddress` | bech32 stake or `null` | Reward account of the withdraw script. | | `withdrawScriptRef` | `txHash#index` or `null` | Published reference script carrying the withdraw script. | | `websocketUrl` | string or `null` | | | `apiKeyEnv` | string or `null` | Name of the variable holding the Lazer access token. | | `trustedSignerExpiry` | string or `null` | Recorded expiry of the deployment's trusted signer. | | `feeds` | record of feed | Keyed by a short name, for example `adaUsd`. | | `maxPriceAgeMs` | positive integer | Maximum accepted age of a price update. | | `deviationThresholdBps` | positive integer | A quote is refused when a pool price differs by more. | A feed carries `id` (the Lazer numeric feed id), `label`, and `expectedExponent` which is an integer or `null`. ## `settlement` [#settlement] | Field | Type | Meaning | | ----------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `validatorHash` | 56 hex chars or `null` | Null until deployed on this network. | | `address` | bech32 or `null` | | | `referenceScript` | `txHash#index` or `null` | | | `deploymentTx` | 64 hex chars or `null` | The transaction that published the script. The checker proves the script's first on-chain appearance is this transaction. | | `expirySlots` | positive integer | How long a settlement UTxO waits before the refund path opens. | ## `tagging` [#tagging] | Field | Type | Meaning | | ------------- | ---------------- | ------------------------------------------------------------------------------------ | | `label` | positive integer | CIP-20 metadata label. 674 in both shipped configurations. | | `projectName` | non empty string | Every tag must have a line starting with this. Immutable once transactions carry it. | ## `routing` [#routing] | Field | Type | Meaning | | -------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------- | | `intermediateAssets` | array of `"ada"` or symbol | Allowed as an intermediate hop, never as user input or output. | | `maxPathLength` | integer 1 to 4 | Maximum hops in a candidate path. | | `maxCandidatePaths` | integer 1 to 16 | Maximum candidate paths carried into the subset enumeration. | | `defaultSlippageBps` | integer 0 to 10 000 | Deducted from the expected output to derive the on-chain minimum. | | `singleClassPreferenceBps` | integer 0 to 10 000 | A single class route is preferred when its net output is within this many basis points of a mixed route. | | `dynamicFeePolicy` | `"exclude" \| "label"` | What to do with pools that can change their fee after the quote. | Both shipped configurations use `intermediateAssets: ["ada"]`, `maxPathLength: 3`, `maxCandidatePaths: 8`, `defaultSlippageBps: 50`, `singleClassPreferenceBps: 10` and `dynamicFeePolicy: "exclude"`. ## `chainLimits` [#chainlimits] `maxTxSize`, `maxTxExMem` and `maxTxExSteps`, all positive integers. Chain limits are read live from the provider at runtime. These values are the fallback used by budget tests and sizing checks when a live read is not available, and a test asserts them against the live values. ## Environment variables [#environment-variables] ### Command line and libraries [#command-line-and-libraries] | Variable | Required | Meaning | | -------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------- | | `CARDANO_SWAP_NETWORK` | When `--network` is omitted | `mainnet`, `preprod` or `preview`. There is no default. | | `CARDANO_SWAP_CONFIG_DIR` | No | Overrides where `.json` files are found. | | `CARDANO_SWAP_SECRETS_DIR` | No | Overrides where operator key material lives. Defaults to `secrets/` at the repository root. | | `CARDANO_SWAP_OPERATOR_MNEMONIC` | No | Supplies the operator wallet directly instead of reading the stored file. | | `KOIOS_BEARER_TOKEN` | No | Named by `providers.koios.bearerTokenEnv`. Raises the Koios rate limit. | | `BLOCKFROST_PROJECT_ID` | When Blockfrost is the provider | Named by `providers.blockfrost.projectIdEnv`. | | `PYTH_LAZER_API_KEY` | For a direct Lazer subscription | Named by `oracle.pyth.apiKeyEnv`. | `requireEnv` throws naming the variable when a required one is unset, and never returns an empty string. ### Web application [#web-application] | Variable | Required | Meaning | | --------------------------- | -------- | ----------------------------------------------------------------- | | `VITE_CARDANO_SWAP_NETWORK` | Yes | The network this deployment reads. Unset throws `WebConfigError`. | | `VITE_KOIOS_BEARER_TOKEN` | No | Raises the Koios rate limit. | Anything given to a `VITE_` variable is compiled into the browser bundle and is therefore public. For a deployment that needs a raised rate limit without publishing the token, put a proxy in front of the provider and point `providers.koios.baseUrl` at the proxy. ### Test only [#test-only] These gate live tests that spend or emit transactions. They are read by test files, never by shipped code. | Variable | Meaning | | ------------------------------------- | ------------------------------------------------------------------------------- | | `CARDANO_SWAP_WEB_SUBMIT` | Set to `1` to let the web live test submit. Otherwise it builds and signs only. | | `CARDANO_SWAP_HANDOVER_WINDOW_MS` | Overrides the submit window that test builds with. | | `CARDANO_SWAP_EMIT_SETTLEMENT_LOCK` | Writes a signed settlement lock transaction. Never submitted by the test. | | `CARDANO_SWAP_EMIT_SETTLEMENT_CLAIM` | As above, for a claim. | | `CARDANO_SWAP_EMIT_SETTLEMENT_REFUND` | As above, for a refund. | ## Related [#related]