Developer guide

Cardano

12 min read

A wallet on this platform can receive and send ada. Cardano is reached through a native adapter built on its own network primitives — EUTXO, fees paid in ada out of the transaction's inputs, and addresses derived from the hash of the public key — and an ada transfer is an Operation like any other: quoted, confirmed, settled and reconciled against the chain. See the Roadmap for which Cardano networks are currently available.

Project program reference supplied for this initiative: Cardano governance program.

EUTXO and assets

Cardano uses Extended UTXO. Transactions consume UTxOs and create outputs that may contain ada and native assets. The adapter therefore handles inputs, outputs, change, protocol parameters, fees, minimum ada requirements, validity intervals and multi-asset quantities.

Wallets and signing

A WalletProfile can include a Cardano ChainAccount, while cryptographic identity remains independent of EVM and Bitcoin. Cardano keys are Ed25519, not the secp256k1 of EVM and Bitcoin, so the key reference held by the Partner Signer Gateway declares its signature scheme and a reference of one scheme can never derive the key material of another.

An address is derived from the public key alone: the blake2b-224 hash of the raw Ed25519 key, behind a header byte that states the address type and the network, bech32-encoded (CIP-19). Nothing is written to a chain to obtain one, which is what lets an address be shown and funded before any transaction exists.

Every account has two keys, derived at roles 0 and 2 of one CIP-1852 account (m/1852'/1815'/0'/0/0 and m/1852'/1815'/0'/2/0) over a BIP32-Ed25519 tree: one that spends and one that stakes. The address published is the base address of both credentials, which is what an ordinary Cardano wallet hands out and the only kind its holder can ever delegate to a stake pool.

That choice cannot be deferred. A staking credential is part of what an address is, not a setting on it: an address that carries only a payment credential can never delegate, and giving its holder that ability later means giving them a different address and moving the ada. This deployment settled it before publishing an address anybody funded.

Declared limitation The key is derived from the deployment's own master secret, so a Cardano address issued here is not importable into Daedalus, Eternl, Lace or any other Cardano wallet today: the platform holds the key and signs on the account's behalf. The derivation path is now the standard one, so what stands between an account and a recovery phrase is the custody model rather than the shape of the tree.

Accounts provisioned before this change keep the enterprise address they were funded at, and the key that spends from it. They cannot delegate, and they cannot be converted: the address is the difference.

Staking and delegation

The address a wallet gets here can be delegated. It is a base address: it carries a payment credential and a staking credential, which is the only thing that makes an address on Cardano delegable at all. An address without the second one receives and spends exactly the same and can never be pointed at a stake pool.

That matters at the moment the address is created and not later, because the staking credential is part of what the address is. It cannot be added to an address that already exists: granting it means granting a different address, and the ada has to move.

Planned Delegating is not built yet. What exists is the address that permits it. Delegating also needs the staking key registered on chain with a certificate — a deposit of 2 ADA, refundable when it is deregistered — and a stake pool chosen. Two questions come before the code, and they are commercial rather than technical: whose rewards are they, the user's or the Partner's, and who picks the pool.

Accounts provisioned before this — enterprise addresses, payment credential only — keep the address they were funded at and cannot delegate.

Transfer flow

sequenceDiagram
    autonumber
    participant P as Partner backend
    participant API as B2B API
    participant OP as Operation worker
    participant A as Cardano adapter
    participant N as Cardano node/provider
    participant SG as Partner Signer Gateway
    participant R as Observer/Reconciler
    P->>API: Transfer ADA/native asset
    API->>OP: Operation + reserve
    OP->>A: Prepare transaction
    A->>N: Query UTxOs + protocol parameters
    N-->>A: UTxOs + parameters
    A->>A: Inputs, outputs, min-ada, fee, change, validity interval
    A->>SG: Sign transaction-body hash
    SG-->>A: Witness/signature
    A->>N: Submit transaction
    N-->>A: tx id
    R->>N: Observe inclusion/stability
    R->>OP: Reconcile UTxOs/assets/fee
    OP-->>P: Webhook / state

What each step does

Partner backend → API. The Partner asks to send ada or a native asset. This request states the intent; how the transaction is built is resolved further down.
API → operation worker. The Operation is persisted and the balance reserved. The same request repeated with the same idempotency key produces the same operation.
Worker → Cardano adapter. The adapter is where the rules of this family live, so EUTXO reaches the rest of the platform as an Operation like any other.
Adapter → node: UTxOs and protocol parameters. In EUTXO a transaction is built by choosing which unspent outputs to consume, so the adapter needs the account's outputs and the parameters in force: fee coefficients, minimum ada, transaction limits.
Node → adapter. The answer is the material the transaction is built from: which outputs exist, what each holds in ada and native assets, and the current parameters.
Adapter builds the transaction. Input selection, outputs, the minimum ada any output carrying tokens must hold, the fee, the change returning to the account, and the validity interval that bounds when it can be included.
Adapter → Partner Signer Gateway. What travels is the hash of the transaction body and the key reference of the Cardano family, which signs with Ed25519 and keeps its own keys and addresses.
Gateway → adapter: witness. The signature returns as a witness, which the adapter assembles with the body into the final transaction.
Adapter → node: submit. The node accepts the transaction into the network.
Node → adapter: tx id. The identifier says the transaction was admitted. Whether it was included is the next question.
Observer → node: inclusion and stability. A transaction can be included in a block that is still open to rollback, so the observer waits for the depth agreed for the operation.
Reconciler → worker. What settled is contrasted against what was recorded: which UTxOs were consumed, which were created, how much ada and which native assets each holds, and the fee actually paid.
Worker → Partner. The final state travels as a signed webhook, and the same result can be read from the Operation.

What a transfer costs, and who pays it

The fee is paid in ada, out of the transaction's own inputs. Nobody else can pay it without taking part in the transaction, so today the operation reports paidBy: "user" with the exact fee in lovelace.

What the network charges and what the network requires are two different things:

The fee of an ada transfer is around 0.168229 ADA, a few cents. It is computed from the size of the very transaction being submitted, so what gets reported is what the chain charged.
The floor, called min-ADA, is the least any output may hold: 0.969750 ADA for an output carrying ada alone, and 1.155080 ADA for one carrying a token. That floor stays with whoever receives it: it is value moving, and not a charge.

An amount below the floor makes the whole transaction invalid, so the quote refuses it before anything is signed. And the fee is accounted from the transaction that settled rather than from the quote that predicted it: it is real ada that left the wallet.

Every figure here was measured on Preprod. The protocol parameters belong to the network and can change; the adapter reads them from the node each time it builds a transaction.

Example: sending 10 ADA

An account holding 12 ADA sends 10 to an external address.

	Before	After
Your account	12 ADA	11.831771 ADA minus the 10 sent = 1.831771 ADA
The recipient	0	10 ADA
Network fee		0.168229 ADA, paid by the sender

For this transfer to exist at all, the account needs the amount plus the fee. An account holding exactly 10 ADA cannot send 10 ADA.

Example: emptying the account

With 3.49 ADA in the account there are two valid sends, and a band between them worth knowing about:

up to 2.351 ADA, the change stays above the floor and returns to your account;
3.321 ADA is "send everything": the account ends at zero, cleanly;
between those two values, the change would fall below the floor, cannot be an output of its own, and the network keeps it as fee.

That band is about 1.14 ADA wide and sits right below "send everything". The quote refuses an amount that lands there and offers the two valid ones: the largest amount that keeps change, and the send-everything amount.

Example: sending USDCx

Planned Transferring assets other than ada is planned; what follows is how the cost works once it is available.

A token never travels alone. The output carrying USDCx must also carry 1.155080 ADA attached: the sender provides it and the recipient receives it along with the token. And when you send part of your balance, your own change carries the token too, so it pays the floor a second time.

An account holding 10 USDCx sending its whole balance:

	Before	After
Your account	10 USDCx + 1.322341 ADA	0
The recipient	0	10 USDCx + 1.155080 ADA
Network fee		0.172013 ADA, paid by the sender

The same account sending half needs 2.482173 ADA on top of the token, because the floor is paid twice: once for the output that travels and once for the change that keeps the remaining 5 USDCx.

What to remember: moving a Cardano token takes ada. A USDCx balance with no ada stays where it is, which is why what follows exists.

The fee subsidy

Planned Today an account holding no ada cannot send, whatever else it holds. The way out is for the Partner to add an input of its own and co-sign the transaction: on Cardano a transaction may spend inputs from several addresses and only asks for a signature from each owner, so adding the Partner's input is one more signature and no new contract.

How it works once it is built:

The Partner provides it. The ada comes out of a Partner account, funded and monitored like any other platform account, with its own low-balance warning.
Who ends up absorbing it is configuration. It can be recovered from the user, appearing in the quote breakdown as part of what is charged, or absorbed by the Partner and reported as a cost of the operation.
When it applies is configuration. Always on Cardano, or only when the sender's account falls short of the amount plus the fee.
It is capped per operation, as a percentage of the value being sent, and capped per user over a period. A small send earns a small subsidy: many minimum-sized transfers therefore cannot become a way to drain the Partner's funding.
The subsidy of an operation never exceeds what that operation charges. No transfer costs the Partner more than it earns.
When the cap is used up or the account runs dry, the quote is refused and nothing is signed. The operation fails before it exists rather than halfway through.

What changes for the sender: with the subsidy on, the minimum to send ada drops to the amount being sent, and moving a token stops requiring ada of your own.

See Costs and platform accounts for what each operation cost and who it was charged to.

An `addr_test1…` does not name which test network

Cardano uses one network id for all of its test networks, so the same address is valid on Preprod, Preview and the legacy testnet, and no validation of the address can tell them apart. What decides the network is the deployment's catalog and its provider credential, which is issued for one network and refuses any other. Send test ada from a faucet of the same network your deployment is configured for; an address that looks right is not evidence that it is.

References

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

Native EUTXO adapter — The adapter builds Cardano transactions in their own shape: inputs, outputs, witnesses, change, validity interval and the minimum amount of ADA every output has to carry. It reads the protocol parameters from the node to calculate the fee.
Ed25519 signing at the gateway boundary — Cardano signs with the Ed25519 curve. The Partner Signer Gateway carries that curve alongside the one EVM and Bitcoin use, holds the Cardano key references, and exposes the raw public key that the payment credential hashes. A Cardano key reference never derives the key of another chain for the same wallet.
Addresses derived with no on-chain write — A Cardano address is derived from the key hash alone. It can be shown to the user and receive funds as soon as the wallet is created, without sending any transaction first.
ADA transfers — Sending ADA, choosing which UTXOs to spend and building the change output. The fee is paid in ADA taken from the transaction's own inputs, is measured from the transaction that settled, and is accounted as what it is: ADA that left the wallet.
Fee subsidy for an account with no ADA — An account with no ADA cannot send, because the fee comes out of the transaction's own inputs. The platform adds an input of its own and co-signs, so a user who was only ever sent tokens can still move them.
Cardano observation and reconciliation — A component watches the chain for transactions that pay into a wallet, and checks that the amounts and assets that settled match what was recorded. The result updates the ledger and produces the corresponding event.
An address that can be delegated, derived by CIP-1852 — Every account has a payment key and a staking key, at roles 0 and 2 of one CIP-1852 account, and the address published carries both credentials. That is what makes an address on Cardano delegable at all: the staking credential is part of what the address is, so it cannot be added to one that already exists.
Native assets, and delegating to a stake pool — Transferring assets other than ADA in the same transaction, and delegating: registering the staking key on chain with its certificate — a refundable deposit of 2 ADA — and choosing a pool. Two commercial questions come first: whose the rewards are, and who picks the pool.
Preprod — Cardano available on its public test network from the API, the SDK and the Sandbox. A Partner can send and receive ADA with no funds at risk, and check every transaction in a public explorer.
Mainnet — Cardano on the network where the funds are real. It depends on the custody, security and operational capabilities listed in the other areas being finished first.