Create and register a wallet

Create a guarded wallet the owner holds, then register it with your Node Token. Registration attaches the mandate Exchain enforces on every payment.

What every guarded wallet hasCopy Anchor Link

CardanoCopy Anchor Link

Mint parametersCopy Anchor Link

These are part of the address. Changing any of them means a new wallet.

Use exactly Exchain's keys and 3. The contract does not check quorum_threshold: 0 or below removes Exchain from the wallet permanently, and a value above the quorum's weight blocks agent spends (the owner can still sweep). Registration does not read the chain, so Exchain cannot catch either mistake for you.

The datumCopy Anchor Link

The wallet UTxO carries an inline datum. The owner can rewrite it later: Owner controls.

Register a Cardano walletCopy Anchor Link

POST /v1/wallets with your Node Token. Every address must carry the network's prefix (addr or addr_test). A full example is in the Quickstart.

Send exactly one of governedAsset with constitution, or governedAssets[]. Hydra keys: Head trust.

Registration does not check that the state token exists at the address, the datum, or that the address's script parameters contain the declared owner, quorum and threshold. These surface at the first co-sign, as utxo_unknown or a transaction-rule refusal.

Deposits use the Deposit redeemer, signed by the agent or the owner, with no Exchain call. Withdrawals: Owner controls.

Seller gatesCopy Anchor Link

List entries are sellerVkeyHash:<56 hex> or agent identifiers.

Several assetsCopy Anchor Link

Send governedAssets[] (1 to 16) instead of governedAsset and constitution. Each asset has its own mandate, and each payment counts only against its asset.

{
  "governedAssets": [
    { "id": "lovelace", "decimals": 6,
      "constitution": { "params": { "perTxCap": "50000000", "daily": "1000000000", "perSeller": "200000000",
                                    "perAgent": "500000000", "envelope": "50000000000", "burstPerMinute": 10 } } },
    { "id": "6ba199f81440944474fb29139bc7a0f736f70615bb26cb7b20d3d6fd.0014df10745553444378", "decimals": 6,
      "constitution": { "params": { "perTxCap": "50000000", "daily": "1000000000", "perSeller": "200000000",
                                    "perAgent": "500000000", "envelope": "50000000000", "burstPerMinute": 10 } } }
  ]
}

A token output may carry up to 6 ADA. When the wallet also governs ADA, that ADA counts against the ADA mandate's daily, perSeller, perAgent and envelope, not against perTxCap or burstPerMinute.

EVM chainsCopy Anchor Link

The guarded wallet is a stock SafeL2 1.4.1 holding one or more of its chain's listed stablecoins: Assets. Exchain deploys it and pays the gas. Its owners, module and contracts: The guarded Safe. One registration serves both direct and x402 payments.

Bind the ownerCopy Anchor Link

If your node belongs to a console account, bind the owner address in the console first, with an EIP-191 signature from that address. Otherwise registration returns 403 owner_unbound.

Register a SafeCopy Anchor Link

{
  "nodeId": "node_1",
  "orgId": "org_acme",
  "agentAddress": "0xAgent…",
  "ownerAddress": "0xOwner…",
  "governedAsset": { "id": "eip155:84532/erc20:0x036cbd53842c5426634e7929541ec2318f3dcf7e", "decimals": 6 },
  "constitution": {
    "params": { "perTxCap": "1000000", "daily": "500000000", "perSeller": "50000000",
                "perAgent": "250000000", "envelope": "20000000000", "burstPerMinute": 60 }
  }
}

Exchain guarded Safe
Safe: 0x…
Chain: eip155:84532
Agent: 0xAgent…
Owner module: 0xOwner…

sellers and unsignedSellers bind payments to signed seller offers: Seller binding.

Fund only the registered Safe. Fund only the walletAddress returned at registration. The Safe balance is the most the agent can ever spend, and only the owner module can withdraw it.

Shadow modeCopy Anchor Link

shadow: true registers the agent's own address, with no Safe and no owner. Exchain decides and journals each payment, but the agent signs alone and pays no fees. Use it as a dry run to evaluate a mandate.

Registration errorsCopy Anchor Link

Registration responseCopy Anchor Link

201 Created returns:

The top-level constitutionId, mandateEnglish and mandateRules are those of the first governed asset. An identical repeat returns 200 with the same walletId. A different body for the same wallet returns 409 wallet_exists. To change a mandate: Changing a mandate. What the owner can do without Exchain: Owner controls.