{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Masumi Payment Service API", "description": "A comprehensive payment service API for the Masumi ecosystem, providing secure payment processing, agent registry management, and wallet operations." }, "servers": [ { "url": "./../api/v1/" } ], "components": { "securitySchemes": { "API-Key": { "type": "apiKey", "in": "header", "name": "token", "description": "API key authentication via header (token)" } }, "schemas": { "APIKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the API key" }, "token": { "type": "string", "description": "The API key token" }, "permission": { "type": "string", "enum": [ "Read", "ReadAndPay", "Admin" ], "description": "Permission level of the API key DEPRECATED (computed from flags for backward compatibility)" }, "canRead": { "type": "boolean", "description": "Whether this API key can access read endpoints" }, "canPay": { "type": "boolean", "description": "Whether this API key can access payment/purchase endpoints" }, "canAdmin": { "type": "boolean", "description": "Whether this API key has admin access" }, "usageLimited": { "type": "boolean", "description": "Whether the API key has usage limits" }, "NetworkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "description": "List of Cardano networks this API key is allowed to access" }, "ChainIdLimit": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "CAIP-2 chain identifiers this API key is allowed to access" }, "RemainingUsageCredits": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" }, "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" } }, "required": [ "unit", "amount" ] }, "description": "Remaining usage credits for this API key" }, "status": { "type": "string", "enum": [ "Active", "Revoked" ], "description": "Current status of the API key" }, "walletScopeEnabled": { "type": "boolean", "description": "Whether wallet scope filtering is enabled for this API key" }, "WalletScopes": { "type": "array", "items": { "type": "object", "properties": { "hotWalletId": { "type": "string", "description": "ID of the hot wallet in scope" } }, "required": [ "hotWalletId" ] }, "description": "List of hot wallets this API key is scoped to" }, "x402WalletScopeEnabled": { "type": "boolean", "description": "Whether managed EVM wallet scope filtering is enabled for this API key" }, "X402WalletScopes": { "type": "array", "items": { "type": "object", "properties": { "evmWalletId": { "type": "string", "description": "ID of the managed EVM wallet in scope" } }, "required": [ "evmWalletId" ] }, "description": "Managed EVM wallets this API key is scoped to. The key additionally always reaches wallets it created itself." } }, "required": [ "id", "token", "permission", "canRead", "canPay", "canAdmin", "usageLimited", "NetworkLimit", "ChainIdLimit", "RemainingUsageCredits", "status", "walletScopeEnabled", "WalletScopes", "x402WalletScopeEnabled", "X402WalletScopes" ] }, "Wallet": { "type": "object", "properties": { "Secret": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the secret was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the secret was last updated" }, "mnemonic": { "type": "string", "description": "Decrypted 24-word mnemonic phrase for the wallet" } }, "required": [ "createdAt", "updatedAt", "mnemonic" ], "description": "Wallet secret (mnemonic). Only included if includeSecret is true" }, "PendingTransaction": { "type": "object", "nullable": true, "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the pending transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the pending transaction was last updated" }, "hash": { "type": "string", "nullable": true, "description": "Transaction hash of the pending transaction. Null if not yet submitted" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the pending transaction was last checked. Null if never checked" } }, "required": [ "createdAt", "updatedAt", "hash", "lastCheckedAt" ], "description": "Pending transaction for this wallet. Null if no transaction is pending" }, "note": { "type": "string", "nullable": true, "description": "Optional note about this wallet. Null if not set" }, "walletVkey": { "type": "string", "description": "Payment key hash of the wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the wallet" }, "collectionAddress": { "type": "string", "nullable": true, "description": "Collection address for this wallet. Null if not set" }, "LowBalanceSummary": { "type": "object", "properties": { "isLow": { "type": "boolean", "description": "Whether any enabled low-balance rule for this wallet is currently below threshold" }, "lowRuleCount": { "type": "integer", "minimum": 0, "description": "How many enabled rules for this wallet are currently in low state" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp of the latest low-balance evaluation across this wallet rules. Null if never checked" } }, "required": [ "isLow", "lowRuleCount", "lastCheckedAt" ], "description": "Aggregated low-balance state for this wallet" }, "LowBalanceRules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the low-balance rule" }, "assetUnit": { "type": "string", "description": "Raw on-chain asset unit, for example lovelace or a full policy+asset identifier" }, "thresholdAmount": { "type": "string", "description": "Threshold in raw on-chain units used to determine low balance" }, "enabled": { "type": "boolean", "description": "Whether the rule is active (fires the low-balance alert/webhook)" }, "topupEnabled": { "type": "boolean", "description": "Whether crossing the threshold also auto-tops-up this wallet from a fund wallet on its source" }, "topupAmount": { "type": "string", "nullable": true, "description": "Amount to top up per trigger, in raw on-chain units. Null when auto top-up is off" }, "status": { "type": "string", "enum": [ "Unknown", "Healthy", "Low" ], "description": "Current deduped state of the rule" }, "lastKnownAmount": { "type": "string", "nullable": true, "description": "Last observed balance for this asset in raw on-chain units. Null if never checked" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the rule was last evaluated. Null if never checked" }, "lastAlertedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the wallet last entered low balance for this rule. Null if never alerted" } }, "required": [ "id", "assetUnit", "thresholdAmount", "enabled", "topupEnabled", "topupAmount", "status", "lastKnownAmount", "lastCheckedAt", "lastAlertedAt" ] }, "description": "Configured low-balance rules for this wallet, including current deduped state" } }, "required": [ "PendingTransaction", "note", "walletVkey", "walletAddress", "collectionAddress", "LowBalanceSummary", "LowBalanceRules" ] }, "WalletListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the wallet" }, "paymentSourceId": { "type": "string", "description": "Id of the payment source this wallet belongs to" }, "type": { "type": "string", "enum": [ "Selling", "Purchasing", "Funding" ], "description": "Whether this is a Selling (seller side), Purchasing (buyer side) or Funding (treasury that tops up the other two) wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the wallet" }, "collectionAddress": { "type": "string", "nullable": true, "description": "Optional collection address for this wallet. Null if not set" }, "note": { "type": "string", "nullable": true, "description": "Optional note about this wallet. Null if not set" }, "LowBalanceSummary": { "type": "object", "properties": { "isLow": { "type": "boolean", "description": "Whether any enabled low-balance rule for this wallet is currently below threshold" }, "lowRuleCount": { "type": "integer", "minimum": 0, "description": "How many enabled rules for this wallet are currently in low state" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp of the latest low-balance evaluation across this wallet rules. Null if never checked" } }, "required": [ "isLow", "lowRuleCount", "lastCheckedAt" ], "description": "Aggregated low-balance status for the wallet" } }, "required": [ "id", "paymentSourceId", "type", "walletVkey", "walletAddress", "collectionAddress", "note", "LowBalanceSummary" ] }, "GeneratedWalletSecret": { "type": "object", "properties": { "walletMnemonic": { "type": "string", "description": "24-word mnemonic phrase for the newly generated wallet. IMPORTANT: Backup this mnemonic securely" }, "walletAddress": { "type": "string", "description": "Cardano address of the newly generated wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the newly generated wallet" } }, "required": [ "walletMnemonic", "walletAddress", "walletVkey" ] }, "WalletFundTransfer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the fund transfer" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the fund transfer" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash. Null until submitted to blockchain" }, "toAddress": { "type": "string", "description": "Destination Cardano address" }, "lovelaceAmount": { "type": "string", "description": "Amount transferred in lovelace" }, "assets": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "quantity": { "type": "string" } }, "required": [ "unit", "quantity" ] }, "description": "Additional native assets included in this transfer. Null if lovelace-only." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transfer was requested" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transfer was last updated" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the blockchain was last polled for confirmation" }, "errorNote": { "type": "string", "nullable": true, "description": "Error message if the transfer failed" } }, "required": [ "id", "status", "txHash", "toAddress", "lovelaceAmount", "assets", "createdAt", "updatedAt", "lastCheckedAt", "errorNote" ] }, "WalletFundTransferList": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/WalletFundTransfer" }, "description": "List of fund transfers" } }, "required": [ "transfers" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the payment" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being paid" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the payment was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "requestedById": { "type": "string", "description": "ID of the API key that created this payment" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "inputHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the input data for the payment (hex string)" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the payment on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Caller-specified layer override recorded on this payment. \"L1\" or \"Hydra\", or null for automatic routing (Hydra if available, else L1)." }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ], "description": "Next action required for this payment" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result to be submitted (hex string). Null if not applicable" } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ], "description": "Next action required for this payment" }, "ActionHistory": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the action" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was last updated" }, "submittedTxHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ], "description": "Next action required for this payment" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result to be submitted (hex string). Null if not applicable" } }, "required": [ "id", "createdAt", "updatedAt", "submittedTxHash", "requestedAction", "errorType", "errorNote", "resultHash" ], "description": "Next action required for this payment" }, "description": "Historical list of all actions for this payment. Null if includeHistory is false" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "fees": { "type": "string", "nullable": true }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "fees", "blockHeight", "blockTime", "txHash", "status", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this payment. Null if no transaction in progress" }, "TransactionHistory": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status", "fees", "blockHeight", "blockTime", "previousOnChainState", "newOnChainState", "confirmations" ] }, "description": "Historical list of all transactions for this payment. Null if includeHistory is false" }, "RequestedFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the seller" }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the buyer (refunds)" }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment source" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network (Mainnet, Preprod, or Preview)" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Payment source type for adapter dispatch" }, "smartContractAddress": { "type": "string", "description": "Address of the smart contract managing this payment" }, "policyId": { "type": "string", "nullable": true, "description": "Policy ID for the agent registry NFTs. Null if not applicable" } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ], "description": "Payment source configuration for this payment" }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the buyer wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the buyer wallet" } }, "required": [ "id", "walletVkey" ], "description": "Buyer wallet information. Null if buyer has not yet submitted payment" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this payment. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the payment for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "externalDisputeUnlockTime", "requestedById", "resultHash", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "nextActionOrOnChainStateOrResultLastChangedAt", "inputHash", "totalBuyerCardanoFees", "totalSellerCardanoFees", "cooldownTime", "cooldownTimeOtherParty", "onChainState", "forceLayer", "NextAction", "ActionHistory", "CurrentTransaction", "TransactionHistory", "RequestedFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "BuyerWallet", "SmartContractWallet", "metadata" ] }, "Purchase": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the purchase" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the purchase" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being purchased" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the purchase was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "requestedById": { "type": "string", "description": "ID of the API key that created this purchase" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the purchase on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Buyer-specified layer override recorded on this purchase. \"L1\" or \"Hydra\", or null for automatic routing." }, "paymentForceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Seller-specified layer override. V2 authenticates it with the blockchain identifier signature; V1 can only carry redundant \"L1\". Null means automatic routing." }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "inputHash": { "type": "string", "description": "SHA256 hash of the input data for the purchase (hex string)" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated", "AuthorizeWithdrawalRequested", "AuthorizeWithdrawalInitiated" ], "description": "Next action required for this purchase" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" } }, "required": [ "requestedAction", "errorType", "errorNote" ], "description": "Next action required for this purchase" }, "ActionHistory": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the action" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the action was last updated" }, "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated", "AuthorizeWithdrawalRequested", "AuthorizeWithdrawalInitiated" ], "description": "Next action required for this purchase" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" } }, "required": [ "id", "createdAt", "updatedAt", "requestedAction", "errorType", "errorNote" ], "description": "Next action required for this purchase" }, "description": "Historical list of all actions for this purchase. Null if includeHistory is false" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status", "fees", "blockHeight", "blockTime", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this purchase. Null if no transaction in progress" }, "TransactionHistory": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status", "fees", "blockHeight", "blockTime", "previousOnChainState", "newOnChainState", "confirmations" ] }, "description": "Historical list of all transactions for this purchase" }, "PaidFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the seller wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the seller wallet" } }, "required": [ "id", "walletVkey" ], "description": "Seller wallet information. Null if not set" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this purchase. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the purchase for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "totalBuyerCardanoFees", "totalSellerCardanoFees", "nextActionOrOnChainStateOrResultLastChangedAt", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "requestedById", "onChainState", "forceLayer", "paymentForceLayer", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "cooldownTime", "cooldownTimeOtherParty", "inputHash", "resultHash", "NextAction", "ActionHistory", "CurrentTransaction", "TransactionHistory", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] }, "AgentMetadata": { "type": "object", "properties": { "policyId": { "type": "string", "description": "Policy ID of the agent registry NFT" }, "assetName": { "type": "string", "description": "Asset name of the agent registry NFT" }, "agentIdentifier": { "type": "string", "description": "Full agent identifier (policy ID + asset name)" }, "Metadata": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the agent" }, "description": { "type": "string", "nullable": true, "maxLength": 250, "description": "Description of the agent. Null if not provided" }, "apiBaseUrl": { "type": "string", "maxLength": 250, "description": "Primary interaction URL: MIP api base, x402 manifest URL, or OpenAPI spec URL" }, "type": { "type": "string", "enum": [ "Standard", "OpenApi", "X402", "A2A" ], "description": "Registry entry type when encoded on-chain" }, "openApiSpecUrl": { "type": "string", "maxLength": 250, "description": "OpenAPI spec URL for OpenApi registry entries" }, "x402ResourcesUrl": { "type": "string", "maxLength": 250, "description": "x402 manifest URL for X402 registry entries" }, "a2aAgentCardUrl": { "type": "string", "maxLength": 250, "description": "Agent Card URL for A2A registry entries" }, "a2aProtocolVersions": { "type": "array", "items": { "type": "string" }, "description": "Declared A2A protocol versions" }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60, "description": "Name of the example output" }, "mimeType": { "type": "string", "maxLength": 60, "description": "MIME type of the example output (e.g., image/png, text/plain)" }, "url": { "type": "string", "maxLength": 250, "description": "URL to the example output" } }, "required": [ "name", "mimeType", "url" ] }, "maxItems": 25, "description": "List of example outputs from the agent" }, "Tags": { "type": "array", "items": { "type": "string", "maxLength": 250 }, "description": "List of tags categorizing the agent" }, "Capability": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "maxLength": 250, "description": "Name of the AI model/capability. Null if not provided" }, "version": { "type": "string", "nullable": true, "maxLength": 250, "description": "Version of the AI model/capability. Null if not provided" } }, "description": "Information about the AI model and version used by the agent. Null if not provided" }, "Author": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the agent author" }, "contactEmail": { "type": "string", "nullable": true, "maxLength": 250, "description": "Contact email of the author. Null if not provided" }, "contactOther": { "type": "string", "nullable": true, "maxLength": 250, "description": "Other contact information for the author. Null if not provided" }, "organization": { "type": "string", "nullable": true, "maxLength": 250, "description": "Organization of the author. Null if not provided" } }, "required": [ "name" ], "description": "Author information for the agent" }, "Legal": { "type": "object", "nullable": true, "properties": { "privacyPolicy": { "type": "string", "nullable": true, "maxLength": 250, "description": "URL to the privacy policy. Null if not provided" }, "terms": { "type": "string", "nullable": true, "maxLength": 250, "description": "URL to the terms of service. Null if not provided" }, "other": { "type": "string", "nullable": true, "maxLength": 250, "description": "Other legal information. Null if not provided" } }, "description": "Legal information about the agent. Null if not provided" }, "AgentPricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "Pricing type for the agent (Fixed or Free)" }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" }, "unit": { "type": "string", "maxLength": 250, "description": "Asset policy id + asset name concatenated. Uses an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" } }, "required": [ "amount", "unit" ] }, "minItems": 1, "description": "List of assets and amounts for fixed pricing" } }, "required": [ "pricingType", "Pricing" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "Pricing type for the agent (Free)" } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "Pricing type for the agent (Dynamic)" } }, "required": [ "pricingType" ] }, { "nullable": true } ], "description": "V1 legacy pricing. Null for V2 metadata, which prices each source independently." }, "image": { "type": "string", "maxLength": 250, "description": "URL to the agent image/logo" }, "metadataVersion": { "type": "integer", "minimum": 1, "maximum": 2, "description": "Version of the metadata schema" }, "supportedPaymentSources": { "type": "array", "nullable": true, "items": { "anyOf": [ { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "Cardano" ], "description": "The blockchain this payment source is available on" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network this payment source is available on" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "The configured payment source type" }, "address": { "type": "string", "maxLength": 250, "description": "The escrow smart contract address for this payment source" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "paymentSourceType", "address", "pricing" ] }, { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "EVM" ], "description": "The chain family used by standard x402" }, "network": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 EVM network id, for example eip155:8453" }, "paymentSourceType": { "type": "string", "nullable": true, "enum": [ "Web3CardanoV1", "Web3CardanoV2", null ], "description": "The configured payment source type" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Alias for payTo, kept for existing payment-source shape" }, "scheme": { "type": "string", "enum": [ "Exact" ], "description": "x402 payment scheme" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address receiving the x402 payment" }, "resource": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional absolute resource URL this x402 option protects" }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional x402 metadata" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "scheme", "payTo", "pricing" ] } ] }, "minItems": 1, "maxItems": 25, "description": "Payment sources advertised by this registry entry. Null for legacy metadata." }, "verifications": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "method": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Verification method discriminator, e.g. \"KERI-ACDC\"" }, "schemaVersion": { "type": "string", "maxLength": 16, "description": "Version of this verification block" }, "issuer": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuer KERI AID (ACDC sad.i) — the root trust anchor" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the issuer KEL (key state) for signature verification" } }, "required": [ "aid", "oobi" ], "description": "Credential issuer identity" }, "schema": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential schema SAID (ACDC sad.s)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the JSON schema; a verifier checks its hash equals said" } }, "required": [ "said", "oobi" ], "description": "Credential schema — the ACDC structure definition" }, "credential": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential SAID (ACDC sad.d)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI/endpoint serving the signed ACDC; a verifier checks its hash equals said" }, "registry": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential status registry / TEL SAID (ACDC sad.ri) for independent revocation checks" } }, "required": [ "said", "oobi" ], "description": "The verifiable credential (ACDC)" }, "holder": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuee/holder KERI AID (ACDC sad.a.i)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the holder KEL" } }, "required": [ "aid", "oobi" ], "description": "Credential holder/issuee identity" }, "baseUrl": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional witness/KERIA resolver root for live key-state (\"verify at time T\") and TEL queries" } }, "required": [ "method", "issuer", "schema", "credential", "holder" ] }, "maxItems": 10, "description": "KERI/Veridian verification claims advertised by this registry entry. Null when none." } }, "required": [ "name", "apiBaseUrl", "ExampleOutputs", "Tags", "Author", "AgentPricing", "image", "metadataVersion", "supportedPaymentSources", "verifications" ], "description": "On-chain metadata for the agent" } }, "required": [ "policyId", "assetName", "agentIdentifier", "Metadata" ] }, "AgentIdentifierMetadata": { "type": "object", "properties": { "policyId": { "type": "string", "description": "Policy ID of the agent registry NFT" }, "assetName": { "type": "string", "description": "Asset name of the agent registry NFT" }, "agentIdentifier": { "type": "string", "description": "Full agent identifier (policy ID + asset name)" }, "Metadata": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the agent" }, "description": { "type": "string", "nullable": true, "maxLength": 250, "description": "Description of the agent. Null if not provided" }, "apiBaseUrl": { "type": "string", "maxLength": 250, "description": "Primary interaction URL: MIP api base, x402 manifest URL, or OpenAPI spec URL" }, "type": { "type": "string", "enum": [ "Standard", "OpenApi", "X402", "A2A" ], "description": "Registry entry type when encoded on-chain" }, "openApiSpecUrl": { "type": "string", "maxLength": 250, "description": "OpenAPI spec URL for OpenApi registry entries" }, "x402ResourcesUrl": { "type": "string", "maxLength": 250, "description": "x402 manifest URL for X402 registry entries" }, "a2aAgentCardUrl": { "type": "string", "maxLength": 250, "description": "Agent Card URL for A2A registry entries" }, "a2aProtocolVersions": { "type": "array", "items": { "type": "string" }, "description": "Declared A2A protocol versions" }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60, "description": "Name of the example output" }, "mimeType": { "type": "string", "maxLength": 60, "description": "MIME type of the example output (e.g., image/png, text/plain)" }, "url": { "type": "string", "maxLength": 250, "description": "URL to the example output" } }, "required": [ "name", "mimeType", "url" ] }, "maxItems": 25, "description": "List of example outputs from the agent" }, "Tags": { "type": "array", "items": { "type": "string", "maxLength": 250 }, "description": "List of tags categorizing the agent" }, "Capability": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "maxLength": 250, "description": "Name of the AI model/capability. Null if not provided" }, "version": { "type": "string", "nullable": true, "maxLength": 250, "description": "Version of the AI model/capability. Null if not provided" } }, "description": "Information about the AI model and version used by the agent. Null if not provided" }, "Author": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the agent author" }, "contactEmail": { "type": "string", "nullable": true, "maxLength": 250, "description": "Contact email of the author. Null if not provided" }, "contactOther": { "type": "string", "nullable": true, "maxLength": 250, "description": "Other contact information for the author. Null if not provided" }, "organization": { "type": "string", "nullable": true, "maxLength": 250, "description": "Organization of the author. Null if not provided" } }, "required": [ "name" ], "description": "Author information for the agent" }, "Legal": { "type": "object", "nullable": true, "properties": { "privacyPolicy": { "type": "string", "nullable": true, "maxLength": 250, "description": "URL to the privacy policy. Null if not provided" }, "terms": { "type": "string", "nullable": true, "maxLength": 250, "description": "URL to the terms of service. Null if not provided" }, "other": { "type": "string", "nullable": true, "maxLength": 250, "description": "Other legal information. Null if not provided" } }, "description": "Legal information about the agent. Null if not provided" }, "AgentPricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "Pricing type for the agent (Fixed)" }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" }, "unit": { "type": "string", "maxLength": 250, "description": "Asset policy id + asset name concatenated. Uses an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" } }, "required": [ "amount", "unit" ] }, "minItems": 1, "description": "List of assets and amounts for fixed pricing" } }, "required": [ "pricingType", "Pricing" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "Pricing type for the agent (Free)" } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "Pricing type for the agent (Dynamic). Amounts are provided per payment/purchase request" } }, "required": [ "pricingType" ] }, { "nullable": true } ], "description": "V1 legacy pricing. Null for V2 metadata, which prices each source independently." }, "image": { "type": "string", "maxLength": 250, "description": "URL to the agent image/logo" }, "metadataVersion": { "type": "integer", "minimum": 1, "maximum": 2, "description": "Version of the metadata schema" }, "supportedPaymentSources": { "type": "array", "nullable": true, "items": { "anyOf": [ { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "Cardano" ], "description": "The blockchain this payment source is available on" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network this payment source is available on" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "The configured payment source type" }, "address": { "type": "string", "maxLength": 250, "description": "The escrow smart contract address for this payment source" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "paymentSourceType", "address", "pricing" ] }, { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "EVM" ], "description": "The chain family used by standard x402" }, "network": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 EVM network id, for example eip155:8453" }, "paymentSourceType": { "type": "string", "nullable": true, "enum": [ "Web3CardanoV1", "Web3CardanoV2", null ], "description": "The configured payment source type" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Alias for payTo, kept for existing payment-source shape" }, "scheme": { "type": "string", "enum": [ "Exact" ], "description": "x402 payment scheme" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address receiving the x402 payment" }, "resource": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional absolute resource URL this x402 option protects" }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional x402 metadata" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "scheme", "payTo", "pricing" ] } ] }, "minItems": 1, "maxItems": 25, "description": "Payment sources advertised by this registry entry. Null for legacy metadata." }, "verifications": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "method": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Verification method discriminator, e.g. \"KERI-ACDC\"" }, "schemaVersion": { "type": "string", "maxLength": 16, "description": "Version of this verification block" }, "issuer": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuer KERI AID (ACDC sad.i) — the root trust anchor" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the issuer KEL (key state) for signature verification" } }, "required": [ "aid", "oobi" ], "description": "Credential issuer identity" }, "schema": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential schema SAID (ACDC sad.s)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the JSON schema; a verifier checks its hash equals said" } }, "required": [ "said", "oobi" ], "description": "Credential schema — the ACDC structure definition" }, "credential": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential SAID (ACDC sad.d)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI/endpoint serving the signed ACDC; a verifier checks its hash equals said" }, "registry": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential status registry / TEL SAID (ACDC sad.ri) for independent revocation checks" } }, "required": [ "said", "oobi" ], "description": "The verifiable credential (ACDC)" }, "holder": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuee/holder KERI AID (ACDC sad.a.i)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the holder KEL" } }, "required": [ "aid", "oobi" ], "description": "Credential holder/issuee identity" }, "baseUrl": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional witness/KERIA resolver root for live key-state (\"verify at time T\") and TEL queries" } }, "required": [ "method", "issuer", "schema", "credential", "holder" ] }, "maxItems": 10, "description": "KERI/Veridian verification claims advertised by this registry entry. Null when none." } }, "required": [ "name", "apiBaseUrl", "ExampleOutputs", "Tags", "Author", "AgentPricing", "image", "metadataVersion", "supportedPaymentSources", "verifications" ], "description": "On-chain metadata for the agent" } }, "required": [ "policyId", "assetName", "agentIdentifier", "Metadata" ] }, "RegistryListEntry": { "allOf": [ { "$ref": "#/components/schemas/RegistryEntry" }, { "type": "object", "properties": { "supportedPaymentSources": { "type": "array", "nullable": true, "items": { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "Cardano" ], "description": "The blockchain this payment source is available on" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network this payment source is available on" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "The configured payment source type" }, "address": { "type": "string", "maxLength": 250, "description": "The escrow smart contract address for this payment source" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "paymentSourceType", "address", "pricing" ] }, { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "EVM" ], "description": "The chain family used by standard x402" }, "network": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 EVM network id, for example eip155:8453" }, "paymentSourceType": { "type": "string", "nullable": true, "enum": [ "Web3CardanoV1", "Web3CardanoV2", null ], "description": "The configured payment source type" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Alias for payTo, kept for existing payment-source shape" }, "scheme": { "type": "string", "enum": [ "Exact" ], "description": "x402 payment scheme" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address receiving the x402 payment" }, "resource": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional absolute resource URL this x402 option protects" }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional x402 metadata" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "scheme", "payTo", "pricing" ] } ] }, { "type": "object", "properties": { "id": { "type": "string", "description": "Payment-node source row ID for x402 verify/settle. May change when sources are replaced." } }, "required": [ "id" ] } ] }, "minItems": 1, "maxItems": 25 } } } ] }, "RegistryEntry": { "type": "object", "properties": { "error": { "type": "string", "nullable": true, "description": "Error message if registration failed. Null if no error" }, "id": { "type": "string", "description": "Unique identifier for the registry request" }, "name": { "type": "string", "description": "Name of the agent" }, "description": { "type": "string", "nullable": true, "description": "Description of the agent. Null if not provided" }, "type": { "type": "string", "enum": [ "Standard", "OpenApi", "X402", "A2A" ], "description": "The agent access model. Standard for legacy/untyped entries; OpenApi, X402, or A2A otherwise" }, "apiBaseUrl": { "type": "string", "nullable": true, "description": "Base URL of the agent API for interactions. Null for OpenApi/X402 agents; required for A2A agents alongside a2aAgentCardUrl" }, "openApiSpecUrl": { "type": "string", "nullable": true, "description": "URL to the agent OpenAPI specification document. Null unless the agent is OpenApi-type" }, "x402ResourcesUrl": { "type": "string", "nullable": true, "description": "URL to the agent x402 resource manifest JSON. Null unless the agent is X402-type" }, "a2aAgentCardUrl": { "type": "string", "nullable": true, "description": "URL to the agent MIP-002 Agent Card JSON. Null unless the agent is A2A-type" }, "a2aProtocolVersions": { "type": "array", "items": { "type": "string" }, "description": "A2A protocol versions this agent declares support for. Empty for non-A2A agents" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Which payment source version (V1/V2) this registry entry is registered under" }, "Capability": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Name of the AI model/capability. Null if not provided" }, "version": { "type": "string", "nullable": true, "description": "Version of the AI model/capability. Null if not provided" } }, "required": [ "name", "version" ], "description": "Information about the AI model and version used by the agent" }, "Author": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent author" }, "contactEmail": { "type": "string", "nullable": true, "description": "Contact email of the author. Null if not provided" }, "contactOther": { "type": "string", "nullable": true, "description": "Other contact information for the author. Null if not provided" }, "organization": { "type": "string", "nullable": true, "description": "Organization of the author. Null if not provided" } }, "required": [ "name", "contactEmail", "contactOther", "organization" ], "description": "Author information for the agent" }, "Legal": { "type": "object", "properties": { "privacyPolicy": { "type": "string", "nullable": true, "description": "URL to the privacy policy. Null if not provided" }, "terms": { "type": "string", "nullable": true, "description": "URL to the terms of service. Null if not provided" }, "other": { "type": "string", "nullable": true, "description": "Other legal information. Null if not provided" } }, "required": [ "privacyPolicy", "terms", "other" ], "description": "Legal information about the agent" }, "state": { "type": "string", "enum": [ "RegistrationRequested", "RegistrationInitiated", "RegistrationConfirmed", "RegistrationFailed", "DeregistrationRequested", "DeregistrationInitiated", "DeregistrationConfirmed", "DeregistrationFailed", "UpdateRequested", "UpdateInitiated", "UpdateConfirmed", "UpdateFailed" ], "description": "Current state of the registration process" }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "List of tags categorizing the agent" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the registry request was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the registry request was last updated" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the registry was last checked. Null if never checked" }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60, "description": "Name of the example output" }, "url": { "type": "string", "maxLength": 250, "description": "URL to the example output" }, "mimeType": { "type": "string", "maxLength": 60, "description": "MIME type of the example output (e.g., image/png, text/plain)" } }, "required": [ "name", "url", "mimeType" ] }, "maxItems": 25, "description": "List of example outputs from the agent" }, "agentIdentifier": { "type": "string", "nullable": true, "minLength": 57, "maxLength": 250, "description": "Full agent identifier (policy ID + asset name). Null if not yet minted" }, "AgentPricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "Pricing type for the agent" }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" }, "unit": { "type": "string", "maxLength": 250, "description": "Asset policy id + asset name concatenated. Uses an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" } }, "required": [ "amount", "unit" ] }, "minItems": 1, "description": "List of assets and amounts for fixed pricing" } }, "required": [ "pricingType", "Pricing" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "Pricing type for the agent" } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "Pricing type for the agent. Amounts are provided per payment/purchase request" } }, "required": [ "pricingType" ] }, { "nullable": true } ], "description": "V1 legacy pricing. Null for V2 entries, whose pricing is owned by each supported payment source." }, "sendFundingLovelace": { "type": "string", "nullable": true, "description": "Effective lovelace amount explicitly configured for the NFT output. Null means the default minimum NFT funding is used." }, "supportedPaymentSources": { "type": "array", "nullable": true, "items": { "anyOf": [ { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "Cardano" ], "description": "The blockchain this payment source is available on" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network this payment source is available on" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "The configured payment source type" }, "address": { "type": "string", "maxLength": 250, "description": "The escrow smart contract address for this payment source" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "paymentSourceType", "address", "pricing" ] }, { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "EVM" ], "description": "The chain family used by standard x402" }, "network": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 EVM network id, for example eip155:8453" }, "paymentSourceType": { "type": "string", "nullable": true, "enum": [ "Web3CardanoV1", "Web3CardanoV2", null ], "description": "The configured payment source type" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Alias for payTo, kept for existing payment-source shape" }, "scheme": { "type": "string", "enum": [ "Exact" ], "description": "x402 payment scheme" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address receiving the x402 payment" }, "resource": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional absolute resource URL this x402 option protects" }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional x402 metadata" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "scheme", "payTo", "pricing" ] } ] }, "minItems": 1, "maxItems": 25, "description": "Payment sources advertised by this registry entry. Null for legacy metadata." }, "verifications": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "method": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Verification method discriminator, e.g. \"KERI-ACDC\"" }, "schemaVersion": { "type": "string", "maxLength": 16, "description": "Version of this verification block" }, "issuer": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuer KERI AID (ACDC sad.i) — the root trust anchor" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the issuer KEL (key state) for signature verification" } }, "required": [ "aid", "oobi" ], "description": "Credential issuer identity" }, "schema": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential schema SAID (ACDC sad.s)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the JSON schema; a verifier checks its hash equals said" } }, "required": [ "said", "oobi" ], "description": "Credential schema — the ACDC structure definition" }, "credential": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential SAID (ACDC sad.d)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI/endpoint serving the signed ACDC; a verifier checks its hash equals said" }, "registry": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential status registry / TEL SAID (ACDC sad.ri) for independent revocation checks" } }, "required": [ "said", "oobi" ], "description": "The verifiable credential (ACDC)" }, "holder": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuee/holder KERI AID (ACDC sad.a.i)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the holder KEL" } }, "required": [ "aid", "oobi" ], "description": "Credential holder/issuee identity" }, "baseUrl": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional witness/KERIA resolver root for live key-state (\"verify at time T\") and TEL queries" } }, "required": [ "method", "issuer", "schema", "credential", "holder" ] }, "maxItems": 10, "description": "KERI/Veridian verification claims advertised by this registry entry. Null when none." }, "SmartContractWallet": { "type": "object", "properties": { "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "walletVkey", "walletAddress" ], "description": "Smart contract wallet managing this agent registration" }, "RecipientWallet": { "type": "object", "nullable": true, "properties": { "walletVkey": { "type": "string", "description": "Payment key hash of the managed recipient wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the managed recipient wallet" } }, "required": [ "walletVkey", "walletAddress" ], "description": "Managed wallet that receives the registry NFT. Null when the minting wallet receives it" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction. Null if not yet confirmed" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" } }, "required": [ "txHash", "status", "confirmations", "fees", "blockHeight", "blockTime" ] } }, "required": [ "error", "id", "name", "description", "type", "apiBaseUrl", "openApiSpecUrl", "x402ResourcesUrl", "a2aAgentCardUrl", "a2aProtocolVersions", "paymentSourceType", "Capability", "Author", "Legal", "state", "Tags", "createdAt", "updatedAt", "lastCheckedAt", "ExampleOutputs", "agentIdentifier", "AgentPricing", "sendFundingLovelace", "supportedPaymentSources", "verifications", "SmartContractWallet", "RecipientWallet", "CurrentTransaction" ] }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment source" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment source was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment source was last updated" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network (Mainnet, Preprod, or Preview)" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Payment source type for adapter dispatch" }, "requiredAdminSignatures": { "type": "integer", "nullable": true, "description": "Required weighted admin signatures for Web3CardanoV2 sources. Null for Web3CardanoV1." }, "policyId": { "type": "string", "nullable": true, "description": "Policy ID for the agent registry NFTs. Null if not applicable" }, "smartContractAddress": { "type": "string", "description": "Address of the smart contract for this payment source" }, "lastIdentifierChecked": { "type": "string", "nullable": true, "description": "Last agent identifier checked during registry sync. Null if not synced yet" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the registry was last synced. Null if never synced" }, "AdminWallets": { "type": "array", "items": { "$ref": "#/components/schemas/AdminWallet" }, "description": "List of admin wallets for dispute resolution" }, "FeeReceiverNetworkWallet": { "type": "object", "nullable": true, "properties": { "walletAddress": { "type": "string", "description": "Cardano address that receives network fees" } }, "required": [ "walletAddress" ], "description": "Wallet that receives network fees from transactions" }, "feeRatePermille": { "type": "number", "minimum": 0, "maximum": 1000, "description": "Fee rate in permille" } }, "required": [ "id", "createdAt", "updatedAt", "network", "paymentSourceType", "requiredAdminSignatures", "policyId", "smartContractAddress", "lastIdentifierChecked", "lastCheckedAt", "AdminWallets", "FeeReceiverNetworkWallet", "feeRatePermille" ] }, "AdminWallet": { "type": "object", "properties": { "walletAddress": { "type": "string", "description": "Cardano address of the admin wallet" }, "order": { "type": "number", "description": "Order/index of this admin wallet " } }, "required": [ "walletAddress", "order" ] }, "PaymentSourceExtended": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment source" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment source was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment source was last updated" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Payment source type for adapter dispatch" }, "requiredAdminSignatures": { "type": "integer", "nullable": true, "description": "Required weighted admin signatures for Web3CardanoV2 sources. Null for Web3CardanoV1." }, "policyId": { "type": "string", "nullable": true, "description": "Policy ID for the agent registry NFTs. Null if not applicable" }, "smartContractAddress": { "type": "string", "description": "Address of the smart contract for this payment source" }, "contractSyncStatus": { "type": "string", "enum": [ "in_sync", "outdated_contract", "custom_address" ], "description": "Whether a Web3CardanoV2 source is on the current on-chain contract. \"outdated_contract\": registry policyId differs from the current default (retired contract — agents orphaned, payment address stale); \"custom_address\": current version but a non-default admin-wallet address; \"in_sync\": matches the current default (also for V1 and any non-V2 source)." }, "PaymentSourceConfig": { "type": "object", "properties": { "rpcProviderApiKey": { "type": "string", "description": "The RPC provider API key (e.g., Blockfrost project ID). Operator secret: only returned to keys with admin access, omitted for Read/ReadAndPay keys." }, "rpcProvider": { "type": "string", "enum": [ "Blockfrost" ], "description": "The RPC provider type (e.g., Blockfrost)" } }, "required": [ "rpcProvider" ], "description": "RPC provider configuration for blockchain interactions" }, "lastIdentifierChecked": { "type": "string", "nullable": true, "description": "Last agent identifier checked during registry sync. Null if not synced yet" }, "syncInProgress": { "type": "boolean", "description": "Whether a registry sync is currently in progress" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the registry was last synced. Null if never synced" }, "AdminWallets": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string", "description": "Cardano address of the admin wallet" }, "order": { "type": "number", "description": "Order/index of this admin wallet (0-2)" } }, "required": [ "walletAddress", "order" ] }, "description": "List of admin wallets for dispute resolution (exactly 3 required)" }, "PurchasingWalletsCount": { "type": "integer", "description": "Number of active purchasing wallets. Fetch the wallets themselves via GET /wallet/list." }, "SellingWalletsCount": { "type": "integer", "description": "Number of active selling wallets. Fetch the wallets themselves via GET /wallet/list." }, "FeeReceiverNetworkWallet": { "type": "object", "nullable": true, "properties": { "walletAddress": { "type": "string", "description": "Cardano address that receives network fees" } }, "required": [ "walletAddress" ], "description": "Wallet that receives network fees from transactions" }, "feeRatePermille": { "type": "number", "minimum": 0, "maximum": 1000, "description": "Fee rate in permille (per thousand). Example: 50 = 5%" } }, "required": [ "id", "createdAt", "updatedAt", "network", "paymentSourceType", "requiredAdminSignatures", "policyId", "smartContractAddress", "contractSyncStatus", "PaymentSourceConfig", "lastIdentifierChecked", "syncInProgress", "lastCheckedAt", "AdminWallets", "PurchasingWalletsCount", "SellingWalletsCount", "FeeReceiverNetworkWallet", "feeRatePermille" ] }, "Utxo": { "type": "object", "properties": { "txHash": { "type": "string", "description": "Transaction hash containing this UTXO" }, "address": { "type": "string", "description": "Cardano address holding this UTXO" }, "Amounts": { "type": "array", "items": { "$ref": "#/components/schemas/UtxoAmount" }, "description": "List of assets and amounts in this UTXO" }, "dataHash": { "type": "string", "nullable": true, "description": "Hash of the datum attached to this UTXO. Null if no datum" }, "inlineDatum": { "type": "string", "nullable": true, "description": "Inline datum data in CBOR hex format. Null if no inline datum" }, "referenceScriptHash": { "type": "string", "nullable": true, "description": "Hash of the reference script attached to this UTXO. Null if no reference script" }, "outputIndex": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 1000000000, "description": "Output index of this UTXO in the transaction" }, "block": { "type": "string", "description": "Block hash where this UTXO was created" } }, "required": [ "txHash", "address", "Amounts", "dataHash", "inlineDatum", "referenceScriptHash", "outputIndex", "block" ] }, "UtxoAmount": { "type": "object", "properties": { "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" }, "quantity": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100000000000000, "description": "The quantity of the asset in its smallest unit. For ADA, this is lovelace (1 ADA = 1000000 lovelace)" } }, "required": [ "unit", "quantity" ] }, "BalanceAmount": { "type": "object", "properties": { "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" }, "quantity": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100000000000000, "description": "The quantity of the asset in its smallest unit. For ADA, this is lovelace (1 ADA = 1000000 lovelace)" } }, "required": [ "unit", "quantity" ] }, "RpcProviderKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the RPC provider key" }, "rpcProviderApiKey": { "type": "string", "description": "The RPC provider API key " }, "rpcProvider": { "type": "string", "enum": [ "Blockfrost" ], "description": "The RPC provider type " }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the RPC provider key was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the RPC provider key was last updated" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network this RPC provider key is for" } }, "required": [ "id", "rpcProviderApiKey", "rpcProvider", "createdAt", "updatedAt", "network" ] }, "InboxAgentMetadata": { "type": "object", "properties": { "policyId": { "type": "string", "description": "Policy ID of the inbox registry NFT" }, "assetName": { "type": "string", "description": "Asset name of the inbox registry NFT" }, "agentIdentifier": { "type": "string", "description": "Full inbox agent identifier (policy ID + asset name)" }, "Metadata": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "description": "Name of the inbox agent" }, "description": { "type": "string", "nullable": true, "maxLength": 500, "description": "Description of the inbox agent. Null if not provided" }, "agentSlug": { "type": "string", "maxLength": 80, "description": "Canonical inbox agent slug" }, "metadataVersion": { "type": "integer", "minimum": 1, "maximum": 1, "description": "Version of the metadata schema (currently only version 1 is supported)" } }, "required": [ "name", "agentSlug", "metadataVersion" ], "description": "On-chain metadata for the inbox agent" } }, "required": [ "policyId", "assetName", "agentIdentifier", "Metadata" ] }, "InboxAgentIdentifierMetadata": { "type": "object", "properties": { "policyId": { "type": "string", "description": "Policy ID of the inbox registry NFT" }, "assetName": { "type": "string", "description": "Asset name of the inbox registry NFT" }, "agentIdentifier": { "type": "string", "description": "Full inbox agent identifier (policy ID + asset name)" }, "Metadata": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "description": "Name of the inbox agent" }, "description": { "type": "string", "nullable": true, "maxLength": 500, "description": "Description of the inbox agent. Null if not provided" }, "agentSlug": { "type": "string", "maxLength": 80, "description": "Canonical inbox agent slug" }, "metadataVersion": { "type": "integer", "minimum": 1, "maximum": 1, "description": "Version of the metadata schema (currently only version 1 is supported)" } }, "required": [ "name", "agentSlug", "metadataVersion" ], "description": "On-chain metadata for the inbox agent" } }, "required": [ "policyId", "assetName", "agentIdentifier", "Metadata" ] }, "RegistryInboxEntry": { "type": "object", "properties": { "error": { "type": "string", "nullable": true, "description": "Error message if registration failed. Null if no error" }, "id": { "type": "string", "description": "Unique identifier for the inbox registration request" }, "name": { "type": "string", "description": "Name of the inbox agent" }, "description": { "type": "string", "nullable": true, "description": "Description of the inbox agent. Null if not provided" }, "agentSlug": { "type": "string", "description": "Canonical slug registered for the inbox agent" }, "state": { "type": "string", "enum": [ "RegistrationRequested", "RegistrationInitiated", "RegistrationConfirmed", "RegistrationFailed", "DeregistrationRequested", "DeregistrationInitiated", "DeregistrationConfirmed", "DeregistrationFailed", "UpdateRequested", "UpdateInitiated", "UpdateConfirmed", "UpdateFailed" ], "description": "Current state of the inbox registration process" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the inbox registration request was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the inbox registration request was last updated" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the inbox registration was last checked. Null if never checked" }, "agentIdentifier": { "type": "string", "nullable": true, "minLength": 57, "maxLength": 250, "description": "Full inbox agent identifier (policy ID + asset name). Null if not yet minted" }, "metadataVersion": { "type": "integer", "description": "Version of the inbox metadata schema" }, "sendFundingLovelace": { "type": "string", "nullable": true, "description": "Effective lovelace amount explicitly configured for the NFT output. Null means the default minimum NFT funding is used." }, "SmartContractWallet": { "type": "object", "properties": { "walletVkey": { "type": "string", "description": "Payment key hash of the minting wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the minting wallet" } }, "required": [ "walletVkey", "walletAddress" ], "description": "Minting wallet managing this inbox registration" }, "RecipientWallet": { "type": "object", "nullable": true, "properties": { "walletVkey": { "type": "string", "description": "Payment key hash of the managed recipient wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the managed recipient wallet" } }, "required": [ "walletVkey", "walletAddress" ], "description": "Managed wallet that receives the inbox registry NFT. Null when the minting wallet receives it" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction. Null if not yet confirmed" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" } }, "required": [ "txHash", "status", "confirmations", "fees", "blockHeight", "blockTime" ] } }, "required": [ "error", "id", "name", "description", "agentSlug", "state", "createdAt", "updatedAt", "lastCheckedAt", "agentIdentifier", "metadataVersion", "sendFundingLovelace", "SmartContractWallet", "RecipientWallet", "CurrentTransaction" ] }, "MonitoringStatus": { "type": "object", "properties": { "MonitoringStatus": { "type": "object", "properties": { "isMonitoring": { "type": "boolean", "description": "Whether the blockchain state monitoring service is currently running" }, "Stats": { "type": "object", "nullable": true, "properties": { "trackedEntities": { "type": "number", "description": "Number of entities being tracked by the monitoring service" }, "PurchaseCursor": { "type": "object", "properties": { "timestamp": { "type": "string", "description": "Last processed purchase timestamp" }, "lastId": { "type": "string", "nullable": true, "description": "Last processed purchase ID" } }, "required": [ "timestamp", "lastId" ], "description": "Cursor position for purchase diff tracking" }, "PaymentCursor": { "type": "object", "properties": { "timestamp": { "type": "string", "description": "Last processed payment timestamp" }, "lastId": { "type": "string", "nullable": true, "description": "Last processed payment ID" } }, "required": [ "timestamp", "lastId" ], "description": "Cursor position for payment diff tracking" }, "MemoryUsage": { "type": "object", "properties": { "heapUsed": { "type": "string", "description": "Heap memory currently used by the monitoring service " }, "heapTotal": { "type": "string", "description": "Total heap memory allocated for the monitoring service " }, "external": { "type": "string", "description": "External memory used by the monitoring service " } }, "required": [ "heapUsed", "heapTotal", "external" ], "description": "Memory usage statistics for the monitoring service" } }, "required": [ "trackedEntities", "PurchaseCursor", "PaymentCursor", "MemoryUsage" ], "description": "Monitoring statistics. Null if monitoring is not active" } }, "required": [ "isMonitoring", "Stats" ], "description": "Current status of the blockchain state monitoring service" } }, "required": [ "MonitoringStatus" ] }, "TriggeredMonitoringCycle": { "type": "object", "properties": { "message": { "type": "string", "description": "Status message about the monitoring cycle trigger" }, "triggered": { "type": "boolean", "description": "Whether the monitoring cycle was successfully triggered" } }, "required": [ "message", "triggered" ] }, "StartedMonitoring": { "type": "object", "properties": { "message": { "type": "string", "description": "Status message about starting the monitoring service" }, "started": { "type": "boolean", "description": "Whether the monitoring service was successfully started" } }, "required": [ "message", "started" ] }, "StoppedMonitoring": { "type": "object", "properties": { "message": { "type": "string", "description": "Status message about stopping the monitoring service" }, "stopped": { "type": "boolean", "description": "Whether the monitoring service was successfully stopped" } }, "required": [ "message", "stopped" ] }, "X402AvailableNetwork": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque x402 network id accepted by managed-wallet endpoints" }, "caip2Id": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 EVM chain id, for example eip155:8453" }, "displayName": { "type": "string", "description": "Human readable chain name" }, "isTestnet": { "type": "boolean", "description": "Whether this chain belongs to the testnet environment" }, "isEnabled": { "type": "boolean", "description": "Whether this chain may currently be used for x402 payments" }, "canSettle": { "type": "boolean", "description": "Whether inbound settlement is configured (a facilitator wallet or URL is present). Outbound (buy) wallets do not require a facilitator, so networks may be listed with canSettle=false." }, "defaultAsset": { "type": "string", "nullable": true, "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Default settlement asset (token contract) for this chain" }, "defaultAssetDecimals": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 255, "description": "Decimals for the default settlement asset; null until an operator confirms them" } }, "required": [ "id", "caip2Id", "displayName", "isTestnet", "isEnabled", "canSettle", "defaultAsset", "defaultAssetDecimals" ] }, "X402Network": { "type": "object", "properties": { "id": { "type": "string" }, "caip2Id": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 EVM chain id, for example eip155:8453" }, "displayName": { "type": "string", "description": "Human readable chain name" }, "rpcUrl": { "type": "string", "description": "HTTP(S) RPC endpoint used to talk to the chain" }, "isTestnet": { "type": "boolean", "description": "Whether this chain is a testnet (paired with the Cardano Preprod environment)" }, "isEnabled": { "type": "boolean", "description": "Whether this chain may be used for x402 payments" }, "defaultAsset": { "type": "string", "nullable": true, "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Default settlement asset (token contract) for this chain" }, "defaultAssetDecimals": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 255, "description": "Decimals for the default settlement asset; null until an operator confirms them" }, "facilitatorWalletId": { "type": "string", "nullable": true, "description": "Id of the managed EVM wallet used to settle payments on this chain (self-hosted facilitator)" }, "facilitatorWalletAddress": { "type": "string", "nullable": true, "description": "Resolved address of the facilitator wallet. Null when no self-hosted facilitator is set." }, "facilitatorUrl": { "type": "string", "nullable": true, "description": "HTTPS URL of a remote x402 facilitator used to settle payments on this chain (no owned wallet needed)" }, "createdById": { "type": "string", "nullable": true, "description": "Id of the API key that created this chain configuration" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "caip2Id", "displayName", "rpcUrl", "isTestnet", "isEnabled", "defaultAsset", "defaultAssetDecimals", "facilitatorWalletId", "facilitatorWalletAddress", "facilitatorUrl", "createdById", "createdAt", "updatedAt" ] }, "X402Wallet": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the managed EVM wallet" }, "networkId": { "type": "string", "description": "Id of the x402 network (payment source) this wallet is bound to" }, "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 chain id of the network this wallet is bound to" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "The EVM address derived from the wallet private key" }, "type": { "type": "string", "enum": [ "Purchasing", "Selling" ], "description": "Purchasing wallets fund outbound payments; Selling wallets settle inbound ones as facilitators" }, "note": { "type": "string", "nullable": true, "description": "Optional human-readable label for the wallet" }, "createdById": { "type": "string", "nullable": true, "description": "Id of the API key that created this wallet. Only returned to admins and for the caller’s own wallets; null otherwise, so a read key cannot enumerate other tenants’ key ids." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "networkId", "caip2Network", "address", "type", "note", "createdById", "createdAt", "updatedAt" ] }, "X402WalletCreated": { "allOf": [ { "$ref": "#/components/schemas/X402Wallet" }, { "type": "object", "properties": { "privateKey": { "type": "string", "nullable": true, "description": "The generated 0x-prefixed private key, returned ONCE so you can back it up. It is null when you supplied your own key, is never stored in plaintext, and can never be retrieved again. Save it now." } }, "required": [ "privateKey" ] } ] }, "X402PaymentAttempt": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "direction": { "type": "string", "enum": [ "InboundVerify", "InboundSettle", "OutboundPayment" ] }, "status": { "type": "string", "enum": [ "PaymentRequired", "Verified", "Settled", "Failed", "Replayed" ] }, "apiKeyId": { "type": "string" }, "evmWalletId": { "type": "string", "nullable": true }, "registryRequestId": { "type": "string", "nullable": true }, "supportedPaymentSourceId": { "type": "string", "nullable": true }, "caip2Network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string", "description": "Payment amount in token base units" }, "payTo": { "type": "string", "nullable": true, "description": "Immutable payee-address snapshot. Null only for legacy transition rows without a snapshot." }, "payer": { "type": "string", "nullable": true }, "resource": { "type": "string", "nullable": true }, "paymentIdentifier": { "type": "string", "nullable": true }, "errorReason": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "facilitator": { "type": "object", "nullable": true, "properties": { "mode": { "type": "string", "enum": [ "self_hosted", "remote", "unknown" ], "description": "Whether an owned wallet, a remote URL, or an unknown legacy facilitator settled" }, "address": { "type": "string", "nullable": true, "description": "Self-hosted facilitator wallet address; null for remote or unknown legacy mode" } }, "required": [ "mode", "address" ], "description": "The facilitator that settled this inbound payment; null for outbound payments and verifies." }, "Settlement": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "success": { "type": "boolean" }, "txHash": { "type": "string", "nullable": true, "description": "On-chain settlement transaction hash" }, "amount": { "type": "string", "nullable": true, "description": "Settled amount in token base units" }, "payer": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "success", "txHash", "amount", "payer", "createdAt" ] } }, "required": [ "id", "createdAt", "updatedAt", "direction", "status", "apiKeyId", "evmWalletId", "registryRequestId", "supportedPaymentSourceId", "caip2Network", "asset", "amount", "payTo", "payer", "resource", "paymentIdentifier", "errorReason", "errorMessage", "facilitator", "Settlement" ] }, "X402SettlementRecord": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "paymentAttemptId": { "type": "string" }, "success": { "type": "boolean" }, "txHash": { "type": "string", "nullable": true }, "caip2Network": { "type": "string" }, "amount": { "type": "string", "nullable": true }, "payer": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "paymentAttemptId", "success", "txHash", "caip2Network", "amount", "payer" ] }, "X402LowBalanceRule": { "type": "object", "properties": { "id": { "type": "string" }, "evmWalletId": { "type": "string" }, "evmWalletAddress": { "type": "string" }, "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string" }, "thresholdAmount": { "type": "string", "description": "Alert threshold in base units" }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "Unknown", "Healthy", "Low" ] }, "lastKnownAmount": { "type": "string", "nullable": true }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastAlertedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "evmWalletId", "evmWalletAddress", "caip2Network", "asset", "thresholdAmount", "enabled", "status", "lastKnownAmount", "lastCheckedAt", "lastAlertedAt", "createdAt", "updatedAt" ] }, "FundWalletList": { "type": "object", "properties": { "FundWallets": { "type": "array", "items": { "$ref": "#/components/schemas/FundWallet" }, "description": "Fund wallets for the payment source" } }, "required": [ "FundWallets" ] }, "FundWallet": { "type": "object", "properties": { "id": { "type": "string", "description": "Fund wallet id" }, "walletAddress": { "type": "string", "description": "Cardano address of the fund wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash" }, "note": { "type": "string", "nullable": true, "description": "Optional note" }, "paymentSourceId": { "type": "string", "description": "Associated payment source id" }, "lockedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when wallet was locked. Null if not locked" }, "LowBalanceSummary": { "type": "object", "properties": { "isLow": { "type": "boolean", "description": "Whether any enabled low-balance rule for this wallet is currently below threshold" }, "lowRuleCount": { "type": "integer", "minimum": 0, "description": "How many enabled rules for this wallet are currently in low state" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp of the latest low-balance evaluation across this wallet rules. Null if never checked" } }, "required": [ "isLow", "lowRuleCount", "lastCheckedAt" ] }, "FundDistributionConfig": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Config id" }, "enabled": { "type": "boolean", "description": "Whether this wallet is an active funding source" }, "batchWindowMs": { "type": "integer", "description": "Milliseconds to wait before sending batched topups" } }, "required": [ "id", "enabled", "batchWindowMs" ], "description": "Distribution configuration" }, "pendingRequestCount": { "type": "integer", "description": "Number of pending distribution requests" } }, "required": [ "id", "walletAddress", "walletVkey", "note", "paymentSourceId", "lockedAt", "LowBalanceSummary", "FundDistributionConfig", "pendingRequestCount" ] }, "FundWalletCreated": { "type": "object", "properties": { "id": { "type": "string", "description": "Fund wallet id" }, "walletAddress": { "type": "string", "description": "Cardano address" }, "walletVkey": { "type": "string", "description": "Payment key hash" }, "paymentSourceId": { "type": "string", "description": "Associated payment source id" }, "FundDistributionConfig": { "type": "object", "properties": { "id": { "type": "string", "description": "Config id" }, "enabled": { "type": "boolean", "description": "Whether this wallet is an active funding source" }, "batchWindowMs": { "type": "integer", "description": "Milliseconds to wait before sending batched topups" } }, "required": [ "id", "enabled", "batchWindowMs" ], "description": "Created distribution config" } }, "required": [ "id", "walletAddress", "walletVkey", "paymentSourceId", "FundDistributionConfig" ] }, "FundWalletUpdated": { "type": "object", "properties": { "id": { "type": "string", "description": "Fund wallet id" }, "FundDistributionConfig": { "type": "object", "properties": { "id": { "type": "string", "description": "Config id" }, "enabled": { "type": "boolean", "description": "Whether this wallet is an active funding source" }, "batchWindowMs": { "type": "integer", "description": "Milliseconds to wait before sending batched topups" } }, "required": [ "id", "enabled", "batchWindowMs" ], "description": "Updated distribution config" } }, "required": [ "id", "FundDistributionConfig" ] }, "FundWalletDeleted": { "type": "object", "properties": { "id": { "type": "string", "description": "Deleted fund wallet id" } }, "required": [ "id" ] }, "FundDistributionList": { "type": "object", "properties": { "FundDistributions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Distribution request id" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the request was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the request was last updated" }, "fundWalletId": { "type": "string", "nullable": true, "description": "Id of the fund wallet sending the funds. Null until a fund wallet claims the request" }, "targetWalletId": { "type": "string", "description": "Id of the wallet receiving the funds" }, "priority": { "type": "string", "enum": [ "Warning", "Critical" ], "description": "Legacy priority marker. New requests use Warning; both values are dispatched through the batch window" }, "assetUnit": { "type": "string", "description": "\"lovelace\" for ADA, otherwise policy id + hex asset name" }, "amount": { "type": "string", "description": "Amount sent in the asset's smallest unit" }, "status": { "type": "string", "enum": [ "Pending", "Submitted", "Confirmed", "Failed" ], "description": "Current status of the distribution request" }, "txHash": { "type": "string", "nullable": true, "description": "On-chain transaction hash. Null until submitted" }, "error": { "type": "string", "nullable": true, "description": "Error message if the distribution failed" }, "batchId": { "type": "string", "nullable": true, "description": "Groups requests sent in the same transaction" } }, "required": [ "id", "createdAt", "updatedAt", "fundWalletId", "targetWalletId", "priority", "assetUnit", "amount", "status", "txHash", "error", "batchId" ] }, "description": "List of distribution requests" } }, "required": [ "FundDistributions" ] }, "FundDistributionTriggered": { "type": "object", "properties": { "triggered": { "type": "boolean", "description": "Always true — indicates the request was received" }, "alreadyRunning": { "type": "boolean", "description": "True if a distribution cycle was already in progress when this request arrived" } }, "required": [ "triggered", "alreadyRunning" ] }, "HydraHost": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "name": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "baseUrl": { "type": "string" }, "allowInsecureHttp": { "type": "boolean" }, "publicPeerHost": { "type": "string" }, "hasAdminToken": { "type": "boolean" }, "hydraVersion": { "type": "string", "nullable": true }, "scriptCatalogueHash": { "type": "string", "nullable": true }, "ledgerParamsHash": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "Active", "Draining", "Unreachable", "Disabled" ] }, "lastHealthAt": { "type": "string", "nullable": true }, "lastHealthError": { "type": "string", "nullable": true }, "participantCount": { "type": "number" } }, "required": [ "id", "createdAt", "updatedAt", "name", "network", "baseUrl", "allowInsecureHttp", "publicPeerHost", "hasAdminToken", "hydraVersion", "scriptCatalogueHash", "ledgerParamsHash", "status", "lastHealthAt", "lastHealthError", "participantCount" ] }, "HydraRelationDetail": { "allOf": [ { "$ref": "#/components/schemas/HydraRelation" }, { "type": "object", "properties": { "Heads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "Disconnected", "Connected", "Connecting", "Idle", "Initializing", "Open", "Closed", "FanoutPossible", "Final" ] }, "headIdentifier": { "type": "string", "nullable": true }, "isEnabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "openedAt": { "type": "string", "nullable": true, "format": "date-time" }, "closedAt": { "type": "string", "nullable": true, "format": "date-time" }, "finalizedAt": { "type": "string", "nullable": true, "format": "date-time" }, "_count": { "type": "object", "properties": { "RemoteParticipants": { "type": "number" } }, "required": [ "RemoteParticipants" ] } }, "required": [ "id", "status", "headIdentifier", "isEnabled", "createdAt", "openedAt", "closedAt", "finalizedAt", "_count" ] } } } } ] }, "HydraRelation": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "localHotWalletId": { "type": "string" }, "remoteWalletId": { "type": "string" }, "counterpartyBaseUrl": { "type": "string", "nullable": true }, "LocalHotWallet": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "type": { "type": "string" }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "type", "note" ] }, "RemoteWallet": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "type": { "type": "string" }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "type", "note" ] }, "_count": { "type": "object", "properties": { "Heads": { "type": "number" } }, "required": [ "Heads" ] } }, "required": [ "id", "createdAt", "updatedAt", "network", "localHotWalletId", "remoteWalletId", "counterpartyBaseUrl" ] }, "HydraHead": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hydraRelationId": { "type": "string" }, "headIdentifier": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "Disconnected", "Connected", "Connecting", "Idle", "Initializing", "Open", "Closed", "FanoutPossible", "Final" ] }, "contestationPeriod": { "type": "string" }, "isEnabled": { "type": "boolean" }, "openedAt": { "type": "string", "nullable": true }, "closedAt": { "type": "string", "nullable": true }, "finalizedAt": { "type": "string", "nullable": true }, "contestationDeadline": { "type": "string", "nullable": true }, "latestActivityAt": { "type": "string", "nullable": true }, "latestSnapshotNumber": { "type": "string" }, "reconciliationStalledTxId": { "type": "string", "nullable": true, "description": "Confirmed in-head tx the ordered replay is stuck on (fail-closed stall); null when replay is healthy" }, "reconciliationStalledReason": { "type": "string", "nullable": true, "description": "Why replay is stalled: evidence-parse-failed | replay-apply-retry" }, "reconciliationStalledSince": { "type": "string", "nullable": true, "description": "When the current stall was first observed" }, "initTxHash": { "type": "string", "nullable": true }, "closeTxHash": { "type": "string", "nullable": true }, "fanoutTxHash": { "type": "string", "nullable": true }, "Invite": { "type": "object", "nullable": true, "properties": { "role": { "type": "string", "enum": [ "Issuer", "Redeemer" ] }, "contestationPeriodSeconds": { "type": "number" }, "depositPeriodSeconds": { "type": "number" }, "unsyncedPeriodSeconds": { "type": "number" } }, "required": [ "role", "contestationPeriodSeconds", "depositPeriodSeconds", "unsyncedPeriodSeconds" ], "description": "Which side of the invite exchange this head came from; absent for heads not created from one" }, "LocalParticipant": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "walletId": { "type": "string" }, "Wallet": { "type": "object", "properties": { "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "Selling", "Purchasing", "Funding" ] } }, "required": [ "walletVkey", "walletAddress", "collectionAddress", "note", "type" ] }, "nodeUrl": { "type": "string" }, "nodeHttpUrl": { "type": "string" }, "hasCommitted": { "type": "boolean" }, "commitTxHash": { "type": "string", "nullable": true }, "hydraHostId": { "type": "string" }, "hostNodeId": { "type": "string" }, "cardanoVkey": { "type": "string" }, "keysDisclosedAt": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "walletId", "Wallet", "nodeUrl", "nodeHttpUrl", "hasCommitted", "commitTxHash", "hydraHostId", "hostNodeId", "cardanoVkey", "keysDisclosedAt" ] }, "RemoteParticipants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "walletId": { "type": "string" }, "Wallet": { "type": "object", "properties": { "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "walletVkey", "walletAddress" ] }, "advertise": { "type": "string" }, "hasCommitted": { "type": "boolean" }, "commitTxHash": { "type": "string", "nullable": true }, "HydraVerificationKey": { "type": "object", "properties": { "hydraVK": { "type": "string" } }, "required": [ "hydraVK" ] }, "cardanoVkey": { "type": "string" } }, "required": [ "id", "createdAt", "walletId", "Wallet", "advertise", "hasCommitted", "commitTxHash", "HydraVerificationKey", "cardanoVkey" ] } }, "_count": { "type": "object", "properties": { "Errors": { "type": "number" }, "Transactions": { "type": "number" } }, "required": [ "Errors", "Transactions" ] } }, "required": [ "id", "createdAt", "updatedAt", "hydraRelationId", "headIdentifier", "status", "contestationPeriod", "isEnabled", "openedAt", "closedAt", "finalizedAt", "contestationDeadline", "latestActivityAt", "latestSnapshotNumber", "reconciliationStalledTxId", "reconciliationStalledReason", "reconciliationStalledSince", "initTxHash", "closeTxHash", "fanoutTxHash" ] }, "HydraLowBalanceRule": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hydraLocalParticipantId": { "type": "string" }, "assetUnit": { "type": "string" }, "thresholdAmount": { "type": "string" }, "enabled": { "type": "boolean" }, "topupEnabled": { "type": "boolean" }, "topupAmount": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "Unknown", "Healthy", "Low" ] }, "lastKnownAmount": { "type": "string", "nullable": true }, "lastCheckedAt": { "type": "string", "nullable": true }, "lastAlertedAt": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "hydraLocalParticipantId", "assetUnit", "thresholdAmount", "enabled", "topupEnabled", "topupAmount", "status", "lastKnownAmount", "lastCheckedAt", "lastAlertedAt" ] }, "HydraLocalParticipant": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hydraHeadId": { "type": "string", "nullable": true }, "walletId": { "type": "string" }, "cardanoVkey": { "type": "string" }, "nodeUrl": { "type": "string" }, "nodeHttpUrl": { "type": "string" }, "hasCommitted": { "type": "boolean" }, "commitTxHash": { "type": "string", "nullable": true }, "hydraHostId": { "type": "string" }, "hostNodeId": { "type": "string" }, "Wallet": { "type": "object", "properties": { "walletAddress": { "type": "string" } }, "required": [ "walletAddress" ] }, "HydraHead": { "type": "object", "nullable": true, "properties": { "status": { "type": "string", "enum": [ "Disconnected", "Connected", "Connecting", "Idle", "Initializing", "Open", "Closed", "FanoutPossible", "Final" ] } }, "required": [ "status" ] }, "keysDisclosedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "createdAt", "updatedAt", "hydraHeadId", "walletId", "cardanoVkey", "nodeUrl", "nodeHttpUrl", "hasCommitted", "commitTxHash", "hydraHostId", "hostNodeId", "keysDisclosedAt" ] }, "HydraRemoteParticipant": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hydraHeadId": { "type": "string", "nullable": true }, "walletId": { "type": "string" }, "cardanoVkey": { "type": "string" }, "advertise": { "type": "string" }, "hasCommitted": { "type": "boolean" }, "commitTxHash": { "type": "string", "nullable": true }, "hydraVerificationKeyId": { "type": "string" } }, "required": [ "id", "createdAt", "updatedAt", "hydraHeadId", "walletId", "cardanoVkey", "advertise", "hasCommitted", "commitTxHash", "hydraVerificationKeyId" ] }, "RailReadiness": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The environment these results describe" }, "Rails": { "type": "array", "items": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "CardanoV2", "X402" ], "description": "Which payment rail this readiness block describes" }, "isReady": { "type": "boolean", "description": "Whether the rail can actually take payments right now. True only when every blocking check is complete — optional checks (e.g. outbound spending) do not affect it" }, "Checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "cardano.payment_source", "cardano.contract_current", "cardano.rpc_provider", "cardano.admin_signatures", "cardano.selling_wallet", "cardano.purchasing_wallet", "cardano.payments_enabled", "x402.enabled_chain", "x402.rpc_url", "x402.facilitator", "x402.selling_wallet", "x402.purchasing_wallet" ], "description": "Stable check identifier. The admin UI maps setup steps onto these" }, "label": { "type": "string", "description": "Short human-readable name for the check" }, "isComplete": { "type": "boolean", "description": "Whether the backend considers this check satisfied" }, "detail": { "type": "string", "nullable": true, "description": "Why the check is incomplete, or extra context when it passes. Null when there is nothing to add" } }, "required": [ "id", "label", "isComplete", "detail" ] }, "description": "Individual checks, in setup order" }, "PurchaseSources": { "type": "array", "items": { "type": "object", "properties": { "policyId": { "type": "string", "nullable": true, "description": "Registry policy id this configured V2 source can purchase from" }, "smartContractAddress": { "type": "string", "description": "V2 escrow contract address this configured source can purchase through" }, "isPurchaseReady": { "type": "boolean", "description": "Whether this exact policy and contract source can execute outbound purchases" }, "Checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "cardano.payment_source", "cardano.contract_current", "cardano.rpc_provider", "cardano.admin_signatures", "cardano.selling_wallet", "cardano.purchasing_wallet", "cardano.payments_enabled", "x402.enabled_chain", "x402.rpc_url", "x402.facilitator", "x402.selling_wallet", "x402.purchasing_wallet" ], "description": "Stable check identifier. The admin UI maps setup steps onto these" }, "label": { "type": "string", "description": "Short human-readable name for the check" }, "isComplete": { "type": "boolean", "description": "Whether the backend considers this check satisfied" }, "detail": { "type": "string", "nullable": true, "description": "Why the check is incomplete, or extra context when it passes. Null when there is nothing to add" } }, "required": [ "id", "label", "isComplete", "detail" ] }, "description": "Buyer-direction checks for this source; selling-wallet readiness is intentionally excluded" } }, "required": [ "policyId", "smartContractAddress", "isPurchaseReady", "Checks" ] }, "description": "Per-source outbound purchase readiness for CardanoV2. Policy ids and contract addresses are public on-chain identifiers; secrets are never returned" } }, "required": [ "rail", "isReady", "Checks" ] }, "description": "Readiness per payment rail" } }, "required": [ "network", "Rails" ] }, "TxSyncQuarantineEntry": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "txHash": { "type": "string", "description": "The transaction the sync could not apply" }, "blockHeight": { "type": "number", "nullable": true, "description": "Chain position, when known" }, "txIndex": { "type": "number", "nullable": true }, "reason": { "type": "string", "enum": [ "ExtendedLookupFailed", "ProcessingFailed", "PredecessorPending", "CanonicalRollback" ], "description": "Whether lookup/processing failed, processing was deferred behind a predecessor, or canonical rollback settlement is pending" }, "attempts": { "type": "number", "description": "How many retries the reconciler has already made" }, "lastError": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "format": "date-time", "description": "The reconciler will not retry before this time" }, "resolvedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Set once successfully applied or canonically confirmed rolled back. Rows are retained for audit" }, "needsOperator": { "type": "boolean", "description": "Retries stopped; a human needs to look at it" }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "smartContractAddress": { "type": "string" } }, "required": [ "id", "network", "smartContractAddress" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "blockHeight", "txIndex", "reason", "attempts", "lastError", "nextRetryAt", "resolvedAt", "needsOperator", "PaymentSource" ] } }, "parameters": {} }, "paths": { "/health": { "get": { "tags": [ "health" ], "summary": "Get the status of the API server. (No authentication required)", "responses": { "200": { "description": "Object with status ok, if the server is up and healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "Health status of the service. Returns \"ok\" when the service is running" } }, "required": [ "status" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "status": "ok" } } } } } } } } }, "/api-key-status": { "get": { "description": "Gets api key status", "summary": "Get information about your current API key.", "tags": [ "api-key" ], "security": [ { "API-Key": [] } ], "responses": { "200": { "description": "API key status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/APIKey" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "api_key_id", "token": "masumi_payment_api_key_secret", "permission": "Admin", "canRead": true, "canPay": true, "canAdmin": true, "usageLimited": true, "NetworkLimit": [ "Preprod" ], "ChainIdLimit": [ "cardano:preprod" ], "RemainingUsageCredits": [ { "unit": "", "amount": "10000000" } ], "status": "Active", "walletScopeEnabled": false, "WalletScopes": [], "x402WalletScopeEnabled": false, "X402WalletScopes": [] } } } } } } } } }, "/wallet": { "get": { "description": "Gets wallet status", "summary": "Get information about a wallet. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Selling", "Purchasing", "Funding" ], "description": "The type of wallet to query" }, "required": true, "description": "The type of wallet to query", "name": "walletType", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "The id of the wallet to query" }, "required": true, "description": "The id of the wallet to query", "name": "id", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the decrypted secret in the response" }, "required": false, "description": "Whether to include the decrypted secret in the response", "name": "includeSecret", "in": "query" } ], "responses": { "200": { "description": "Wallet status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/Wallet" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "walletVkey": "wallet_vkey", "note": "note", "PendingTransaction": null, "walletAddress": "wallet_address", "collectionAddress": "collection_address", "LowBalanceSummary": { "isLow": true, "lowRuleCount": 1, "lastCheckedAt": "1970-01-20T20:00:36.260Z" }, "LowBalanceRules": [ { "id": "low_balance_rule_id", "assetUnit": "lovelace", "thresholdAmount": "5000000", "enabled": true, "topupEnabled": true, "topupAmount": "10000000", "status": "Low", "lastKnownAmount": "4200000", "lastCheckedAt": "1970-01-20T20:00:36.260Z", "lastAlertedAt": "1970-01-20T20:00:36.260Z" } ] } } } } } } } }, "post": { "description": "Creates a wallet, it will not be saved in the database, please ensure to remember the mnemonic", "summary": "Create a new wallet. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the Cardano wallet will be used on" } }, "required": [ "network" ], "example": { "network": "Preprod" } } } } }, "responses": { "200": { "description": "Wallet created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/GeneratedWalletSecret" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "walletMnemonic": "wallet_mnemonic", "walletAddress": "wallet_address", "walletVkey": "wallet_vkey" } } } } } } } }, "patch": { "description": "Updates a wallet", "summary": "Update a wallet. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 250, "description": "The id of the wallet to update" }, "newCollectionAddress": { "type": "string", "nullable": true, "maxLength": 250, "description": "The new collection address to set for this wallet. Pass null to clear." } }, "required": [ "id", "newCollectionAddress" ], "example": { "id": "unique_cuid_v2_of_entry_to_update", "newCollectionAddress": "collection_address" } } } } }, "responses": { "200": { "description": "Wallet updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Wallet" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "walletVkey": "wallet_vkey", "note": "note", "PendingTransaction": null, "walletAddress": "wallet_address", "collectionAddress": "collection_address", "LowBalanceSummary": { "isLow": true, "lowRuleCount": 1, "lastCheckedAt": "1970-01-20T20:00:36.260Z" }, "LowBalanceRules": [ { "id": "low_balance_rule_id", "assetUnit": "lovelace", "thresholdAmount": "5000000", "enabled": true, "topupEnabled": true, "topupAmount": "10000000", "status": "Low", "lastKnownAmount": "4200000", "lastCheckedAt": "1970-01-20T20:00:36.260Z", "lastAlertedAt": "1970-01-20T20:00:36.260Z" } ] } } } } } }, "404": { "description": "Wallet not found" } } } }, "/wallet/list": { "get": { "description": "Lists hot wallets across payment sources with cursor-based pagination. searchQuery applies before pagination, so a wallet beyond the first page is still found.", "summary": "List hot wallets, optionally filtered or searched by payment source, type and free text. (read access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of wallets to return" }, "required": false, "description": "The number of wallets to return", "name": "take", "in": "query" }, { "schema": { "type": "string", "maxLength": 250, "description": "Used to paginate through the wallets (provide the id of the last returned wallet)" }, "required": false, "description": "Used to paginate through the wallets (provide the id of the last returned wallet)", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "maxLength": 250, "description": "Filter wallets to a single payment source" }, "required": false, "description": "Filter wallets to a single payment source", "name": "paymentSourceId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Selling", "Purchasing", "Funding" ], "description": "Filter wallets by type (Selling, Purchasing or Funding)" }, "required": false, "description": "Filter wallets by type (Selling, Purchasing or Funding)", "name": "walletType", "in": "query" }, { "schema": { "type": "string", "maxLength": 250, "description": "Filter to the single wallet with this payment key hash" }, "required": false, "description": "Filter to the single wallet with this payment key hash", "name": "walletVkey", "in": "query" }, { "schema": { "type": "string", "maxLength": 250, "description": "Filter to wallets with this Cardano address" }, "required": false, "description": "Filter to wallets with this Cardano address", "name": "walletAddress", "in": "query" }, { "schema": { "type": "string", "maxLength": 500, "description": "Free-text search applied before pagination, so a wallet beyond the first page is still found. Matches wallet address, collection address, note, payment key hash and id (case-insensitive substring), and the wallet type by either its API name (\"Purchasing\") or the label the admin UI renders (\"Buying\"). \"%\" and \"_\" are matched literally. Balance is not searchable: it is read from the chain, not stored. Combined with the exact filters above as a logical AND." }, "required": false, "description": "Free-text search applied before pagination, so a wallet beyond the first page is still found. Matches wallet address, collection address, note, payment key hash and id (case-insensitive substring), and the wallet type by either its API name (\"Purchasing\") or the label the admin UI renders (\"Buying\"). \"%\" and \"_\" are matched literally. Balance is not searchable: it is read from the chain, not stored. Combined with the exact filters above as a logical AND.", "name": "searchQuery", "in": "query" } ], "responses": { "200": { "description": "Paginated list of hot wallets", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Wallets": { "type": "array", "items": { "$ref": "#/components/schemas/WalletListItem" }, "description": "Paginated list of hot wallets" } }, "required": [ "Wallets" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Wallets": [ { "id": "unique_cuid_v2_auto_generated", "paymentSourceId": "unique_cuid_v2_of_payment_source", "type": "Selling", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "collectionAddress": null, "note": "note", "LowBalanceSummary": { "isLow": false, "lowRuleCount": 0, "lastCheckedAt": "1970-01-20T20:00:36.260Z" } } ] } } } } } } } } }, "/wallet/low-balance": { "get": { "description": "Lists low-balance monitoring rules for wallets", "summary": "List wallet low-balance rules. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Optional: filter rules by wallet id" }, "required": false, "description": "Optional: filter rules by wallet id", "name": "walletId", "in": "query" }, { "schema": { "type": "string", "description": "Optional: filter rules by payment source id" }, "required": false, "description": "Optional: filter rules by payment source id", "name": "paymentSourceId", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to return only rules currently in low state" }, "required": false, "description": "Whether to return only rules currently in low state", "name": "onlyLow", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include disabled rules" }, "required": false, "description": "Whether to include disabled rules", "name": "includeDisabled", "in": "query" } ], "responses": { "200": { "description": "Wallet low-balance rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the low-balance rule" }, "assetUnit": { "type": "string", "description": "Raw on-chain asset unit, for example lovelace or a full policy+asset identifier" }, "thresholdAmount": { "type": "string", "description": "Threshold in raw on-chain units used to determine low balance" }, "enabled": { "type": "boolean", "description": "Whether the rule is active (fires the low-balance alert/webhook)" }, "topupEnabled": { "type": "boolean", "description": "Whether crossing the threshold also auto-tops-up this wallet from a fund wallet on its source" }, "topupAmount": { "type": "string", "nullable": true, "description": "Amount to top up per trigger, in raw on-chain units. Null when auto top-up is off" }, "status": { "type": "string", "enum": [ "Unknown", "Healthy", "Low" ], "description": "Current deduped state of the rule" }, "lastKnownAmount": { "type": "string", "nullable": true, "description": "Last observed balance for this asset in raw on-chain units. Null if never checked" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the rule was last evaluated. Null if never checked" }, "lastAlertedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the wallet last entered low balance for this rule. Null if never alerted" }, "walletId": { "type": "string", "description": "Hot wallet id the rule belongs to" }, "walletVkey": { "type": "string", "description": "Wallet verification key" }, "walletAddress": { "type": "string", "description": "Wallet address" }, "walletType": { "type": "string", "enum": [ "Selling", "Purchasing", "Funding" ], "description": "Hot wallet type" }, "paymentSourceId": { "type": "string", "description": "Payment source id owning the wallet" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Wallet network" } }, "required": [ "id", "assetUnit", "thresholdAmount", "enabled", "topupEnabled", "topupAmount", "status", "lastKnownAmount", "lastCheckedAt", "lastAlertedAt", "walletId", "walletVkey", "walletAddress", "walletType", "paymentSourceId", "network" ] } } }, "required": [ "Rules" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Rules": [ { "id": "low_balance_rule_id", "assetUnit": "lovelace", "thresholdAmount": "5000000", "enabled": true, "topupEnabled": true, "topupAmount": "10000000", "status": "Low", "lastKnownAmount": "4200000", "lastCheckedAt": "1970-01-20T20:00:36.260Z", "lastAlertedAt": "1970-01-20T20:00:36.260Z", "walletId": "unique_cuid_v2_of_wallet", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "walletType": "Purchasing", "paymentSourceId": "payment_source_id", "network": "Preprod" } ] } } } } } } } }, "post": { "description": "Creates a wallet low-balance monitoring rule", "summary": "Create a wallet low-balance rule. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Low-balance rule to create", "content": { "application/json": { "schema": { "type": "object", "properties": { "walletId": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Hot wallet id to attach the rule to" }, "assetUnit": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Raw on-chain asset unit, for example lovelace or a policy+asset identifier" }, "thresholdAmount": { "type": "string", "pattern": "^\\d+$", "description": "Threshold in raw on-chain units. Example: 5000000 for 5 ADA" }, "enabled": { "type": "boolean", "default": true, "description": "Whether the rule should start enabled" }, "topupEnabled": { "type": "boolean", "default": false, "description": "Whether crossing the threshold also auto-tops-up this wallet" }, "topupAmount": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "Amount to top up per trigger, in raw on-chain units. Required when topupEnabled is true; ADA requires at least 5000000 lovelace" } }, "required": [ "walletId", "assetUnit", "thresholdAmount" ], "example": { "walletId": "unique_cuid_v2_of_wallet", "assetUnit": "lovelace", "thresholdAmount": "5000000", "enabled": true } } } } }, "responses": { "200": { "description": "Wallet low-balance rule created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the low-balance rule" }, "assetUnit": { "type": "string", "description": "Raw on-chain asset unit, for example lovelace or a full policy+asset identifier" }, "thresholdAmount": { "type": "string", "description": "Threshold in raw on-chain units used to determine low balance" }, "enabled": { "type": "boolean", "description": "Whether the rule is active (fires the low-balance alert/webhook)" }, "topupEnabled": { "type": "boolean", "description": "Whether crossing the threshold also auto-tops-up this wallet from a fund wallet on its source" }, "topupAmount": { "type": "string", "nullable": true, "description": "Amount to top up per trigger, in raw on-chain units. Null when auto top-up is off" }, "status": { "type": "string", "enum": [ "Unknown", "Healthy", "Low" ], "description": "Current deduped state of the rule" }, "lastKnownAmount": { "type": "string", "nullable": true, "description": "Last observed balance for this asset in raw on-chain units. Null if never checked" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the rule was last evaluated. Null if never checked" }, "lastAlertedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the wallet last entered low balance for this rule. Null if never alerted" }, "walletId": { "type": "string", "description": "Hot wallet id the rule belongs to" }, "walletVkey": { "type": "string", "description": "Wallet verification key" }, "walletAddress": { "type": "string", "description": "Wallet address" }, "walletType": { "type": "string", "enum": [ "Selling", "Purchasing", "Funding" ], "description": "Hot wallet type" }, "paymentSourceId": { "type": "string", "description": "Payment source id owning the wallet" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Wallet network" } }, "required": [ "id", "assetUnit", "thresholdAmount", "enabled", "topupEnabled", "topupAmount", "status", "lastKnownAmount", "lastCheckedAt", "lastAlertedAt", "walletId", "walletVkey", "walletAddress", "walletType", "paymentSourceId", "network" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "low_balance_rule_id", "assetUnit": "lovelace", "thresholdAmount": "5000000", "enabled": true, "topupEnabled": true, "topupAmount": "10000000", "status": "Low", "lastKnownAmount": "4200000", "lastCheckedAt": "1970-01-20T20:00:36.260Z", "lastAlertedAt": "1970-01-20T20:00:36.260Z", "walletId": "unique_cuid_v2_of_wallet", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "walletType": "Purchasing", "paymentSourceId": "payment_source_id", "network": "Preprod" } } } } } }, "400": { "description": "Invalid asset unit or auto top-up configuration" }, "404": { "description": "Wallet not found" }, "409": { "description": "Low-balance rule already exists for this wallet and asset" } } }, "patch": { "description": "Updates a wallet low-balance monitoring rule", "summary": "Update a wallet low-balance rule. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Low-balance rule update", "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Low-balance rule id to update" }, "thresholdAmount": { "type": "string", "pattern": "^\\d+$", "description": "Updated threshold in raw on-chain units" }, "enabled": { "type": "boolean", "description": "Updated enabled state" }, "topupEnabled": { "type": "boolean", "description": "Enable or disable auto top-up on this rule" }, "topupAmount": { "type": "string", "nullable": true, "pattern": "^[1-9]\\d*$", "description": "Updated top-up amount in raw on-chain units, or null to clear it while auto top-up is disabled. ADA requires at least 5000000 lovelace" } }, "required": [ "ruleId" ], "example": { "ruleId": "low_balance_rule_id", "thresholdAmount": "7000000", "enabled": true } } } } }, "responses": { "200": { "description": "Wallet low-balance rule updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the low-balance rule" }, "assetUnit": { "type": "string", "description": "Raw on-chain asset unit, for example lovelace or a full policy+asset identifier" }, "thresholdAmount": { "type": "string", "description": "Threshold in raw on-chain units used to determine low balance" }, "enabled": { "type": "boolean", "description": "Whether the rule is active (fires the low-balance alert/webhook)" }, "topupEnabled": { "type": "boolean", "description": "Whether crossing the threshold also auto-tops-up this wallet from a fund wallet on its source" }, "topupAmount": { "type": "string", "nullable": true, "description": "Amount to top up per trigger, in raw on-chain units. Null when auto top-up is off" }, "status": { "type": "string", "enum": [ "Unknown", "Healthy", "Low" ], "description": "Current deduped state of the rule" }, "lastKnownAmount": { "type": "string", "nullable": true, "description": "Last observed balance for this asset in raw on-chain units. Null if never checked" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the rule was last evaluated. Null if never checked" }, "lastAlertedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the wallet last entered low balance for this rule. Null if never alerted" }, "walletId": { "type": "string", "description": "Hot wallet id the rule belongs to" }, "walletVkey": { "type": "string", "description": "Wallet verification key" }, "walletAddress": { "type": "string", "description": "Wallet address" }, "walletType": { "type": "string", "enum": [ "Selling", "Purchasing", "Funding" ], "description": "Hot wallet type" }, "paymentSourceId": { "type": "string", "description": "Payment source id owning the wallet" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Wallet network" } }, "required": [ "id", "assetUnit", "thresholdAmount", "enabled", "topupEnabled", "topupAmount", "status", "lastKnownAmount", "lastCheckedAt", "lastAlertedAt", "walletId", "walletVkey", "walletAddress", "walletType", "paymentSourceId", "network" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "low_balance_rule_id", "assetUnit": "lovelace", "thresholdAmount": "7000000", "enabled": true, "topupEnabled": true, "topupAmount": "10000000", "status": "Low", "lastKnownAmount": "4200000", "lastCheckedAt": "1970-01-20T20:00:36.260Z", "lastAlertedAt": "1970-01-20T20:00:36.260Z", "walletId": "unique_cuid_v2_of_wallet", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "walletType": "Purchasing", "paymentSourceId": "payment_source_id", "network": "Preprod" } } } } } }, "400": { "description": "No changes were requested, or the auto top-up configuration is invalid" }, "404": { "description": "Low-balance rule not found" } } }, "delete": { "description": "Deletes a wallet low-balance monitoring rule", "summary": "Delete a wallet low-balance rule. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Low-balance rule to delete", "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Low-balance rule id to delete" } }, "required": [ "ruleId" ], "example": { "ruleId": "low_balance_rule_id" } } } } }, "responses": { "200": { "description": "Wallet low-balance rule deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "ruleId": { "type": "string", "description": "Deleted rule id" }, "deletedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the rule was deleted" } }, "required": [ "ruleId", "deletedAt" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "ruleId": "low_balance_rule_id", "deletedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "404": { "description": "Low-balance rule not found" } } } }, "/signature/verify/reveal-data": { "post": { "description": "Verifies the reveal data signature is valid.", "summary": "Verifies the reveal data signature is valid. (read access required)", "tags": [ "signature" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "maxLength": 7500, "description": "Cryptographic signature from the admin wallet" }, "key": { "type": "string", "maxLength": 2500, "description": "Public key used to create the signature" }, "walletAddress": { "type": "string", "minLength": 58, "maxLength": 250, "pattern": "^(addr1|addr_test1)[0-9a-z]+$", "description": "Cardano address of the admin wallet signing the request" }, "validUntil": { "type": "number", "minimum": 0, "maximum": 1000000000000000000, "description": "Unix timestamp (in milliseconds) until which this signature is valid" }, "blockchainIdentifier": { "type": "string", "minLength": 1, "maxLength": 2500, "description": "The blockchain identifier, for which the data should be revealed" }, "action": { "type": "string", "enum": [ "RevealData" ], "description": "The action to perform" } }, "required": [ "signature", "key", "walletAddress", "validUntil", "blockchainIdentifier", "action" ], "example": { "action": "RevealData", "blockchainIdentifier": "blockchain_identifier", "signature": "signature", "key": "key", "walletAddress": "wallet_address", "validUntil": 1713636260 } } } } }, "responses": { "200": { "description": "Revealed data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "isValid": { "type": "boolean", "description": "Whether the signature is valid and the data can be revealed" } }, "required": [ "isValid" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "isValid": true } } } } } }, "400": { "description": "Bad Request (invalid signature or payment is not disputable)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (network not allowed)" }, "404": { "description": "Payment not found" }, "500": { "description": "Internal Server Error" } } } }, "/api-key": { "get": { "description": "Gets api key status", "summary": "Get information about all API keys. (admin access required)", "tags": [ "api-key" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of API keys to return" }, "required": false, "description": "The number of API keys to return", "name": "take", "in": "query" }, { "schema": { "type": "string", "maxLength": 550, "description": "Used to paginate through the API keys (provide the id of the last returned key)" }, "required": false, "description": "Used to paginate through the API keys (provide the id of the last returned key)", "name": "cursorId", "in": "query" } ], "responses": { "200": { "description": "Api key status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "ApiKeys": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" }, "description": "List of API keys" } }, "required": [ "ApiKeys" ] } }, "required": [ "status", "data" ], "example": { "data": { "ApiKeys": [ { "id": "api_key_id", "token": "masumi_payment_api_key_secret", "permission": "Admin", "canRead": true, "canPay": true, "canAdmin": true, "usageLimited": true, "NetworkLimit": [ "Preprod" ], "ChainIdLimit": [ "cardano:preprod" ], "RemainingUsageCredits": [ { "unit": "", "amount": "10000000" } ], "status": "Active", "walletScopeEnabled": false, "WalletScopes": [], "x402WalletScopeEnabled": false, "X402WalletScopes": [] } ] }, "status": "Success" } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "post": { "description": "Creates a API key", "summary": "Create a new API key. (admin access required)", "tags": [ "api-key" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "usageLimited": { "type": "string", "description": "Whether the API key is usage limited. Meaning only allowed to use the specified credits or can freely spend. Omitted defaults to true for non-admin keys; admin keys are never usage limited." }, "UsageCredits": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 150, "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA); \"lovelace\" is accepted and stored as the empty string. For x402/EVM spending the unit is chain-qualified as \":\" (lowercased), e.g. \"eip155:8453:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913\". Gas-token units are not supported." }, "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" } }, "required": [ "unit", "amount" ] }, "description": "The credits allowed to be used by the API key. Only relevant if usageLimited is true. " }, "NetworkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "maxItems": 3, "default": [ "Mainnet", "Preprod" ], "description": "The Cardano networks the API key is allowed to use" }, "ChainIdLimit": { "type": "array", "items": { "type": "string", "pattern": "^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$" }, "maxItems": 50, "description": "Additional non-Cardano CAIP-2 chain identifiers the API key is allowed to use. Omit to grant every configured EVM chain, mirroring NetworkLimit defaulting to all Cardano networks; pass an empty array to grant none." }, "permission": { "type": "string", "enum": [ "Read", "ReadAndPay", "Admin" ], "description": "[DEPRECATED] The permission of the API key. Use canRead/canPay/canAdmin flags instead. Will be removed in a future version. Omitted means read-only; sending it together with contradictory canRead/canPay/canAdmin flags is rejected." }, "canRead": { "type": "boolean", "description": "Whether this API key can access read endpoints" }, "canPay": { "type": "boolean", "description": "Whether this API key can access payment/purchase endpoints" }, "canAdmin": { "type": "boolean", "description": "Whether this API key has admin access" }, "walletScopeEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "default": false, "description": "Whether to enable wallet scope filtering for this API key" }, "WalletScopeHotWalletIds": { "type": "array", "items": { "type": "string", "maxLength": 150 }, "maxItems": 100, "default": [], "description": "List of hot wallet IDs to scope this API key to" }, "x402WalletScopeEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "default": false, "description": "Whether to enable managed EVM wallet scope filtering. False leaves the key unrestricted, matching walletScopeEnabled." }, "X402WalletScopeEvmWalletIds": { "type": "array", "items": { "type": "string", "maxLength": 150 }, "maxItems": 100, "default": [], "description": "Managed EVM wallet IDs to scope this API key to. Only applied when x402WalletScopeEnabled is true; the key also always reaches wallets it created itself." } }, "required": [ "UsageCredits" ], "example": { "usageLimited": "true", "UsageCredits": [ { "unit": "", "amount": "10000000" } ], "canAdmin": true, "walletScopeEnabled": "false", "WalletScopeHotWalletIds": [] } } } } }, "responses": { "200": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/APIKey" }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "api_key_id", "token": "masumi_payment_api_key_secret", "permission": "Admin", "canRead": true, "canPay": true, "canAdmin": true, "usageLimited": true, "NetworkLimit": [ "Preprod" ], "ChainIdLimit": [ "cardano:preprod" ], "RemainingUsageCredits": [ { "unit": "", "amount": "10000000" } ], "status": "Active", "walletScopeEnabled": false, "WalletScopes": [], "x402WalletScopeEnabled": false, "X402WalletScopes": [] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "patch": { "description": "Creates a API key", "summary": "Update an existing API key. (admin access required)", "tags": [ "api-key" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 150, "description": "The id of the API key to update. Provide either id or apiKey" }, "token": { "type": "string", "minLength": 15, "maxLength": 550, "description": "To change the api key token" }, "UsageCreditsToAddOrRemove": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 150, "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA); \"lovelace\" is accepted and stored as the empty string. For x402/EVM spending the unit is chain-qualified as \":\" (lowercased), e.g. \"eip155:8453:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913\". Gas-token units are not supported." }, "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" } }, "required": [ "unit", "amount" ] }, "maxItems": 25, "description": "The amount of credits to add or remove from the API key. Only relevant if usageLimited is true. " }, "usageLimited": { "type": "boolean", "description": "Whether the API key is usage limited. Omit to leave it unchanged." }, "status": { "type": "string", "enum": [ "Active", "Revoked" ], "description": "The status of the API key. Omit to leave it unchanged." }, "NetworkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "maxItems": 3, "description": "Replaces the Cardano-network half of the access list. Omit to leave Cardano access unchanged." }, "ChainIdLimit": { "type": "array", "items": { "type": "string", "pattern": "^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$" }, "maxItems": 50, "description": "Replaces the EVM (CAIP-2) half of the access list. Omit to leave EVM access unchanged." }, "walletScopeEnabled": { "type": "boolean", "description": "Whether to enable wallet scope filtering for this API key" }, "x402WalletScopeEnabled": { "type": "boolean", "description": "Whether to enable managed EVM wallet scope filtering for this API key" }, "X402WalletScopeEvmWalletIds": { "type": "array", "items": { "type": "string", "maxLength": 150 }, "maxItems": 100, "description": "Replaces the managed EVM wallets this API key is scoped to" }, "WalletScopeHotWalletIds": { "type": "array", "items": { "type": "string", "maxLength": 150 }, "maxItems": 100, "description": "List of hot wallet IDs to scope this API key to. Replaces existing scopes when provided" }, "canRead": { "type": "boolean", "description": "Whether this API key can access read endpoints" }, "canPay": { "type": "boolean", "description": "Whether this API key can access payment/purchase endpoints" }, "canAdmin": { "type": "boolean", "description": "Whether this API key has admin access" } }, "required": [ "id" ], "example": { "id": "unique_cuid_v2_of_entry_to_update", "token": "api_key_to_change_to", "UsageCreditsToAddOrRemove": [ { "unit": "", "amount": "10000000" }, { "unit": "c48cbb3d5e57ed56e276bc45f99ab39abe94e6cd7ac39fb402da47ad0014df105553444d", "amount": "-25000000" } ], "status": "Active", "walletScopeEnabled": false, "WalletScopeHotWalletIds": [ "hot_wallet_id_1", "hot_wallet_id_2" ] } } } } }, "responses": { "200": { "description": "API key updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/APIKey" }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "api_key_id", "token": "masumi_payment_api_key_secret", "permission": "Admin", "canRead": true, "canPay": true, "canAdmin": true, "usageLimited": true, "NetworkLimit": [ "Preprod", "Mainnet" ], "ChainIdLimit": [ "cardano:preprod" ], "RemainingUsageCredits": [ { "unit": "", "amount": "10000000" } ], "status": "Active", "walletScopeEnabled": false, "WalletScopes": [], "x402WalletScopeEnabled": false, "X402WalletScopes": [] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "delete": { "description": "Removes a API key", "summary": "Delete an existing API key. (admin access required)", "tags": [ "api-key" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 150, "description": "The id of the API key to be (soft) deleted." } }, "required": [ "id" ], "example": { "id": "id_or_apiKey_unique_cuid_v2_of_entry_to_delete" } } } } }, "responses": { "200": { "description": "API key deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/APIKey" }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "api_key_id", "token": "masumi_payment_api_key_secret", "permission": "Admin", "canRead": true, "canPay": true, "canAdmin": true, "usageLimited": true, "NetworkLimit": [ "Preprod" ], "ChainIdLimit": [ "cardano:preprod" ], "RemainingUsageCredits": [ { "unit": "", "amount": "10000000" } ], "status": "Revoked", "walletScopeEnabled": false, "WalletScopes": [], "x402WalletScopeEnabled": false, "X402WalletScopes": [] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/swap": { "post": { "description": "Swap ADA for CNTs (Cardano Native Tokens) or CNTs for ADA using SundaeSwap DEX. This endpoint is mainnet-only.", "summary": "Execute a token swap on SundaeSwap. (admin access required, mainnet only)", "tags": [ "swap" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Swap request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "walletVkey": { "type": "string", "minLength": 56, "maxLength": 56, "pattern": "^[0-9a-fA-F]{56}$", "description": "Wallet verification key (vKey) to identify the wallet" }, "amount": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000000, "description": "Amount to swap (in ADA or token units). Capped to prevent overflow/DoS." }, "FromToken": { "type": "object", "properties": { "policyId": { "type": "string", "description": "Policy ID of the source token. Use empty string \"\" for ADA (native token)" }, "assetName": { "type": "string", "description": "Asset name of the source token. Use empty string \"\" for ADA" }, "name": { "type": "string", "description": "Name of the source token" } }, "required": [ "policyId", "assetName", "name" ], "description": "Source token information" }, "ToToken": { "type": "object", "properties": { "policyId": { "type": "string", "description": "Policy ID of the destination token. Use empty string \"\" for ADA (native token)" }, "assetName": { "type": "string", "description": "Asset name of the destination token. Use empty string \"\" for ADA" }, "name": { "type": "string", "description": "Name of the destination token" } }, "required": [ "policyId", "assetName", "name" ], "description": "Destination token information" }, "poolId": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[0-9a-zA-Z]+$", "description": "SundaeSwap pool identifier" }, "slippage": { "type": "number", "minimum": 0, "maximum": 1, "description": "Slippage tolerance (0-1, default: 0.03 for 3%)" } }, "required": [ "walletVkey", "amount", "FromToken", "ToToken", "poolId" ], "example": { "walletVkey": "wallet_verification_key_here", "amount": 1, "FromToken": { "policyId": "c48cbb3d5e57ed56e276bc45f99ab39abe94e6cd7ac39fb402da47ad", "assetName": "5553444d", "name": "USDM" }, "ToToken": { "policyId": "c48cbb3d5e57ed56e276bc45f99ab39abe94e6cd7ac39fb402da47ad", "assetName": "5553444d", "name": "USDM" }, "poolId": "64f35d26b237ad58e099041bc14c687ea7fdc58969d7d5b66e2540ef", "slippage": 0.03 } } } } }, "responses": { "200": { "description": "Swap executed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "txHash": { "type": "string", "description": "Transaction hash of the swap" }, "walletAddress": { "type": "string", "description": "Wallet address used for the swap" } }, "required": [ "txHash", "walletAddress" ], "example": { "txHash": "abc123def456...", "walletAddress": "addr1..." } } } } }, "400": { "description": "Bad Request (missing or invalid parameters)" }, "401": { "description": "Unauthorized (invalid API key or insufficient permissions)" }, "500": { "description": "Internal Server Error (swap failed)" } } } }, "/swap/confirm": { "get": { "description": "Check on-chain confirmation status of a swap transaction by transaction hash. Use after POST /swap/ to poll until status is confirmed. Mainnet only.", "summary": "Get swap transaction confirmation status. (admin access required, mainnet only)", "tags": [ "swap" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-fA-F]{64}$", "description": "Transaction hash to check" }, "required": true, "description": "Transaction hash to check", "name": "txHash", "in": "query" }, { "schema": { "type": "string", "minLength": 56, "maxLength": 56, "pattern": "^[0-9a-fA-F]{56}$", "description": "Wallet verification key (vKey) that submitted the swap" }, "required": true, "description": "Wallet verification key (vKey) that submitted the swap", "name": "walletVkey", "in": "query" } ], "responses": { "200": { "description": "Confirmation status (Pending, Confirmed, or NotFound)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Pending", "Confirmed", "NotFound" ], "description": "On-chain status: Pending (not yet in a block), Confirmed (in a block), NotFound (tx unknown)" }, "swapStatus": { "type": "string", "description": "Swap lifecycle status (OrderPending, OrderConfirmed, CancelPending, CancelConfirmed, Completed)" }, "swapTransactionId": { "type": "string", "description": "SwapTransaction ID, returned when lifecycle transition occurs" }, "confirmations": { "type": "integer", "nullable": true, "minimum": 0, "description": "Number of block confirmations. Present when status is confirmed." } }, "required": [ "status" ], "example": { "status": "Confirmed", "swapStatus": "OrderConfirmed", "confirmations": 15 } } } } }, "400": { "description": "Bad Request (e.g. mainnet wallet required)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Wallet not found" } } } }, "/swap/transactions": { "get": { "description": "List swap transactions for a wallet, ordered by most recent first. Supports cursor-based pagination.", "summary": "List swap transactions. (admin access required, mainnet only)", "tags": [ "swap" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 56, "maxLength": 56, "pattern": "^[0-9a-fA-F]{56}$", "description": "Wallet verification key (vKey) to filter swap transactions" }, "required": true, "description": "Wallet verification key (vKey) to filter swap transactions", "name": "walletVkey", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "Number of swap transactions to return" }, "required": false, "description": "Number of swap transactions to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 64, "description": "Cursor ID for pagination" }, "required": false, "description": "Cursor ID for pagination", "name": "cursorId", "in": "query" } ], "responses": { "200": { "description": "List of swap transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "SwapTransactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Swap transaction ID" }, "createdAt": { "type": "string", "description": "Creation timestamp" }, "txHash": { "type": "string", "nullable": true, "description": "On-chain transaction hash" }, "status": { "type": "string", "description": "Transaction status" }, "swapStatus": { "type": "string", "description": "Swap lifecycle status (OrderPending, OrderConfirmed, CancelPending, CancelConfirmed, Completed)" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations" }, "fromPolicyId": { "type": "string", "description": "Source token policy ID" }, "fromAssetName": { "type": "string", "description": "Source token asset name" }, "fromAmount": { "type": "string", "description": "Amount swapped" }, "toPolicyId": { "type": "string", "description": "Destination token policy ID" }, "toAssetName": { "type": "string", "description": "Destination token asset name" }, "poolId": { "type": "string", "description": "SundaeSwap pool ID" }, "slippage": { "type": "number", "nullable": true, "description": "Slippage tolerance used" }, "cancelTxHash": { "type": "string", "nullable": true, "description": "Transaction hash of cancel transaction" }, "orderOutputIndex": { "type": "number", "nullable": true, "description": "Output index of the order UTXO" } }, "required": [ "id", "createdAt", "txHash", "status", "swapStatus", "fromPolicyId", "fromAssetName", "fromAmount", "toPolicyId", "toAssetName", "poolId" ] }, "description": "List of swap transactions" } }, "required": [ "SwapTransactions" ], "example": { "SwapTransactions": [ { "id": "clx1abc...", "createdAt": "2026-03-06T12:00:00.000Z", "txHash": "abc123def456...", "status": "Confirmed", "swapStatus": "Completed", "confirmations": 15, "fromPolicyId": "", "fromAssetName": "", "fromAmount": "10", "toPolicyId": "c48cbb3d5e57ed56e276bc45f99ab39abe94e6cd7ac39fb402da47ad", "toAssetName": "0014df105553444d", "poolId": "pool_id_here", "slippage": 0.03, "cancelTxHash": null, "orderOutputIndex": null } ] } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Wallet not found" } } } }, "/swap/estimate": { "get": { "description": "Get a swap price estimate from the SundaeSwap pool. Returns the conversion rate based on current pool reserves.", "summary": "Get swap price estimate. (admin access required, mainnet only)", "tags": [ "swap" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 56, "pattern": "^[0-9a-fA-F]*$", "description": "Policy ID of the source token. Use empty string \"\" for ADA" }, "required": true, "description": "Policy ID of the source token. Use empty string \"\" for ADA", "name": "fromPolicyId", "in": "query" }, { "schema": { "type": "string", "maxLength": 64, "pattern": "^[0-9a-fA-F]*$", "description": "Asset name (hex) of the source token. Use empty string \"\" for ADA" }, "required": true, "description": "Asset name (hex) of the source token. Use empty string \"\" for ADA", "name": "fromAssetName", "in": "query" }, { "schema": { "type": "string", "maxLength": 56, "pattern": "^[0-9a-fA-F]*$", "description": "Policy ID of the destination token. Use empty string \"\" for ADA" }, "required": true, "description": "Policy ID of the destination token. Use empty string \"\" for ADA", "name": "toPolicyId", "in": "query" }, { "schema": { "type": "string", "maxLength": 64, "pattern": "^[0-9a-fA-F]*$", "description": "Asset name (hex) of the destination token. Use empty string \"\" for ADA" }, "required": true, "description": "Asset name (hex) of the destination token. Use empty string \"\" for ADA", "name": "toAssetName", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[0-9a-zA-Z]+$", "description": "SundaeSwap pool identifier" }, "required": true, "description": "SundaeSwap pool identifier", "name": "poolId", "in": "query" } ], "responses": { "200": { "description": "Swap estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "rate": { "type": "number", "description": "Estimated conversion rate (toToken per 1 fromToken, after pool fee)" }, "fee": { "type": "number", "description": "Pool fee as a decimal (e.g. 0.003 for 0.3%)" }, "fromDecimals": { "type": "number", "description": "Decimal places of the source token" }, "toDecimals": { "type": "number", "description": "Decimal places of the destination token" } }, "required": [ "rate", "fee", "fromDecimals", "toDecimals" ], "example": { "rate": 2.45, "fee": 0.003, "fromDecimals": 6, "toDecimals": 6 } } } } }, "400": { "description": "Bad request (invalid pool or token)" }, "401": { "description": "Unauthorized" } } } }, "/swap/cancel": { "post": { "description": "Cancel a pending SundaeSwap order that is sitting at the script address. Only orders in OrderConfirmed state can be cancelled.", "summary": "Cancel a pending swap order. (admin access required, mainnet only)", "tags": [ "swap" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Cancel swap request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "walletVkey": { "type": "string", "minLength": 56, "maxLength": 56, "pattern": "^[0-9a-fA-F]{56}$", "description": "Wallet verification key (vKey) of the wallet that placed the order" }, "swapTransactionId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "ID of the SwapTransaction to cancel" } }, "required": [ "walletVkey", "swapTransactionId" ], "example": { "walletVkey": "wallet_verification_key_here", "swapTransactionId": "clx1abc..." } } } } }, "responses": { "200": { "description": "Cancel transaction submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelTxHash": { "type": "string", "description": "Transaction hash of the cancel transaction" } }, "required": [ "cancelTxHash" ], "example": { "cancelTxHash": "abc123def456..." } } } } }, "400": { "description": "Bad Request (swap not in cancellable state)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Swap transaction or wallet not found" }, "409": { "description": "Wallet is currently locked" } } } }, "/swap/acknowledge-timeout": { "post": { "description": "Acknowledge a timed-out swap transaction. Checks on-chain state and recovers to the correct status: OrderConfirmed if the order UTXO still exists (allowing retry), Completed if the DEX executed the swap, or keeps the timeout state if the order tx never confirmed.", "summary": "Acknowledge a swap timeout and recover state. (admin access required, mainnet only)", "tags": [ "swap" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Acknowledge timeout request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "walletVkey": { "type": "string", "minLength": 56, "maxLength": 56, "pattern": "^[0-9a-fA-F]{56}$", "description": "Wallet verification key (vKey) of the wallet" }, "swapTransactionId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "ID of the timed-out SwapTransaction" } }, "required": [ "walletVkey", "swapTransactionId" ], "example": { "walletVkey": "wallet_verification_key_here", "swapTransactionId": "clx1abc..." } } } } }, "responses": { "200": { "description": "Timeout acknowledged, state recovered", "content": { "application/json": { "schema": { "type": "object", "properties": { "swapStatus": { "type": "string", "description": "New swap status after acknowledgement" }, "message": { "type": "string", "description": "Human-readable explanation of what happened" } }, "required": [ "swapStatus", "message" ], "example": { "swapStatus": "OrderConfirmed", "message": "Cancel tx failed but order UTXO still exists. You can retry cancelling." } } } } }, "400": { "description": "Bad Request (swap not in timeout state)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Swap transaction or wallet not found" } } } }, "/wallet/transfer-funds": { "post": { "description": "Queues an asynchronous transfer of lovelace (and optional native assets) from a hot wallet to a target Cardano address. The transfer is picked up by the background processor once the wallet is free. Poll GET /wallet/transfer-funds to check status.", "summary": "Queue a fund transfer from a wallet. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Fund transfer request", "content": { "application/json": { "schema": { "type": "object", "properties": { "fromWalletAddress": { "type": "string", "minLength": 1, "maxLength": 250, "description": "The Cardano address of the hot wallet to send funds from" }, "toAddress": { "type": "string", "minLength": 1, "maxLength": 250, "description": "The Cardano address to send funds to" }, "lovelaceAmount": { "type": "string", "maxLength": 20, "pattern": "^[1-9][0-9]*$", "description": "Amount of lovelace to transfer (minimum 2000000 = 2 ADA)" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "pattern": "^[0-9a-fA-F]{56}(?:[0-9a-fA-F]{2}){0,32}$", "description": "Asset unit: policy id (56 hex chars) followed by the hex asset name. Not \"lovelace\"." }, "quantity": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Amount of the asset to transfer, in its smallest unit" } }, "required": [ "unit", "quantity" ] }, "maxItems": 10, "description": "Additional native assets to transfer alongside lovelace" } }, "required": [ "fromWalletAddress", "toAddress", "lovelaceAmount" ], "example": { "fromWalletAddress": "addr_test1qx9...source_wallet_address", "toAddress": "addr_test1qz8x...destination_address", "lovelaceAmount": "100000000" } } } } }, "responses": { "200": { "description": "Fund transfer queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/WalletFundTransfer" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "unique_cuid_v2_of_fund_transfer", "status": "Confirmed", "txHash": "a3f8c12d9e4b71d2f0e5c8a9b3d6e7f1a2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8", "toAddress": "addr_test1qz8x...purchasing_wallet_address", "lovelaceAmount": "100000000", "assets": null, "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": "1970-01-20T20:00:36.260Z", "errorNote": null } } } } } }, "400": { "description": "Bad Request (lovelaceAmount below 2 ADA minimum)" }, "404": { "description": "Not Found (wallet not found)" } } }, "get": { "description": "Query the status of a fund transfer by id, or list all fund transfers for a wallet. Poll this endpoint after posting to /wallet/transfer-funds. Status values: Pending (queued or submitted), Confirmed (on-chain), FailedViaManualReset (submission error), FailedViaTimeout (no confirmation within timeout).", "summary": "Get fund transfer status or history. (admin access required)", "tags": [ "wallet" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Query a specific fund transfer by id" }, "required": false, "description": "Query a specific fund transfer by id", "name": "id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Query all fund transfers for a wallet by internal id" }, "required": false, "description": "Query all fund transfers for a wallet by internal id", "name": "hotWalletId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Query all fund transfers for a wallet by its Cardano address" }, "required": false, "description": "Query all fund transfers for a wallet by its Cardano address", "name": "walletAddress", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Cursor for pagination" }, "required": false, "description": "Cursor for pagination", "name": "cursorId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of results to return (1-100, default 20)" }, "required": false, "description": "Number of results to return (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Fund transfer list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/WalletFundTransferList" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "transfers": [ { "id": "unique_cuid_v2_of_fund_transfer", "status": "Confirmed", "txHash": "a3f8c12d9e4b71d2f0e5c8a9b3d6e7f1a2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8", "toAddress": "addr_test1qz8x...purchasing_wallet_address", "lovelaceAmount": "100000000", "assets": null, "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": "1970-01-20T20:00:36.260Z", "errorNote": null } ] } } } } } }, "404": { "description": "Fund transfer not found" } } } }, "/payment": { "get": { "description": "Gets the payment status. It needs to be created first with a POST request.", "summary": "Get information about a payment request. (READ access required)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of payments to return" }, "required": false, "description": "The number of payments to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Used to paginate through the payments. If this is provided, cursorId is required" }, "required": false, "description": "Used to paginate through the payments. If this is provided, cursorId is required", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the payments were made on" }, "required": true, "description": "The network the payments were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ], "description": "Filter by on-chain state" }, "required": false, "description": "Filter by on-chain state", "name": "filterOnChainState", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment list/count endpoints default to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment list/count endpoints default to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" }, { "schema": { "type": "string", "description": "When true, only returns payments that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it" }, "required": false, "description": "When true, only returns payments that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it", "name": "filterNeedsManualAction", "in": "query" }, { "schema": { "type": "string", "maxLength": 5020, "description": "Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing." }, "required": false, "description": "Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing.", "name": "filterAgentIdentifier", "in": "query" }, { "schema": { "type": "string", "maxLength": 500, "description": "Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer (\"L1\", \"L2\" or \"hydra\"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and \"%\" and \"_\" are matched literally." }, "required": false, "description": "Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer (\"L1\", \"L2\" or \"hydra\"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and \"%\" and \"_\" are matched literally.", "name": "searchQuery", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the full transaction and action history of the payments" }, "required": false, "description": "Whether to include the full transaction and action history of the payments", "name": "includeHistory", "in": "query" } ], "responses": { "200": { "description": "Payment status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } }, "required": [ "Payments" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Payments": [ { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "forceLayer": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "RequestedFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address", "policyId": "policy_id" }, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "TransactionHistory": [] } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "post": { "description": "Creates a payment request and identifier. This will check incoming payments in the background.", "summary": "Create a new payment request. (+PAY access required)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "inputHash": { "type": "string", "maxLength": 250, "description": "The hash of the input data of the payment, should be sha256 hash of the input data, therefore needs to be in hex string format" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the payment will be received on" }, "agentIdentifier": { "type": "string", "minLength": 57, "maxLength": 250, "description": "The identifier of the agent that will be paid" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Expected payment source type for this request" }, "supportedPaymentSourceIndex": { "type": "integer", "minimum": 0, "maximum": 24, "description": "Required for V2 Cardano payments and forbidden for V1. Selects the independently-priced source by its index in supported_payment_sources." }, "RequestedFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Amount of the asset in smallest unit (e.g., lovelace for ADA)" }, "unit": { "type": "string", "maxLength": 150, "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "maxItems": 7, "description": "The amounts of the payment, should be null for fixed amount" }, "payByTime": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "default": "1970-01-01T12:00:00.000Z", "description": "The time after which the payment has to be submitted to the smart contract" }, "submitResultTime": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "default": "1970-01-01T12:00:00.000Z", "description": "The time after which the payment has to be submitted to the smart contract" }, "unlockTime": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "description": "The time after which the payment will be unlocked" }, "externalDisputeUnlockTime": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "description": "The time after which the payment will be unlocked for external dispute" }, "metadata": { "type": "string", "description": "Metadata to be stored with the payment request" }, "sellerReturnAddress": { "type": "string", "maxLength": 250, "description": "Optional seller return address. Defaults to the selling hot wallet collection address when available." }, "identifierFromPurchaser": { "type": "string", "minLength": 14, "maxLength": 26, "description": "A unique nonce from the purchaser. It must be in hex format" }, "forceLayer": { "type": "string", "enum": [ "L1", "Hydra" ], "description": "Optional seller layer override. For V2 this choice is signed into the purchase terms: \"Hydra\" requires an open head, \"L1\" forces L1, and a conflict with the buyer's forceLayer is rejected. Hydra is not supported for V1. Omit for automatic routing." } }, "required": [ "inputHash", "network", "agentIdentifier", "identifierFromPurchaser" ], "example": { "agentIdentifier": "agent_identifier", "network": "Preprod", "inputHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "payByTime": "1970-01-20T20:00:26.260Z", "metadata": "(private) metadata to be stored with the payment request", "submitResultTime": "1970-01-20T20:00:36.260Z", "identifierFromPurchaser": "aabbaabb11221122aabb" } } } } }, "responses": { "200": { "description": "Payment request created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the payment" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being paid" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the payment was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "requestedById": { "type": "string", "description": "ID of the API key that created this payment" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "inputHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the input data for the payment (hex string)" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the payment on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Caller-specified layer override recorded on this payment. \"L1\" or \"Hydra\", or null for automatic routing (Hydra if available, else L1)." }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ], "description": "Next action required for this payment" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result to be submitted (hex string). Null if not applicable" } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ], "description": "Next action required for this payment" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "fees": { "type": "string", "nullable": true }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "fees", "blockHeight", "blockTime", "txHash", "status", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this payment. Null if no transaction in progress" }, "RequestedFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the seller" }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the buyer (refunds)" }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment source" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network (Mainnet, Preprod, or Preview)" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Payment source type for adapter dispatch" }, "smartContractAddress": { "type": "string", "description": "Address of the smart contract managing this payment" }, "policyId": { "type": "string", "nullable": true, "description": "Policy ID for the agent registry NFTs. Null if not applicable" } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ], "description": "Payment source configuration for this payment" }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the buyer wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the buyer wallet" } }, "required": [ "id", "walletVkey" ], "description": "Buyer wallet information. Null if buyer has not yet submitted payment" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this payment. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the payment for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "externalDisputeUnlockTime", "requestedById", "resultHash", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "nextActionOrOnChainStateOrResultLastChangedAt", "inputHash", "totalBuyerCardanoFees", "totalSellerCardanoFees", "cooldownTime", "cooldownTimeOtherParty", "onChainState", "forceLayer", "NextAction", "CurrentTransaction", "RequestedFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "BuyerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "forceLayer": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "RequestedFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address", "policyId": "policy_id" }, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/payment/diff": { "get": { "description": "Returns payments that changed since the provided timestamp (combined next-action + on-chain-state/result).", "summary": "Diff payments by combined status timestamp (READ access required)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of payments to return" }, "required": false, "description": "The number of payments to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor (payment id). Used as tie-breaker when lastUpdate equals a payment change timestamp" }, "required": false, "description": "Pagination cursor (payment id). Used as tie-breaker when lastUpdate equals a payment change timestamp", "name": "cursorId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "default": "1970-01-01T00:00:00.000Z", "description": "Return payments whose selected status timestamp changed after this ISO timestamp" }, "required": false, "description": "Return payments whose selected status timestamp changed after this ISO timestamp", "name": "lastUpdate", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the payments were made on" }, "required": true, "description": "The network the payments were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment diff endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment diff endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment diff endpoints default to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment diff endpoints default to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the full transaction and status history of the payments" }, "required": false, "description": "Whether to include the full transaction and status history of the payments", "name": "includeHistory", "in": "query" } ], "responses": { "200": { "description": "Payment diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } }, "required": [ "Payments" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Payments": [ { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "forceLayer": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "RequestedFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address", "policyId": "policy_id" }, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "TransactionHistory": [] } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/payment/diff/next-action": { "get": { "description": "Returns payments whose next action changed since lastUpdate.", "summary": "Diff payments by next-action timestamp (READ access required)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of payments to return" }, "required": false, "description": "The number of payments to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor (payment id). Used as tie-breaker when lastUpdate equals a payment change timestamp" }, "required": false, "description": "Pagination cursor (payment id). Used as tie-breaker when lastUpdate equals a payment change timestamp", "name": "cursorId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "default": "1970-01-01T00:00:00.000Z", "description": "Return payments whose selected status timestamp changed after this ISO timestamp" }, "required": false, "description": "Return payments whose selected status timestamp changed after this ISO timestamp", "name": "lastUpdate", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the payments were made on" }, "required": true, "description": "The network the payments were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment diff endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment diff endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment diff endpoints default to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment diff endpoints default to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the full transaction and status history of the payments" }, "required": false, "description": "Whether to include the full transaction and status history of the payments", "name": "includeHistory", "in": "query" } ], "responses": { "200": { "description": "Payment diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } }, "required": [ "Payments" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Payments": [ { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "forceLayer": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "RequestedFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address", "policyId": "policy_id" }, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "TransactionHistory": [] } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/payment/count": { "get": { "description": "Gets the total count of payments.", "summary": "Get the total number of payments. (READ access required)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the payments were made on" }, "required": true, "description": "The network the payments were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "description": "When true, only counts payments that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it" }, "required": false, "description": "When true, only counts payments that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it", "name": "filterNeedsManualAction", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment count defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment count defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment count defaults to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment count defaults to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" }, { "schema": { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ], "description": "Filter by on-chain state" }, "required": false, "description": "Filter by on-chain state", "name": "filterOnChainState", "in": "query" }, { "schema": { "type": "string", "maxLength": 5020, "description": "Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing." }, "required": false, "description": "Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing.", "name": "filterAgentIdentifier", "in": "query" }, { "schema": { "type": "string", "maxLength": 500, "description": "Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer (\"L1\", \"L2\" or \"hydra\"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and \"%\" and \"_\" are matched literally." }, "required": false, "description": "Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer (\"L1\", \"L2\" or \"hydra\"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and \"%\" and \"_\" are matched literally.", "name": "searchQuery", "in": "query" } ], "responses": { "200": { "description": "Total payments count", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of payments" } }, "required": [ "total" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "total": 150 } } } } } } } } }, "/purchase/count": { "get": { "description": "Gets the total count of purchases.", "summary": "Get the total number of purchases. (READ access required)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the purchases were made on" }, "required": true, "description": "The network the purchases were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "description": "When true, only counts purchases that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it" }, "required": false, "description": "When true, only counts purchases that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it", "name": "filterNeedsManualAction", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, purchase count defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, purchase count defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, purchase count defaults to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, purchase count defaults to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" }, { "schema": { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ], "description": "Filter by on-chain state" }, "required": false, "description": "Filter by on-chain state", "name": "filterOnChainState", "in": "query" }, { "schema": { "type": "string", "maxLength": 5020, "description": "Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing." }, "required": false, "description": "Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing.", "name": "filterAgentIdentifier", "in": "query" }, { "schema": { "type": "string", "maxLength": 500, "description": "Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer (\"L1\", \"L2\" or \"hydra\"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and \"%\" and \"_\" are matched literally." }, "required": false, "description": "Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer (\"L1\", \"L2\" or \"hydra\"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and \"%\" and \"_\" are matched literally.", "name": "searchQuery", "in": "query" } ], "responses": { "200": { "description": "Total purchases count", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of purchases" } }, "required": [ "total" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "total": 75 } } } } } } } } }, "/payment/diff/onchain-state-or-result": { "get": { "description": "Returns payments whose on-chain state or result hash changed since lastUpdate.", "summary": "Diff payments by on-chain-state/result timestamp (READ access required)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of payments to return" }, "required": false, "description": "The number of payments to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor (payment id). Used as tie-breaker when lastUpdate equals a payment change timestamp" }, "required": false, "description": "Pagination cursor (payment id). Used as tie-breaker when lastUpdate equals a payment change timestamp", "name": "cursorId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "default": "1970-01-01T00:00:00.000Z", "description": "Return payments whose selected status timestamp changed after this ISO timestamp" }, "required": false, "description": "Return payments whose selected status timestamp changed after this ISO timestamp", "name": "lastUpdate", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the payments were made on" }, "required": true, "description": "The network the payments were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment diff endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, payment diff endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment diff endpoints default to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, payment diff endpoints default to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the full transaction and status history of the payments" }, "required": false, "description": "Whether to include the full transaction and status history of the payments", "name": "includeHistory", "in": "query" } ], "responses": { "200": { "description": "Payment diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } }, "required": [ "Payments" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Payments": [ { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "forceLayer": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "RequestedFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address", "policyId": "policy_id" }, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "TransactionHistory": [] } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/payment/submit-result": { "post": { "description": "Submit the hash of their completed job for a payment request, which triggers the fund unlock process so the seller can collect payment after the unlock time expires. (+PAY access required; only the creator or an admin may submit)", "summary": "Completes a payment request. This will collect the funds after the unlock time. (+PAY access required; only the creator or an admin may submit)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the payment was received on" }, "submitResultHash": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-fA-F]{64}$", "description": "The hash of the AI agent result to be submitted, should be sha256 hash of the result, therefore needs to be in hex string format" }, "blockchainIdentifier": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "The identifier of the payment" } }, "required": [ "network", "submitResultHash", "blockchainIdentifier" ], "example": { "network": "Preprod", "blockchainIdentifier": "identifier", "submitResultHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } } } } }, "responses": { "200": { "description": "Payment updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the payment" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being paid" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the payment was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "requestedById": { "type": "string", "description": "ID of the API key that created this payment" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "inputHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the input data for the payment (hex string)" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the payment on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Caller-specified layer override recorded on this payment. \"L1\" or \"Hydra\", or null for automatic routing (Hydra if available, else L1)." }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ], "description": "Next action required for this payment" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result to be submitted (hex string). Null if not applicable" } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ], "description": "Next action required for this payment" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "fees": { "type": "string", "nullable": true }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "fees", "blockHeight", "blockTime", "txHash", "status", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this payment. Null if no transaction in progress" }, "RequestedFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the seller" }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the buyer (refunds)" }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment source" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network (Mainnet, Preprod, or Preview)" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Payment source type for adapter dispatch" }, "smartContractAddress": { "type": "string", "description": "Address of the smart contract managing this payment" }, "policyId": { "type": "string", "nullable": true, "description": "Policy ID for the agent registry NFTs. Null if not applicable" } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ], "description": "Payment source configuration for this payment" }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the buyer wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the buyer wallet" } }, "required": [ "id", "walletVkey" ], "description": "Buyer wallet information. Null if buyer has not yet submitted payment" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this payment. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the payment for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "externalDisputeUnlockTime", "requestedById", "resultHash", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "nextActionOrOnChainStateOrResultLastChangedAt", "inputHash", "totalBuyerCardanoFees", "totalSellerCardanoFees", "cooldownTime", "cooldownTimeOtherParty", "onChainState", "forceLayer", "NextAction", "CurrentTransaction", "RequestedFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "BuyerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "forceLayer": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "RequestedFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address", "policyId": "policy_id" }, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (only the creator or an admin can submit results)" }, "404": { "description": "Payment not found or in invalid state" }, "500": { "description": "Internal Server Error" } } } }, "/payment/authorize-refund": { "post": { "description": "Authorizes a refund for a payment request. This will stop the right to receive a payment and initiate a refund for the other party. (+PAY access required; only the creator or an admin may authorize)", "summary": "Authorizes a refund for a payment request. This will stop the right to receive a payment and initiate a refund for the other party. (+PAY access required; only the creator or an admin may authorize)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchainIdentifier": { "type": "string", "maxLength": 8000, "description": "The identifier of the purchase to be refunded" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the Cardano wallet will be used on" } }, "required": [ "blockchainIdentifier", "network" ], "example": { "network": "Preprod", "blockchainIdentifier": "blockchain_identifier" } } } } }, "responses": { "200": { "description": "Payment refund authorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the payment" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being paid" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the payment was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "requestedById": { "type": "string", "description": "ID of the API key that created this payment" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "inputHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the input data for the payment (hex string)" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the payment on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Caller-specified layer override recorded on this payment. \"L1\" or \"Hydra\", or null for automatic routing (Hydra if available, else L1)." }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ], "description": "Next action required for this payment" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result to be submitted (hex string). Null if not applicable" } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ], "description": "Next action required for this payment" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "fees": { "type": "string", "nullable": true }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "fees", "blockHeight", "blockTime", "txHash", "status", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this payment. Null if no transaction in progress" }, "RequestedFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the seller" }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the buyer (refunds)" }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment source" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network (Mainnet, Preprod, or Preview)" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Payment source type for adapter dispatch" }, "smartContractAddress": { "type": "string", "description": "Address of the smart contract managing this payment" }, "policyId": { "type": "string", "nullable": true, "description": "Policy ID for the agent registry NFTs. Null if not applicable" } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ], "description": "Payment source configuration for this payment" }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the buyer wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the buyer wallet" } }, "required": [ "id", "walletVkey" ], "description": "Buyer wallet information. Null if buyer has not yet submitted payment" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this payment. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the payment for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "externalDisputeUnlockTime", "requestedById", "resultHash", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "nextActionOrOnChainStateOrResultLastChangedAt", "inputHash", "totalBuyerCardanoFees", "totalSellerCardanoFees", "cooldownTime", "cooldownTimeOtherParty", "onChainState", "forceLayer", "NextAction", "CurrentTransaction", "RequestedFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "BuyerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "forceLayer": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "RequestedFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address", "policyId": "policy_id" }, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (only the creator or an admin can authorize a refund)" }, "404": { "description": "Payment not found or in invalid state" }, "500": { "description": "Internal Server Error" } } } }, "/payment/error-state-recovery": { "post": { "description": "Clears error states for payment requests in WaitingForManualAction state and resets them up for retry or other actions. This endpoint provides manual intervention capability to recover from error states by clearing error fields.", "summary": "Clear error state for payment request (PAY access required)", "tags": [ "error-state-recovery" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Payment error recovery request details", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchainIdentifier": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "The blockchain identifier of the payment request" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the transaction was made on" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "description": "The time of the last update, to ensure you clear the correct error state" }, "retryPreviousAction": { "type": "boolean", "description": "When true, retry the failed action. When false or omitted, only clear the error state." } }, "required": [ "blockchainIdentifier", "network", "updatedAt" ], "example": { "blockchainIdentifier": "blockchain_identifier", "updatedAt": "1970-01-20T20:00:36.260Z", "network": "Preprod" } } } } }, "responses": { "200": { "description": "Error state cleared successfully for payment request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the payment" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being paid" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the payment was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "requestedById": { "type": "string", "description": "ID of the API key that created this payment" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "inputHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the input data for the payment (hex string)" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the payment on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Caller-specified layer override recorded on this payment. \"L1\" or \"Hydra\", or null for automatic routing (Hydra if available, else L1)." }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ], "description": "Next action required for this payment" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result to be submitted (hex string). Null if not applicable" } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ], "description": "Next action required for this payment" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "fees": { "type": "string", "nullable": true }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "fees", "blockHeight", "blockTime", "txHash", "status", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this payment. Null if no transaction in progress" }, "RequestedFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Use an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the seller" }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of the asset withdrawn (as string to handle large numbers)" }, "unit": { "type": "string", "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "description": "List of assets and amounts withdrawn for the buyer (refunds)" }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment source" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network (Mainnet, Preprod, or Preview)" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Payment source type for adapter dispatch" }, "smartContractAddress": { "type": "string", "description": "Address of the smart contract managing this payment" }, "policyId": { "type": "string", "nullable": true, "description": "Policy ID for the agent registry NFTs. Null if not applicable" } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ], "description": "Payment source configuration for this payment" }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the buyer wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the buyer wallet" } }, "required": [ "id", "walletVkey" ], "description": "Buyer wallet information. Null if buyer has not yet submitted payment" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this payment. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the payment for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "externalDisputeUnlockTime", "requestedById", "resultHash", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "nextActionOrOnChainStateOrResultLastChangedAt", "inputHash", "totalBuyerCardanoFees", "totalSellerCardanoFees", "cooldownTime", "cooldownTimeOtherParty", "onChainState", "forceLayer", "NextAction", "CurrentTransaction", "RequestedFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "BuyerWallet", "SmartContractWallet", "metadata" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "cmf40vg7h0016ucj1u1ro6651" } } } } } }, "400": { "description": "Bad Request (not in WaitingForManualAction state, no error to clear, or invalid input)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] }, "example": { "status": "error", "error": { "message": "Payment request is not in WaitingForManualAction state. Current state: WaitingForExternalAction" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment request not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] }, "example": { "status": "error", "error": { "message": "Payment request not found" } } } } }, "500": { "description": "Internal Server Error" } } } }, "/purchase/error-state-recovery": { "post": { "description": "Clears error states for purchase requests in WaitingForManualAction state and resets them up for retry or other actions. This endpoint provides manual intervention capability to recover from error states by clearing error fields.", "summary": "Clear error state for purchase request (PAY access required)", "tags": [ "error-state-recovery" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Purchase error recovery request details", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchainIdentifier": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "The blockchain identifier of the purchase request" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the transaction was made on" }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "description": "The time of the last update, to ensure you clear the correct error state" }, "retryPreviousAction": { "type": "boolean", "description": "When true, retry the failed action. When false or omitted, only clear the error state." } }, "required": [ "blockchainIdentifier", "network", "updatedAt" ], "example": { "blockchainIdentifier": "blockchain_identifier", "network": "Preprod", "updatedAt": "1970-01-20T20:00:36.260Z" } } } } }, "responses": { "200": { "description": "Error state cleared successfully for purchase request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the purchase" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the purchase" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being purchased" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the purchase was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "requestedById": { "type": "string", "description": "ID of the API key that created this purchase" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the purchase on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Buyer-specified layer override recorded on this purchase. \"L1\" or \"Hydra\", or null for automatic routing." }, "paymentForceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Seller-specified layer override. V2 authenticates it with the blockchain identifier signature; V1 can only carry redundant \"L1\". Null means automatic routing." }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "inputHash": { "type": "string", "description": "SHA256 hash of the input data for the purchase (hex string)" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated", "AuthorizeWithdrawalRequested", "AuthorizeWithdrawalInitiated" ], "description": "Next action required for this purchase" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" } }, "required": [ "requestedAction", "errorType", "errorNote" ], "description": "Next action required for this purchase" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status", "fees", "blockHeight", "blockTime", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this purchase. Null if no transaction in progress" }, "PaidFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the seller wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the seller wallet" } }, "required": [ "id", "walletVkey" ], "description": "Seller wallet information. Null if not set" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this purchase. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the purchase for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "totalBuyerCardanoFees", "totalSellerCardanoFees", "nextActionOrOnChainStateOrResultLastChangedAt", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "requestedById", "onChainState", "forceLayer", "paymentForceLayer", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "cooldownTime", "cooldownTimeOtherParty", "inputHash", "resultHash", "NextAction", "CurrentTransaction", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "cmf40vg7h0016ucj1u1ro6651" } } } } } }, "400": { "description": "Bad Request (not in WaitingForManualAction state, no error to clear, or invalid input)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] }, "example": { "status": "error", "error": { "message": "Purchase request is not in WaitingForManualAction state. Current state: WaitingForExternalAction" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Purchase request not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] }, "example": { "status": "error", "error": { "message": "Purchase request not found" } } } } }, "500": { "description": "Internal Server Error" } } } }, "/signature/sign/create-invoice/monthly": { "post": { "description": "Provides a signed message from the smart contract wallet to authorize monthly invoice retrieval for a buyer wallet. (+PAY access required)", "summary": "Get a signed message to request a monthly invoice. (+PAY access required)", "tags": [ "signature" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "buyerWalletVkey": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The buyer wallet vkey for which to aggregate the month" }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Target month in format YYYY-MM (UTC calendar)" }, "action": { "type": "string", "enum": [ "RetrieveMonthlyInvoices" ], "description": "The action to perform for monthly invoices" }, "Buyer": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The country of the invoice" }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The city of the invoice" }, "zipCode": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The zip code of the invoice" }, "street": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The street of the invoice" }, "streetNumber": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The street number of the invoice" }, "email": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "format": "email", "description": "The email of the invoice" }, "phone": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The phone of the invoice" }, "name": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The name of the invoice" }, "companyName": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The company name of the invoice" }, "vatNumber": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The VAT number of the invoice" } }, "required": [ "country", "city", "zipCode", "street", "streetNumber", "email", "phone", "name", "companyName", "vatNumber" ] } }, "required": [ "buyerWalletVkey", "month", "action", "Buyer" ], "example": { "action": "RetrieveMonthlyInvoices", "buyerWalletVkey": "buyer_wallet_vkey", "month": "2025-09", "Buyer": { "country": "DE", "city": "Berlin", "zipCode": "10115", "street": "Buyer Str.", "streetNumber": "2", "email": "buyer@example.com", "phone": "+49 30 987654", "name": "Bob", "companyName": null, "vatNumber": null } } } } } }, "responses": { "200": { "description": "Monthly signature generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "signature": { "type": "string" }, "key": { "type": "string" }, "walletAddress": { "type": "string" }, "signatureData": { "type": "string" } }, "required": [ "signature", "key", "walletAddress", "signatureData" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "signature": "ed25519_signature", "key": "ed25519_key", "walletAddress": "addr1...", "signatureData": "{\"action\":\"RetrieveMonthlyInvoices\",\"validUntil\":1736352000000,\"hash\":\"...\"}" } } } } } } } } }, "/signature/sign/verifyAndPublishAgent": { "post": { "description": "Provides a signed message from the registered agent wallet to authorize wallet verification for agent publishing. (+PAY access required)", "summary": "Get a signed message to verify and publish an agent. (+PAY access required)", "tags": [ "signature" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The public key to sign for publishing the agent" }, "agentIdentifier": { "type": "string", "minLength": 57, "maxLength": 250, "description": "Full agent identifier (policy ID + asset name in hex)" }, "action": { "type": "string", "enum": [ "VerifyAndPublishAgent" ], "description": "The action to perform for agent publish verification" } }, "required": [ "publicKey", "agentIdentifier", "action" ], "example": { "action": "VerifyAndPublishAgent", "publicKey": "ed25519_pk1example", "agentIdentifier": "policyidassetnamehex" } } } } }, "responses": { "200": { "description": "Agent publish signature generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "signature": { "type": "string" }, "key": { "type": "string" }, "walletAddress": { "type": "string" }, "signatureData": { "type": "string" } }, "required": [ "signature", "key", "walletAddress", "signatureData" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "signature": "ed25519_signature", "key": "ed25519_key", "walletAddress": "addr1...", "signatureData": "{\"action\":\"VerifyAndPublishAgent\",\"validUntil\":1736352000000,\"data\":{\"publicKey\":\"...\",\"walletVkey\":\"...\"}}" } } } } } } } } }, "/invoice/monthly": { "post": { "description": "Generates an invoice PDF aggregating all payment requests for a buyer wallet within a month, using the end-of-month conversion rate. (+PAY access required)\n\n**BETA:** This invoice feature is in beta. Generated invoices should be reviewed manually or verified with a tax advisor before use. Use at your own discretion.", "summary": "Generate a monthly invoice PDF by buyer wallet vkey and month. (+PAY access required)", "tags": [ "invoice" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "buyerWalletVkey": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The buyer wallet vkey to aggregate the month for" }, "sellerWalletVkey": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Optional seller wallet vkey to scope the invoice to a specific seller" }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Target month in format YYYY-MM (UTC calendar)" }, "invoiceCurrency": { "type": "string", "enum": [ "usd", "eur", "gbp", "jpy", "chf", "aed" ], "description": "The currency of the invoice" }, "CurrencyConversion": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "description": "Currency conversion settings by unit for this invoice" }, "Invoice": { "type": "object", "properties": { "itemNamePrefix": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The prefix of the item name" }, "itemNameSuffix": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The suffix of the item name" }, "title": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The title of the invoice" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The description of the invoice" }, "idPrefix": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The prefix of the invoice number" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date of the invoice (YYYY-MM-DD)" }, "greeting": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The greetings of the invoice" }, "closing": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The closing of the invoice" }, "signature": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The signature of the invoice" }, "logo": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The logo of the invoice" }, "footer": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The footer of the invoice" }, "terms": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The terms of the invoice" }, "privacy": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The privacy of the invoice" }, "language": { "type": "string", "enum": [ "en-us", "en-gb", "de" ], "description": "Invoice language and region: English US (en-us), English GB (en-gb), or German (de). Default: en-us" }, "localizationFormat": { "type": "string", "enum": [ "en-us", "en-gb", "de" ], "description": "The localization format of the invoice" } } }, "vatRate": { "type": "number", "minimum": 0, "maximum": 1, "description": "The VAT rate as decimal (e.g., 0.19 for 19%)" }, "reverseCharge": { "type": "boolean", "default": false, "description": "Enable reverse charge (VAT = 0, notice on invoice)" }, "forceRegenerate": { "type": "boolean", "default": false, "description": "Force cancel existing invoice and generate a new revision, even if no data changes detected" }, "Seller": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The country of the invoice" }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The city of the invoice" }, "zipCode": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The zip code of the invoice" }, "street": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The street of the invoice" }, "streetNumber": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The street number of the invoice" }, "email": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "format": "email", "description": "The email of the invoice" }, "phone": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The phone of the invoice" }, "name": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The name of the invoice" }, "companyName": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The company name of the invoice" }, "vatNumber": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The VAT number of the invoice" } }, "required": [ "country", "city", "zipCode", "street", "streetNumber", "email", "phone", "name", "companyName", "vatNumber" ] }, "Buyer": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The country of the invoice" }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The city of the invoice" }, "zipCode": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The zip code of the invoice" }, "street": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The street of the invoice" }, "streetNumber": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The street number of the invoice" }, "email": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "format": "email", "description": "The email of the invoice" }, "phone": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The phone of the invoice" }, "name": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The name of the invoice" }, "companyName": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The company name of the invoice" }, "vatNumber": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The VAT number of the invoice" } }, "required": [ "country", "city", "zipCode", "street", "streetNumber", "email", "phone", "name", "companyName", "vatNumber" ] }, "signature": { "type": "string", "maxLength": 2000, "description": "The signature to verify" }, "key": { "type": "string", "maxLength": 2000, "description": "The key to verify the signature" }, "walletAddress": { "type": "string", "minLength": 58, "maxLength": 500, "pattern": "^(addr1|addr_test1)[0-9a-z]+$", "description": "The wallet address that signed the message" }, "validUntil": { "type": "number", "description": "The valid until timestamp" }, "action": { "type": "string", "enum": [ "RetrieveMonthlyInvoices" ], "description": "The action to perform for monthly invoices" } }, "required": [ "buyerWalletVkey", "month", "invoiceCurrency", "Seller", "Buyer", "signature", "key", "walletAddress", "validUntil", "action" ], "example": { "signature": "ed25519_signature", "key": "ed25519_key", "walletAddress": "addr1xk2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x", "validUntil": 1736352000000, "action": "RetrieveMonthlyInvoices", "buyerWalletVkey": "buyer_wallet_vkey", "month": "2025-09", "invoiceCurrency": "usd", "CurrencyConversion": { "": 0.45, "policyIdAssetHex": 1.23 }, "Invoice": { "itemNamePrefix": "Agent: ", "title": "Monthly Invoice", "language": "en-us", "localizationFormat": "en-us" }, "vatRate": 0.19, "reverseCharge": false, "forceRegenerate": false, "Seller": { "country": "DE", "city": "Berlin", "zipCode": "10115", "street": "Example Str.", "streetNumber": "1", "email": "seller@example.com", "phone": "+49 30 123456", "name": "Alice", "companyName": "Alice GmbH", "vatNumber": "DE123456789" }, "Buyer": { "country": "DE", "city": "Berlin", "zipCode": "10115", "street": "Buyer Str.", "streetNumber": "2", "email": "buyer@example.com", "phone": "+49 30 987654", "name": "Bob", "companyName": null, "vatNumber": null } } } } } }, "responses": { "200": { "description": "Monthly invoice generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "invoice": { "type": "string" }, "cancellationInvoice": { "type": "string" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "invoice": "BASE64_PDF_STRING", "cancellationInvoice": "BASE64_CANCELLATION_PDF_STRING_OR_UNDEFINED" } } } } } } } }, "get": { "description": "Lists invoice summaries for a given month with pagination. Returns only the latest revision per invoice base. Pass invoiceBaseId to get all revisions for a specific invoice. (+PAY access required)\n\n**BETA:** This invoice feature is in beta. Generated invoices should be reviewed manually or verified with a tax advisor before use. Use at your own risk.", "summary": "List invoices for a month. (+Read access required)", "tags": [ "invoice" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Target month in format YYYY-MM (UTC calendar)" }, "required": true, "description": "Target month in format YYYY-MM (UTC calendar)", "name": "month", "in": "query" }, { "schema": { "type": "string", "description": "Cursor for pagination (InvoiceBase id)" }, "required": false, "description": "Cursor for pagination (InvoiceBase id)", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "Number of results to return" }, "required": false, "description": "Number of results to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "When provided, return all revisions for this specific invoice base (ignores pagination)" }, "required": false, "description": "When provided, return all revisions for this specific invoice base (ignores pagination)", "name": "invoiceBaseId", "in": "query" } ], "responses": { "200": { "description": "List of invoice summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "revisionId": { "type": "string" }, "revisionNumber": { "type": "number" }, "revisionCount": { "type": "number", "description": "Total number of revisions for this invoice base" }, "invoiceMonth": { "type": "number" }, "invoiceYear": { "type": "number" }, "invoiceDate": { "type": "string", "format": "date-time" }, "currencyShortId": { "type": "string" }, "reverseCharge": { "type": "boolean" }, "language": { "type": "string", "nullable": true }, "localizationFormat": { "type": "string" }, "vatRate": { "type": "number", "nullable": true, "description": "VAT rate from the first item, null if no items" }, "sellerName": { "type": "string", "nullable": true }, "sellerCompanyName": { "type": "string", "nullable": true }, "sellerVatNumber": { "type": "string", "nullable": true }, "sellerCountry": { "type": "string" }, "sellerCity": { "type": "string" }, "sellerZipCode": { "type": "string" }, "sellerStreet": { "type": "string" }, "sellerStreetNumber": { "type": "string" }, "sellerEmail": { "type": "string", "nullable": true }, "sellerPhone": { "type": "string", "nullable": true }, "buyerName": { "type": "string", "nullable": true }, "buyerCompanyName": { "type": "string", "nullable": true }, "buyerVatNumber": { "type": "string", "nullable": true }, "buyerCountry": { "type": "string" }, "buyerCity": { "type": "string" }, "buyerZipCode": { "type": "string" }, "buyerStreet": { "type": "string" }, "buyerStreetNumber": { "type": "string" }, "buyerEmail": { "type": "string", "nullable": true }, "buyerPhone": { "type": "string", "nullable": true }, "invoiceTitle": { "type": "string", "nullable": true }, "invoiceDescription": { "type": "string", "nullable": true }, "isCancelled": { "type": "boolean" }, "cancellationReason": { "type": "string", "nullable": true }, "cancellationDate": { "type": "string", "nullable": true, "format": "date-time" }, "cancellationId": { "type": "string", "nullable": true }, "itemCount": { "type": "number" }, "netTotal": { "type": "string" }, "vatTotal": { "type": "string" }, "grossTotal": { "type": "string" }, "CoveredPaymentRequestIds": { "type": "array", "items": { "type": "string" } }, "buyerWalletVkey": { "type": "string", "nullable": true }, "sellerWalletVkey": { "type": "string", "nullable": true }, "invoicePdf": { "type": "string", "description": "Base64-encoded invoice PDF" }, "cancellationInvoicePdf": { "type": "string", "nullable": true, "description": "Base64-encoded cancellation PDF if cancelled" } }, "required": [ "id", "invoiceId", "createdAt", "revisionId", "revisionNumber", "revisionCount", "invoiceMonth", "invoiceYear", "invoiceDate", "currencyShortId", "reverseCharge", "language", "localizationFormat", "vatRate", "sellerName", "sellerCompanyName", "sellerVatNumber", "sellerCountry", "sellerCity", "sellerZipCode", "sellerStreet", "sellerStreetNumber", "sellerEmail", "sellerPhone", "buyerName", "buyerCompanyName", "buyerVatNumber", "buyerCountry", "buyerCity", "buyerZipCode", "buyerStreet", "buyerStreetNumber", "buyerEmail", "buyerPhone", "invoiceTitle", "invoiceDescription", "isCancelled", "cancellationReason", "cancellationDate", "cancellationId", "itemCount", "netTotal", "vatTotal", "grossTotal", "CoveredPaymentRequestIds", "buyerWalletVkey", "sellerWalletVkey", "invoicePdf", "cancellationInvoicePdf" ] } } }, "required": [ "Invoices" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Invoices": [ { "id": "invoice_base_id", "invoiceId": "INV-0001", "createdAt": "2025-09-30T23:59:59.000Z", "revisionId": "revision_id", "revisionNumber": 0, "revisionCount": 1, "invoiceMonth": 9, "invoiceYear": 2025, "invoiceDate": "2025-09-30T00:00:00.000Z", "currencyShortId": "usd", "sellerName": "Alice", "sellerCompanyName": "Alice GmbH", "buyerName": "Bob", "buyerCompanyName": null, "isCancelled": false, "cancellationReason": null, "cancellationDate": null, "cancellationId": null, "itemCount": 3, "netTotal": "150.00", "vatTotal": "28.50", "grossTotal": "178.50", "CoveredPaymentRequestIds": [ "payment_id_1", "payment_id_2" ], "buyerWalletVkey": "buyer_wallet_vkey", "invoicePdf": "BASE64_PDF_STRING", "cancellationInvoicePdf": null } ] } } } } } } } } }, "/registry/count": { "get": { "description": "Gets the total count of AI agents.", "summary": "Get the total number of AI agents. (READ access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the agent on" }, "required": true, "description": "The Cardano network used to register the agent on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, count defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, count defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, count defaults to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, count defaults to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" } ], "responses": { "200": { "description": "Total AI agents count", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of AI agents" } }, "required": [ "total" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "total": 42 } } } } } } } } }, "/invoice/monthly/internal": { "post": { "description": "Generates an invoice PDF aggregating all payment requests for a buyer wallet within a month, without requiring buyer wallet signature verification. (+PAY access required)\n\n**BETA:** This invoice feature is in beta. Generated invoices should be reviewed manually or verified with a tax advisor before use. Use at your own discretion.", "summary": "Generate a monthly invoice PDF without signature verification. (+PAY access required)", "tags": [ "invoice" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "buyerWalletVkey": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The buyer wallet vkey to aggregate the month for" }, "sellerWalletVkey": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Optional seller wallet vkey to scope the invoice to a specific seller" }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Target month in format YYYY-MM (UTC calendar)" }, "invoiceCurrency": { "type": "string", "enum": [ "usd", "eur", "gbp", "jpy", "chf", "aed" ], "description": "The currency of the invoice" }, "CurrencyConversion": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "description": "Currency conversion settings by unit for this invoice" }, "Invoice": { "type": "object", "properties": { "itemNamePrefix": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The prefix of the item name" }, "itemNameSuffix": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The suffix of the item name" }, "title": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The title of the invoice" }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The description of the invoice" }, "idPrefix": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The prefix of the invoice number" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date of the invoice (YYYY-MM-DD)" }, "greeting": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The greetings of the invoice" }, "closing": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The closing of the invoice" }, "signature": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The signature of the invoice" }, "logo": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The logo of the invoice" }, "footer": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The footer of the invoice" }, "terms": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The terms of the invoice" }, "privacy": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The privacy of the invoice" }, "language": { "type": "string", "enum": [ "en-us", "en-gb", "de" ], "description": "Invoice language and region: English US (en-us), English GB (en-gb), or German (de). Default: en-us" }, "localizationFormat": { "type": "string", "enum": [ "en-us", "en-gb", "de" ], "description": "The localization format of the invoice" } } }, "vatRate": { "type": "number", "minimum": 0, "maximum": 1, "description": "The VAT rate as decimal (e.g., 0.19 for 19%)" }, "reverseCharge": { "type": "boolean", "default": false, "description": "Enable reverse charge (VAT = 0, notice on invoice)" }, "forceRegenerate": { "type": "boolean", "default": false, "description": "Force cancel existing invoice and generate a new revision, even if no data changes detected" }, "Seller": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The country of the invoice" }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The city of the invoice" }, "zipCode": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The zip code of the invoice" }, "street": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The street of the invoice" }, "streetNumber": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The street number of the invoice" }, "email": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "format": "email", "description": "The email of the invoice" }, "phone": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The phone of the invoice" }, "name": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The name of the invoice" }, "companyName": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The company name of the invoice" }, "vatNumber": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The VAT number of the invoice" } }, "required": [ "country", "city", "zipCode", "street", "streetNumber", "email", "phone", "name", "companyName", "vatNumber" ] }, "Buyer": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The country of the invoice" }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The city of the invoice" }, "zipCode": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The zip code of the invoice" }, "street": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The street of the invoice" }, "streetNumber": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The street number of the invoice" }, "email": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "format": "email", "description": "The email of the invoice" }, "phone": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The phone of the invoice" }, "name": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The name of the invoice" }, "companyName": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The company name of the invoice" }, "vatNumber": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 100, "description": "The VAT number of the invoice" } }, "required": [ "country", "city", "zipCode", "street", "streetNumber", "email", "phone", "name", "companyName", "vatNumber" ] } }, "required": [ "buyerWalletVkey", "month", "invoiceCurrency", "Seller", "Buyer" ], "example": { "buyerWalletVkey": "buyer_wallet_vkey", "month": "2025-09", "invoiceCurrency": "usd", "CurrencyConversion": { "": 0.45, "policyIdAssetHex": 1.23 }, "Invoice": { "itemNamePrefix": "Agent: ", "title": "Monthly Invoice", "language": "en-us", "localizationFormat": "en-us" }, "vatRate": 0.19, "reverseCharge": false, "forceRegenerate": false, "Seller": { "country": "DE", "city": "Berlin", "zipCode": "10115", "street": "Example Str.", "streetNumber": "1", "email": "seller@example.com", "phone": "+49 30 123456", "name": "Alice", "companyName": "Alice GmbH", "vatNumber": "DE123456789" }, "Buyer": { "country": "DE", "city": "Berlin", "zipCode": "10115", "street": "Buyer Str.", "streetNumber": "2", "email": "buyer@example.com", "phone": "+49 30 987654", "name": "Bob", "companyName": null, "vatNumber": null } } } } } }, "responses": { "200": { "description": "Monthly invoice generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "invoice": { "type": "string" }, "cancellationInvoice": { "type": "string" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "invoice": "BASE64_PDF_STRING", "cancellationInvoice": "BASE64_CANCELLATION_PDF_STRING_OR_UNDEFINED" } } } } } } } } }, "/invoice/monthly/missing": { "get": { "description": "Finds billable payment requests that do not yet have an invoice for a given month. Only finalized payments are included: Withdrawn (seller completed work), ResultSubmitted past unlock time, or DisputedWithdrawn with seller funds. Payments still locked, pending refund, or in dispute are excluded. (+PAY access required)\n\n**BETA:** This invoice feature is in beta. Generated invoices should be reviewed manually or verified with a tax advisor before use. Use at your own discretion.", "summary": "List uninvoiced payments for a month. (+Read access required)", "tags": [ "invoice" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Target month in format YYYY-MM (UTC calendar)" }, "required": true, "description": "Target month in format YYYY-MM (UTC calendar)", "name": "month", "in": "query" }, { "schema": { "type": "string", "maxLength": 1000, "description": "Optional buyer wallet vkey filter" }, "required": false, "description": "Optional buyer wallet vkey filter", "name": "buyerWalletVkey", "in": "query" }, { "schema": { "type": "string", "description": "Cursor for pagination (PaymentRequest id)" }, "required": false, "description": "Cursor for pagination (PaymentRequest id)", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "Number of results to return" }, "required": false, "description": "Number of results to return", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "List of uninvoiced billable payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "UninvoicedPayments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "onChainState": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "finalizedAt": { "type": "string", "format": "date-time" }, "buyerWalletVkey": { "type": "string", "nullable": true }, "buyerWalletAddress": { "type": "string", "nullable": true }, "sellerWalletVkey": { "type": "string", "nullable": true }, "sellerWalletAddress": { "type": "string", "nullable": true }, "RequestedFunds": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "unit", "amount" ] } } }, "required": [ "id", "blockchainIdentifier", "onChainState", "createdAt", "finalizedAt", "buyerWalletVkey", "buyerWalletAddress", "sellerWalletVkey", "sellerWalletAddress", "RequestedFunds" ] } } }, "required": [ "UninvoicedPayments" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "UninvoicedPayments": [ { "id": "payment_request_id", "blockchainIdentifier": "blockchain_identifier", "onChainState": "Withdrawn", "createdAt": "2025-09-15T10:00:00.000Z", "buyerWalletVkey": "buyer_wallet_vkey", "buyerWalletAddress": "addr1...", "RequestedFunds": [ { "unit": "", "amount": "5000000" } ] } ] } } } } } } } } }, "/purchase": { "get": { "description": "Gets the purchase status. It needs to be created first with a POST request.", "summary": "Get information about an existing purchase request. (READ access required)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of purchases to return" }, "required": false, "description": "The number of purchases to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Used to paginate through the purchases. If this is provided, cursorId is required" }, "required": false, "description": "Used to paginate through the purchases. If this is provided, cursorId is required", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the purchases were made on" }, "required": true, "description": "The network the purchases were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, purchase list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, purchase list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ], "description": "Filter by on-chain state" }, "required": false, "description": "Filter by on-chain state", "name": "filterOnChainState", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, purchase list/count endpoints default to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, purchase list/count endpoints default to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" }, { "schema": { "type": "string", "description": "When true, only returns purchases that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it" }, "required": false, "description": "When true, only returns purchases that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it", "name": "filterNeedsManualAction", "in": "query" }, { "schema": { "type": "string", "maxLength": 5020, "description": "Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing." }, "required": false, "description": "Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing.", "name": "filterAgentIdentifier", "in": "query" }, { "schema": { "type": "string", "maxLength": 500, "description": "Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer (\"L1\", \"L2\" or \"hydra\"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and \"%\" and \"_\" are matched literally." }, "required": false, "description": "Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer (\"L1\", \"L2\" or \"hydra\"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and \"%\" and \"_\" are matched literally.", "name": "searchQuery", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the full transaction and action history of the purchases" }, "required": false, "description": "Whether to include the full transaction and action history of the purchases", "name": "includeHistory", "in": "query" } ], "responses": { "200": { "description": "Purchase status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Purchases": { "type": "array", "items": { "$ref": "#/components/schemas/Purchase" } } }, "required": [ "Purchases" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Purchases": [ { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "lastCheckedAt": null, "onChainState": null, "metadata": null, "requestedById": "requester_id", "resultHash": "", "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "externalDisputeUnlockTime": "1713636260", "submitResultTime": "1970-01-20T20:00:36.260Z", "unlockTime": "1713636260", "PaidFunds": [], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "policyId": "policy_id", "smartContractAddress": "address" }, "SellerWallet": null, "SmartContractWallet": null, "CurrentTransaction": null, "TransactionHistory": [], "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "post": { "description": "Creates a purchase and pays the seller. This requires funds to be available.", "summary": "Create a new purchase request and pay. (access required +PAY)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchainIdentifier": { "type": "string", "maxLength": 8000, "description": "The identifier of the purchase. Is provided by the seller" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the transaction will be made on" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Optional payment source type hint for this purchase. When omitted, the type is inferred from the blockchainIdentifier shape." }, "smartContractAddress": { "type": "string", "maxLength": 250, "description": "Optional V2 payment contract address. When omitted, the address is inferred from the signed blockchainIdentifier; when provided, it must match that identifier." }, "supportedPaymentSourceIndex": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The V2 Cardano source index selected when the seller created the payment. The seller signature covers this value. Omit only for legacy V2 identifiers created before source-owned pricing." }, "inputHash": { "type": "string", "maxLength": 250, "description": "The hash of the input data of the purchase, should be sha256 hash of the input data, therefore needs to be in hex string format" }, "sellerVkey": { "type": "string", "maxLength": 250, "description": "The verification key of the seller" }, "agentIdentifier": { "type": "string", "minLength": 57, "maxLength": 250, "description": "The identifier of the agent that is being purchased" }, "Amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Amount of the asset in smallest unit (e.g., lovelace for ADA)" }, "unit": { "type": "string", "maxLength": 150, "description": "Asset policy id + asset name concatenated. Empty string for ADA/lovelace" } }, "required": [ "amount", "unit" ] }, "maxItems": 7, "description": "The amounts to be paid for the purchase" }, "unlockTime": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "The time after which the purchase will be unlocked. In unix time (number)" }, "externalDisputeUnlockTime": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "The time after which the purchase will be unlocked for external dispute. In unix time (number)" }, "submitResultTime": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "The time by which the result has to be submitted. In unix time (number)" }, "payByTime": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "The time after which the purchase has to be submitted to the smart contract" }, "metadata": { "type": "string", "description": "Metadata to be stored with the purchase request" }, "buyerReturnAddress": { "type": "string", "maxLength": 250, "description": "Optional buyer return address. Defaults to the purchasing hot wallet collection address when available." }, "sellerReturnAddress": { "type": "string", "maxLength": 250, "description": "Optional seller return address when using a signed V2 identifier from the seller." }, "identifierFromPurchaser": { "type": "string", "minLength": 14, "maxLength": 26, "description": "The nonce of the purchaser. It must be in hex format" }, "forceLayer": { "type": "string", "enum": [ "L1", "Hydra" ], "description": "Optional buyer layer override. \"L1\" forces L1; \"Hydra\" requires an open head and is supported only for V2. It must not conflict with the signed paymentForceLayer. Omit for automatic routing." }, "paymentForceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Seller layer override copied from the payment response. For V2, a non-null value is part of the signed payment terms and cannot be changed or omitted without invalidating the identifier. V1 accepts only the redundant \"L1\" value for response round-tripping. Omit or pass null when the seller selected automatic routing." } }, "required": [ "blockchainIdentifier", "network", "inputHash", "sellerVkey", "agentIdentifier", "unlockTime", "externalDisputeUnlockTime", "submitResultTime", "payByTime", "identifierFromPurchaser" ], "example": { "identifierFromPurchaser": "aabbaabb11221122aabb", "network": "Preprod", "sellerVkey": "seller_vkey", "blockchainIdentifier": "blockchain_identifier", "payByTime": "1713626260", "submitResultTime": "1713636260", "unlockTime": "1713636260", "externalDisputeUnlockTime": "1713636260", "agentIdentifier": "agent_identifier", "inputHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } } } } }, "responses": { "200": { "description": "Purchase request created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the purchase" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the purchase" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being purchased" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the purchase was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "requestedById": { "type": "string", "description": "ID of the API key that created this purchase" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the purchase on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Buyer-specified layer override recorded on this purchase. \"L1\" or \"Hydra\", or null for automatic routing." }, "paymentForceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Seller-specified layer override. V2 authenticates it with the blockchain identifier signature; V1 can only carry redundant \"L1\". Null means automatic routing." }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "inputHash": { "type": "string", "description": "SHA256 hash of the input data for the purchase (hex string)" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated", "AuthorizeWithdrawalRequested", "AuthorizeWithdrawalInitiated" ], "description": "Next action required for this purchase" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" } }, "required": [ "requestedAction", "errorType", "errorNote" ], "description": "Next action required for this purchase" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status", "fees", "blockHeight", "blockTime", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this purchase. Null if no transaction in progress" }, "PaidFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the seller wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the seller wallet" } }, "required": [ "id", "walletVkey" ], "description": "Seller wallet information. Null if not set" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this purchase. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the purchase for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "totalBuyerCardanoFees", "totalSellerCardanoFees", "nextActionOrOnChainStateOrResultLastChangedAt", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "requestedById", "onChainState", "forceLayer", "paymentForceLayer", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "cooldownTime", "cooldownTimeOtherParty", "inputHash", "resultHash", "NextAction", "CurrentTransaction", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "payByTime": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "requestedById": "requester_id", "onChainState": null, "forceLayer": null, "paymentForceLayer": null, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "cooldownTime": 0, "cooldownTimeOtherParty": 0, "inputHash": "input_hash", "resultHash": null, "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "PaidFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "409": { "description": "Conflict (purchase request already exists)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "id": { "type": "string" }, "object": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the purchase" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the purchase" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being purchased" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the purchase was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "requestedById": { "type": "string", "description": "ID of the API key that created this purchase" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the purchase on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Buyer-specified layer override recorded on this purchase. \"L1\" or \"Hydra\", or null for automatic routing." }, "paymentForceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Seller-specified layer override. V2 authenticates it with the blockchain identifier signature; V1 can only carry redundant \"L1\". Null means automatic routing." }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "inputHash": { "type": "string", "description": "SHA256 hash of the input data for the purchase (hex string)" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated", "AuthorizeWithdrawalRequested", "AuthorizeWithdrawalInitiated" ], "description": "Next action required for this purchase" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" } }, "required": [ "requestedAction", "errorType", "errorNote" ], "description": "Next action required for this purchase" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status", "fees", "blockHeight", "blockTime", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this purchase. Null if no transaction in progress" }, "PaidFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the seller wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the seller wallet" } }, "required": [ "id", "walletVkey" ], "description": "Seller wallet information. Null if not set" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this purchase. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the purchase for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "totalBuyerCardanoFees", "totalSellerCardanoFees", "nextActionOrOnChainStateOrResultLastChangedAt", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "requestedById", "onChainState", "forceLayer", "paymentForceLayer", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "cooldownTime", "cooldownTimeOtherParty", "inputHash", "resultHash", "NextAction", "CurrentTransaction", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] } }, "required": [ "status", "error", "id", "object" ] }, "example": { "status": "error", "error": { "message": "Purchase request already exists" }, "id": "cuid_v2_auto_generated", "object": { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "payByTime": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "requestedById": "requester_id", "onChainState": null, "forceLayer": null, "paymentForceLayer": null, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "cooldownTime": 0, "cooldownTimeOtherParty": 0, "inputHash": "input_hash", "resultHash": null, "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "PaidFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } }, "500": { "description": "Internal Server Error" } } } }, "/purchase/diff": { "get": { "description": "Returns purchases that changed since the provided timestamp (combined next-action + on-chain-state/result).", "summary": "Diff purchases by combined status timestamp (READ access required)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of purchases to return" }, "required": false, "description": "The number of purchases to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor (purchase id). Used as tie-breaker when lastUpdate equals a purchase change timestamp" }, "required": false, "description": "Pagination cursor (purchase id). Used as tie-breaker when lastUpdate equals a purchase change timestamp", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "default": "1970-01-01T00:00:00.000Z", "description": "Return purchases whose selected status timestamp changed at/after this ISO timestamp" }, "required": false, "description": "Return purchases whose selected status timestamp changed at/after this ISO timestamp", "name": "lastUpdate", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the purchases were made on" }, "required": true, "description": "The network the purchases were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source" }, "required": false, "description": "The smart contract address of the payment source", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the full transaction and status history of the purchases" }, "required": false, "description": "Whether to include the full transaction and status history of the purchases", "name": "includeHistory", "in": "query" } ], "responses": { "200": { "description": "Purchase diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Purchases": { "type": "array", "items": { "$ref": "#/components/schemas/Purchase" } } }, "required": [ "Purchases" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Purchases": [ { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "lastCheckedAt": null, "onChainState": null, "metadata": null, "requestedById": "requester_id", "resultHash": "", "cooldownTime": 0, "payByTime": null, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "externalDisputeUnlockTime": "1713636260", "submitResultTime": "1970-01-20T20:00:36.260Z", "unlockTime": "1713636260", "PaidFunds": [], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "policyId": "policy_id", "smartContractAddress": "address" }, "SellerWallet": null, "SmartContractWallet": null, "CurrentTransaction": null, "TransactionHistory": [], "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/purchase/diff/next-action": { "get": { "description": "Returns purchases whose next action changed since lastUpdate.", "summary": "Diff purchases by next-action timestamp (READ access required)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of purchases to return" }, "required": false, "description": "The number of purchases to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor (purchase id). Used as tie-breaker when lastUpdate equals a purchase change timestamp" }, "required": false, "description": "Pagination cursor (purchase id). Used as tie-breaker when lastUpdate equals a purchase change timestamp", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "default": "1970-01-01T00:00:00.000Z", "description": "Return purchases whose selected status timestamp changed at/after this ISO timestamp" }, "required": false, "description": "Return purchases whose selected status timestamp changed at/after this ISO timestamp", "name": "lastUpdate", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the purchases were made on" }, "required": true, "description": "The network the purchases were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source" }, "required": false, "description": "The smart contract address of the payment source", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the full transaction and status history of the purchases" }, "required": false, "description": "Whether to include the full transaction and status history of the purchases", "name": "includeHistory", "in": "query" } ], "responses": { "200": { "description": "Purchase diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Purchases": { "type": "array", "items": { "$ref": "#/components/schemas/Purchase" } } }, "required": [ "Purchases" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/purchase/diff/onchain-state-or-result": { "get": { "description": "Returns purchases whose on-chain state or result hash changed since lastUpdate.", "summary": "Diff purchases by on-chain-state/result timestamp (READ access required)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of purchases to return" }, "required": false, "description": "The number of purchases to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor (purchase id). Used as tie-breaker when lastUpdate equals a purchase change timestamp" }, "required": false, "description": "Pagination cursor (purchase id). Used as tie-breaker when lastUpdate equals a purchase change timestamp", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "default": "1970-01-01T00:00:00.000Z", "description": "Return purchases whose selected status timestamp changed at/after this ISO timestamp" }, "required": false, "description": "Return purchases whose selected status timestamp changed at/after this ISO timestamp", "name": "lastUpdate", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the purchases were made on" }, "required": true, "description": "The network the purchases were made on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source" }, "required": false, "description": "The smart contract address of the payment source", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "default": "false", "description": "Whether to include the full transaction and status history of the purchases" }, "required": false, "description": "Whether to include the full transaction and status history of the purchases", "name": "includeHistory", "in": "query" } ], "responses": { "200": { "description": "Purchase diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Purchases": { "type": "array", "items": { "$ref": "#/components/schemas/Purchase" } } }, "required": [ "Purchases" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/payment/x402": { "post": { "description": "Builds an unsigned Cardano funds-locking transaction for an existing payment request. The seller calls this on behalf of the buyer (x402 protocol). No state is saved — the returned CBOR must be signed by the buyer and submitted to the network.", "summary": "Build an unsigned x402 funds-locking transaction for a payment. (+READ access required)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network" }, "blockchainIdentifier": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "The blockchainIdentifier from the PaymentRequest" }, "buyerAddress": { "type": "string", "minLength": 58, "maxLength": 120, "pattern": "^(addr1|addr_test1)[0-9a-z]+$", "description": "The buyer's bech32 Cardano wallet address. UTxOs fetched from this address to build the unsigned tx." } }, "required": [ "network", "blockchainIdentifier", "buyerAddress" ], "example": { "network": "Preprod", "blockchainIdentifier": "blockchain_identifier", "buyerAddress": "addr_test1qp..." } } } } }, "responses": { "200": { "description": "Unsigned transaction CBOR ready for buyer to sign and submit", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "unsignedTxCbor": { "type": "string", "description": "Hex-encoded unsigned transaction CBOR. Sign with buyer wallet and submit." }, "collateralReturnLovelace": { "type": "string", "description": "Extra lovelace included for min-UTXO. Buyer receives this back as change after result submission." } }, "required": [ "unsignedTxCbor", "collateralReturnLovelace" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "unsignedTxCbor": "84a500818258...", "collateralReturnLovelace": "1500000" } } } } } }, "400": { "description": "Bad Request (invalid buyer address, expired payment, or insufficient buyer funds)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment not found or not in a buildable state" }, "500": { "description": "Internal Server Error" } } } }, "/purchase/request-refund": { "post": { "description": "Requests a refund for a completed purchase. This will collect the refund after the refund time.", "summary": "Request a refund for a completed purchase, which will be automatically collected after the refund time period expires. (+PAY access required)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchainIdentifier": { "type": "string", "maxLength": 8000, "description": "The identifier of the purchase to be refunded" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the Cardano wallet will be used on" } }, "required": [ "blockchainIdentifier", "network" ], "example": { "network": "Preprod", "blockchainIdentifier": "blockchain_identifier" } } } } }, "responses": { "200": { "description": "Purchase refund requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the purchase" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the purchase" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being purchased" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the purchase was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "requestedById": { "type": "string", "description": "ID of the API key that created this purchase" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the purchase on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Buyer-specified layer override recorded on this purchase. \"L1\" or \"Hydra\", or null for automatic routing." }, "paymentForceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Seller-specified layer override. V2 authenticates it with the blockchain identifier signature; V1 can only carry redundant \"L1\". Null means automatic routing." }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "inputHash": { "type": "string", "description": "SHA256 hash of the input data for the purchase (hex string)" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated", "AuthorizeWithdrawalRequested", "AuthorizeWithdrawalInitiated" ], "description": "Next action required for this purchase" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" } }, "required": [ "requestedAction", "errorType", "errorNote" ], "description": "Next action required for this purchase" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status", "fees", "blockHeight", "blockTime", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this purchase. Null if no transaction in progress" }, "PaidFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the seller wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the seller wallet" } }, "required": [ "id", "walletVkey" ], "description": "Seller wallet information. Null if not set" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this purchase. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the purchase for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "totalBuyerCardanoFees", "totalSellerCardanoFees", "nextActionOrOnChainStateOrResultLastChangedAt", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "requestedById", "onChainState", "forceLayer", "paymentForceLayer", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "cooldownTime", "cooldownTimeOtherParty", "inputHash", "resultHash", "NextAction", "CurrentTransaction", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "payByTime": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "requestedById": "requester_id", "onChainState": null, "forceLayer": null, "paymentForceLayer": null, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "cooldownTime": 0, "cooldownTimeOtherParty": 0, "inputHash": "input_hash", "resultHash": null, "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "PaidFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (only the creator or an admin can request a refund)" }, "404": { "description": "Purchase not found or not in valid state" }, "500": { "description": "Internal Server Error" } } } }, "/purchase/cancel-refund-request": { "post": { "description": "Cancels a previously requested refund for a completed purchase.", "summary": "Cancel a previously requested refund for a purchase, reverting the transaction back to its normal processing state. (+PAY access required)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchainIdentifier": { "type": "string", "maxLength": 8000, "description": "The identifier of the purchase to be refunded" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the Cardano wallet will be used on" } }, "required": [ "blockchainIdentifier", "network" ], "example": { "network": "Preprod", "blockchainIdentifier": "blockchain_identifier" } } } } }, "responses": { "200": { "description": "Purchase refund request cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the purchase" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the purchase was last updated" }, "blockchainIdentifier": { "type": "string", "description": "Unique blockchain identifier for the purchase" }, "agentIdentifier": { "type": "string", "nullable": true, "description": "Identifier of the agent that is being purchased" }, "agentName": { "type": "string", "nullable": true, "description": "Display name of the agent when known" }, "pricingType": { "type": "string", "enum": [ "Fixed", "Free", "Dynamic" ], "description": "Pricing type of the agent (Fixed, Free, or Dynamic)" }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Timestamp when the purchase was last checked on-chain. Null if never checked" }, "payByTime": { "type": "string", "nullable": true, "description": "Unix timestamp (in milliseconds) by which the buyer must submit the payment transaction. Null if not set" }, "submitResultTime": { "type": "string", "description": "Unix timestamp (in milliseconds) by which the seller must submit the result" }, "unlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which funds can be unlocked if no disputes" }, "externalDisputeUnlockTime": { "type": "string", "description": "Unix timestamp (in milliseconds) after which external dispute resolution can occur" }, "totalBuyerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the buyer in ADA (sum of all confirmed transactions initiated by buyer)" }, "totalSellerCardanoFees": { "type": "number", "description": "Total Cardano transaction fees paid by the seller in ADA (sum of all confirmed transactions initiated by seller)" }, "nextActionOrOnChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action or on-chain state or result was last changed" }, "nextActionLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the next action was last changed" }, "onChainStateOrResultLastChangedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the on-chain state or result was last changed" }, "requestedById": { "type": "string", "description": "ID of the API key that created this purchase" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Current state of the purchase on the blockchain. Null if not yet on-chain" }, "forceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Buyer-specified layer override recorded on this purchase. \"L1\" or \"Hydra\", or null for automatic routing." }, "paymentForceLayer": { "type": "string", "nullable": true, "enum": [ "L1", "Hydra", null ], "description": "Seller-specified layer override. V2 authenticates it with the blockchain identifier signature; V1 can only carry redundant \"L1\". Null means automatic routing." }, "collateralReturnLovelace": { "type": "string", "nullable": true, "description": "Amount of collateral to return in lovelace. Null if no collateral" }, "buyerReturnAddress": { "type": "string", "nullable": true, "description": "Optional buyer return address stored with the request" }, "sellerReturnAddress": { "type": "string", "nullable": true, "description": "Optional seller return address stored with the request" }, "cooldownTime": { "type": "number", "description": "Cooldown period in milliseconds for the buyer to dispute" }, "cooldownTimeOtherParty": { "type": "number", "description": "Cooldown period in milliseconds for the seller to dispute" }, "inputHash": { "type": "string", "description": "SHA256 hash of the input data for the purchase (hex string)" }, "resultHash": { "type": "string", "nullable": true, "description": "SHA256 hash of the result submitted by the seller (hex string)" }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated", "AuthorizeWithdrawalRequested", "AuthorizeWithdrawalInitiated" ], "description": "Next action required for this purchase" }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown", null ], "description": "Type of error that occurred, if any" }, "errorNote": { "type": "string", "nullable": true, "description": "Additional details about the error, if any" } }, "required": [ "requestedAction", "errorType", "errorNote" ], "description": "Next action required for this purchase" }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was last updated" }, "txHash": { "type": "string", "nullable": true, "description": "Cardano transaction hash" }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "Blockchain layer this transaction was submitted to" }, "hydraHeadId": { "type": "string", "nullable": true, "description": "Hydra head ID when this transaction was submitted to L2. Null for L1 transactions" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ], "description": "Current status of the transaction" }, "fees": { "type": "string", "nullable": true, "description": "Fees of the transaction" }, "blockHeight": { "type": "number", "nullable": true, "description": "Block height of the transaction" }, "blockTime": { "type": "number", "nullable": true, "description": "Block time of the transaction" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "Previous on-chain state before this transaction" }, "newOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ], "description": "New on-chain state of this transaction" }, "confirmations": { "type": "number", "nullable": true, "description": "Number of block confirmations for this transaction" } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status", "fees", "blockHeight", "blockTime", "previousOnChainState", "newOnChainState", "confirmations" ], "description": "Current active transaction for this purchase. Null if no transaction in progress" }, "PaidFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForSeller": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "WithdrawnForBuyer": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "amount", "unit" ] } }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true } }, "required": [ "id", "network", "paymentSourceType", "smartContractAddress", "policyId" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the seller wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the seller wallet" } }, "required": [ "id", "walletVkey" ], "description": "Seller wallet information. Null if not set" }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier for the smart contract wallet" }, "walletVkey": { "type": "string", "description": "Payment key hash of the smart contract wallet" }, "walletAddress": { "type": "string", "description": "Cardano address of the smart contract wallet" } }, "required": [ "id", "walletVkey", "walletAddress" ], "description": "Smart contract wallet (seller wallet) managing this purchase. Null if not set" }, "metadata": { "type": "string", "nullable": true, "description": "Optional metadata stored with the purchase for additional context. Null if not provided" } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "agentIdentifier", "agentName", "pricingType", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "totalBuyerCardanoFees", "totalSellerCardanoFees", "nextActionOrOnChainStateOrResultLastChangedAt", "nextActionLastChangedAt", "onChainStateOrResultLastChangedAt", "requestedById", "onChainState", "forceLayer", "paymentForceLayer", "collateralReturnLovelace", "buyerReturnAddress", "sellerReturnAddress", "cooldownTime", "cooldownTimeOtherParty", "inputHash", "resultHash", "NextAction", "CurrentTransaction", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "agentName": "Example Agent", "pricingType": "Fixed", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "payByTime": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "requestedById": "requester_id", "onChainState": null, "forceLayer": null, "paymentForceLayer": null, "collateralReturnLovelace": null, "buyerReturnAddress": null, "sellerReturnAddress": null, "cooldownTime": 0, "cooldownTimeOtherParty": 0, "inputHash": "input_hash", "resultHash": null, "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "PaidFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV1", "smartContractAddress": "address" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (only the creator or an admin can cancel a refund request)" }, "404": { "description": "Purchase not found or in invalid state" }, "500": { "description": "Internal Server Error" } } } }, "/payment/resolve-blockchain-identifier": { "post": { "description": "Resolves a payment request by its blockchain identifier.", "summary": "Resolve a payment request by its blockchain identifier. (READ access required)", "tags": [ "payment" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchainIdentifier": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "The blockchain identifier to resolve" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the purchases were made on" }, "filterSmartContractAddress": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source" }, "includeHistory": { "type": "string", "default": "false", "description": "Whether to include the full transaction and status history of the purchases" } }, "required": [ "blockchainIdentifier", "network" ], "example": { "blockchainIdentifier": "blockchain_identifier", "network": "Preprod", "includeHistory": "false" } } } } }, "responses": { "200": { "description": "Payment request resolved", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "lastCheckedAt": null, "payByTime": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "requestedById": "requester_id", "resultHash": "result_hash", "inputHash": "input_hash", "cooldownTime": 0, "cooldownTimeOtherParty": 0, "collateralReturnLovelace": null, "onChainState": null, "NextAction": { "requestedAction": "WaitingForExternalAction", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "TransactionHistory": [], "RequestedFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "smartContractAddress": "address", "policyId": "policy_id" }, "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment request not found" }, "500": { "description": "Internal Server Error" } } } }, "/purchase/resolve-blockchain-identifier": { "post": { "description": "Resolves a purchase request by its blockchain identifier.", "summary": "Resolve a purchase request by its blockchain identifier. (READ access required)", "tags": [ "purchase" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchainIdentifier": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "The blockchain identifier to resolve" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the purchases were made on" }, "filterSmartContractAddress": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source" }, "includeHistory": { "type": "string", "default": "false", "description": "Whether to include the full transaction and status history of the purchases" } }, "required": [ "blockchainIdentifier", "network" ], "example": { "blockchainIdentifier": "blockchain_identifier", "network": "Preprod", "includeHistory": "false" } } } } }, "responses": { "200": { "description": "Purchase request resolved", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/Purchase" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "blockchainIdentifier": "blockchain_identifier", "agentIdentifier": "agent_identifier", "lastCheckedAt": null, "payByTime": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "requestedById": "requester_id", "onChainState": null, "collateralReturnLovelace": null, "cooldownTime": 0, "cooldownTimeOtherParty": 0, "inputHash": "input_hash", "resultHash": "", "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "TransactionHistory": [], "PaidFunds": [ { "unit": "", "amount": "10000000" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "smartContractAddress": "address", "policyId": "policy_id" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "totalBuyerCardanoFees": 0, "totalSellerCardanoFees": 0, "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z", "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z", "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Purchase request not found" }, "500": { "description": "Internal Server Error" } } } }, "/registry/wallet": { "get": { "description": "Gets the agent metadata.", "summary": "Fetch all agents (and their full metadata) that are registered to a specified wallet. (READ access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 250, "description": "The payment key of the wallet to be queried" }, "required": true, "description": "The payment key of the wallet to be queried", "name": "walletVkey", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the agent on" }, "required": true, "description": "The Cardano network used to register the agent on", "name": "network", "in": "query" }, { "schema": { "type": "string", "maxLength": 250, "description": "The smart contract address of the payment source to which the registration belongs" }, "required": false, "description": "The smart contract address of the payment source to which the registration belongs", "name": "smartContractAddress", "in": "query" } ], "responses": { "200": { "description": "Agent metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Assets": { "type": "array", "items": { "$ref": "#/components/schemas/AgentMetadata" }, "description": "List of agent assets registered to this wallet" } }, "required": [ "Assets" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Assets": [ { "policyId": "policy_id", "assetName": "asset_name", "agentIdentifier": "agent_identifier", "Metadata": { "name": "name", "description": "description", "apiBaseUrl": "api_url", "ExampleOutputs": [], "Tags": [ "tag1", "tag2" ], "Capability": { "name": "capability_name", "version": "capability_version" }, "Legal": { "privacyPolicy": "privacy_policy", "terms": "terms", "other": "other" }, "Author": { "name": "author_name", "contactEmail": "author_contact_email", "contactOther": "author_contact_other", "organization": "author_organization" }, "image": "image", "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "metadataVersion": 1 } } ] } } } } } } } } }, "/registry/agent-identifier": { "get": { "description": "Gets the on-chain metadata for a specific agent by its identifier.", "summary": "Fetch the current metadata for a given agentIdentifier. (READ access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 57, "maxLength": 250, "description": "Full agent identifier (policy ID + asset name in hex)" }, "required": true, "description": "Full agent identifier (policy ID + asset name in hex)", "name": "agentIdentifier", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network (Preprod or Mainnet)" }, "required": true, "description": "The Cardano network (Preprod or Mainnet)", "name": "network", "in": "query" } ], "responses": { "200": { "description": "Agent metadata retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/AgentIdentifierMetadata" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "policyId": "policy_id", "assetName": "asset_name", "agentIdentifier": "policy_id_asset_name", "Metadata": { "name": "Agent Name", "description": "Agent Description", "apiBaseUrl": "https://api.example.com", "ExampleOutputs": [], "Tags": [ "tag1", "tag2" ], "Capability": { "name": "capability_name", "version": "capability_version" }, "Legal": { "privacyPolicy": "privacy_policy", "terms": "terms", "other": "other" }, "Author": { "name": "author_name", "contactEmail": "author_contact_email", "contactOther": "author_contact_other", "organization": "author_organization" }, "image": "ipfs://...", "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "metadataVersion": 1 } } } } } } }, "400": { "description": "Bad Request (agent identifier is not a valid hex string)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Agent identifier not found or network/policyId combination not supported" }, "422": { "description": "Agent metadata is invalid or malformed" }, "500": { "description": "Internal Server Error" } } } }, "/registry": { "get": { "description": "Gets the agent metadata.", "summary": "List every agent that is recorded in the Masumi Registry. (READ access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of registry entries to return" }, "required": false, "description": "The number of registry entries to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "The cursor id to paginate through the results" }, "required": false, "description": "The cursor id to paginate through the results", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the agent on" }, "required": true, "description": "The Cardano network used to register the agent on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no V2-aware filters, registry list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no V2-aware filters, registry list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no source/address/identifier support filters, the endpoint defaults to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no source/address/identifier support filters, the endpoint defaults to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" }, { "schema": { "type": "string", "enum": [ "Registered", "Deregistered", "Pending", "Failed" ], "description": "Filter by registration status category" }, "required": false, "description": "Filter by registration status category", "name": "filterStatus", "in": "query" }, { "schema": { "type": "string", "description": "Search query to filter by name, description, tags, minting or recipient wallet address, state, or price" }, "required": false, "description": "Search query to filter by name, description, tags, minting or recipient wallet address, state, or price", "name": "searchQuery", "in": "query" }, { "schema": { "type": "string", "minLength": 57, "maxLength": 250, "description": "When set, return only the registry entry whose on-chain agent identifier matches exactly (same scope as list: network, payment source, and wallet permissions). This exact lookup does not apply the default Web3CardanoV1 compatibility filter." }, "required": false, "description": "When set, return only the registry entry whose on-chain agent identifier matches exactly (same scope as list: network, payment source, and wallet permissions). This exact lookup does not apply the default Web3CardanoV1 compatibility filter.", "name": "filterAgentIdentifier", "in": "query" }, { "schema": { "type": "string", "description": "Return only entries that advertise a supported payment source with this address (the Cardano smart-contract address, or an EVM x402 payTo/address). Matched server-side so callers do not have to fetch every entry and filter client-side. Combined with filterSupportedPaymentSourceNetworks as a logical OR. This V2-aware filter opts out of the default Web3CardanoV1 compatibility filter." }, "required": false, "description": "Return only entries that advertise a supported payment source with this address (the Cardano smart-contract address, or an EVM x402 payTo/address). Matched server-side so callers do not have to fetch every entry and filter client-side. Combined with filterSupportedPaymentSourceNetworks as a logical OR. This V2-aware filter opts out of the default Web3CardanoV1 compatibility filter.", "name": "filterSupportedPaymentSourceAddress", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated list of supported-payment-source networks to match (Cardano network name, or CAIP-2 EVM chain ids such as eip155:8453). Returns entries advertising a supported payment source on any of these networks. Combined with filterSupportedPaymentSourceAddress as a logical OR. This V2-aware filter opts out of the default Web3CardanoV1 compatibility filter." }, "required": false, "description": "Comma-separated list of supported-payment-source networks to match (Cardano network name, or CAIP-2 EVM chain ids such as eip155:8453). Returns entries advertising a supported payment source on any of these networks. Combined with filterSupportedPaymentSourceAddress as a logical OR. This V2-aware filter opts out of the default Web3CardanoV1 compatibility filter.", "name": "filterSupportedPaymentSourceNetworks", "in": "query" } ], "responses": { "200": { "description": "Agent metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Assets": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryListEntry" } } }, "required": [ "Assets" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Assets": [ { "error": null, "id": "asset_id", "name": "name", "description": "description", "Capability": { "name": "capability_name", "version": "capability_version" }, "Author": { "name": "author_name", "organization": "author_organization", "contactEmail": "author_contact_email", "contactOther": "author_contact_other" }, "Legal": { "privacyPolicy": "privacy_policy", "terms": "terms", "other": "other" }, "state": "RegistrationRequested", "Tags": [ "tag1", "tag2" ], "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": "1970-01-20T20:00:36.260Z", "agentIdentifier": "agent_identifier", "apiBaseUrl": "api_url", "ExampleOutputs": [], "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": { "walletVkey": "recipient_wallet_vkey", "walletAddress": "recipient_wallet_address" }, "CurrentTransaction": null } ] } } } } } } } }, "post": { "description": "Registers an agent to the registry (Please note that while it it is put on-chain, the transaction is not yet finalized by the blockchain, as designed finality is only eventually reached. If you need certainty, please check status via the registry(GET) or if you require custom logic, the transaction directly using the txHash)", "summary": "Registers an agent to the registry (+PAY access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the agent on" }, "type": { "type": "string", "enum": [ "Standard", "OpenApi", "X402", "A2A" ], "description": "The agent access model. Defaults to Standard when omitted (Standard emits no on-chain type field for backwards compatibility). Standard requires apiBaseUrl; OpenApi requires openApiSpecUrl; X402 advertises priced resources; A2A (V2 payment sources only) requires both apiBaseUrl and a2aAgentCardUrl plus a2aProtocolVersions." }, "sellingWalletVkey": { "type": "string", "minLength": 56, "maxLength": 56, "pattern": "^[0-9a-fA-F]{56}$", "description": "The payment key of a specific wallet used for the registration" }, "recipientWalletAddress": { "type": "string", "minLength": 58, "maxLength": 120, "pattern": "^(addr1|addr_test1)[0-9a-z]+$", "description": "Optional managed hot wallet address on the same payment source that should receive the minted registry NFT. If omitted, the minting wallet receives it." }, "sendFundingLovelace": { "type": "string", "maxLength": 17, "pattern": "^\\d+$", "description": "Optional lovelace amount to include with the minted NFT output. If provided below the minimum NFT funding, the current minimum is still used." }, "supportedPaymentSources": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "Cardano" ], "description": "The blockchain this payment source is available on" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network this payment source is available on" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "The configured payment source type" }, "address": { "type": "string", "maxLength": 250, "description": "The escrow smart contract address for this payment source" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "paymentSourceType", "address", "pricing" ] }, { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "EVM" ], "description": "The chain family used by standard x402" }, "network": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 EVM network id, for example eip155:8453" }, "paymentSourceType": { "type": "string", "nullable": true, "enum": [ "Web3CardanoV1", "Web3CardanoV2", null ], "description": "The configured payment source type" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Alias for payTo, kept for existing payment-source shape" }, "scheme": { "type": "string", "enum": [ "Exact" ], "description": "x402 payment scheme" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address receiving the x402 payment" }, "resource": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional absolute resource URL this x402 option protects" }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional x402 metadata" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "scheme", "payTo", "pricing" ] } ] }, "minItems": 1, "maxItems": 25, "description": "Required for V2 registrations and forbidden for V1 registrations. Every V2 source owns its pricing." }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Verification method discriminator, e.g. \"KERI-ACDC\"" }, "schemaVersion": { "type": "string", "maxLength": 16, "description": "Version of this verification block" }, "issuer": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuer KERI AID (ACDC sad.i) — the root trust anchor" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the issuer KEL (key state) for signature verification" } }, "required": [ "aid", "oobi" ], "description": "Credential issuer identity" }, "schema": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential schema SAID (ACDC sad.s)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the JSON schema; a verifier checks its hash equals said" } }, "required": [ "said", "oobi" ], "description": "Credential schema — the ACDC structure definition" }, "credential": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential SAID (ACDC sad.d)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI/endpoint serving the signed ACDC; a verifier checks its hash equals said" }, "registry": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential status registry / TEL SAID (ACDC sad.ri) for independent revocation checks" } }, "required": [ "said", "oobi" ], "description": "The verifiable credential (ACDC)" }, "holder": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuee/holder KERI AID (ACDC sad.a.i)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the holder KEL" } }, "required": [ "aid", "oobi" ], "description": "Credential holder/issuee identity" }, "baseUrl": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional witness/KERIA resolver root for live key-state (\"verify at time T\") and TEL queries" } }, "required": [ "method", "issuer", "schema", "credential", "holder" ] }, "maxItems": 10, "description": "Optional KERI/Veridian verification claims advertised in the registry metadata for independent third-party verification. Accepted on any registration; surfaced in the UI for V2 registries only." }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60, "description": "Name of the example output" }, "url": { "type": "string", "maxLength": 250, "description": "URL to the example output" }, "mimeType": { "type": "string", "maxLength": 60, "description": "MIME type of the example output (e.g., image/png, text/plain)" } }, "required": [ "name", "url", "mimeType" ] }, "maxItems": 25, "description": "List of example outputs from the agent" }, "Tags": { "type": "array", "items": { "type": "string", "maxLength": 63 }, "minItems": 1, "maxItems": 15, "description": "Tags used in the registry metadata" }, "name": { "type": "string", "maxLength": 250, "description": "Name of the agent" }, "apiBaseUrl": { "type": "string", "maxLength": 250, "format": "uri", "description": "Base URL of the agent, to request interactions. Required for Standard-type agents; omit for OpenApi/X402." }, "openApiSpecUrl": { "type": "string", "maxLength": 250, "format": "uri", "description": "URL to the agent OpenAPI 3.1.x specification document (JSON or YAML). Required for OpenApi-type agents; omit for others." }, "x402ResourcesUrl": { "type": "string", "maxLength": 250, "format": "uri", "description": "URL to the agent self-hosted x402 resource manifest (e.g. /.well-known/x402.json): a JSON document listing this agent resources, each { resource, type (http|mcp), inputSchema?, outputSchema? }. Payment stays agent-level (supportedPaymentSources), not per resource. Required for X402-type agents; omit for others." }, "a2aAgentCardUrl": { "type": "string", "maxLength": 250, "format": "uri", "description": "URL to the agent MIP-002 Agent Card JSON document. Required for A2A-type agents (V2 payment sources only), alongside apiBaseUrl; omit for others." }, "a2aProtocolVersions": { "type": "array", "items": { "type": "string", "maxLength": 64, "pattern": "^[0-9]+\\.[0-9]+$" }, "minItems": 1, "maxItems": 10, "description": "A2A protocol versions this agent declares support for. Required and non-empty for A2A-type agents; every value must appear in the fetched Agent Card protocolVersions. Omit for other types." }, "skipAgentCardValidation": { "type": "boolean", "description": "A2A-only override: when true, skip fetching/validating the Agent Card before registering. Ignored for other types." }, "description": { "type": "string", "maxLength": 250, "description": "Description of the agent" }, "Capability": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the AI model/capability" }, "version": { "type": "string", "maxLength": 250, "description": "Version of the AI model/capability" } }, "required": [ "name", "version" ], "description": "Provide information about the used AI model and version" }, "AgentPricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "Pricing type for the agent" }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 250, "description": "Asset policy id + asset name concatenated. Uses an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" } }, "required": [ "unit", "amount" ] }, "minItems": 1, "maxItems": 5, "description": "Price for a default interaction" } }, "required": [ "pricingType", "Pricing" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "Pricing type for the agent" } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "Pricing type for the agent. Amounts are provided per payment/purchase request" } }, "required": [ "pricingType" ] } ], "description": "Required legacy pricing for V1 registrations and forbidden for V2 registrations. V2 pricing belongs inside supportedPaymentSources[].pricing." }, "Legal": { "type": "object", "properties": { "privacyPolicy": { "type": "string", "maxLength": 250, "description": "URL to the privacy policy" }, "terms": { "type": "string", "maxLength": 250, "description": "URL to the terms of service" }, "other": { "type": "string", "maxLength": 250, "description": "Other legal information" } }, "description": "Legal information about the agent" }, "Author": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the agent author" }, "contactEmail": { "type": "string", "maxLength": 250, "description": "Contact email of the author" }, "contactOther": { "type": "string", "maxLength": 250, "description": "Other contact information for the author" }, "organization": { "type": "string", "maxLength": 250, "description": "Organization of the author" } }, "required": [ "name" ], "description": "Author information about the agent" } }, "required": [ "network", "sellingWalletVkey", "ExampleOutputs", "Tags", "name", "description", "Capability", "Author" ], "example": { "network": "Preprod", "ExampleOutputs": [ { "name": "example_output_name", "url": "https://example.com/example_output", "mimeType": "application/json" } ], "Tags": [ "tag1", "tag2" ], "name": "Agent Name", "description": "Agent Description", "Author": { "name": "Author Name", "contactEmail": "author@example.com", "contactOther": "author_contact_other", "organization": "Author Organization" }, "apiBaseUrl": "https://api.example.com", "Legal": { "privacyPolicy": "Privacy Policy URL", "terms": "Terms of Service URL", "other": "Other Legal Information URL" }, "sellingWalletVkey": "wallet_vkey", "recipientWalletAddress": "recipient_wallet_address", "sendFundingLovelace": "7500000", "Capability": { "name": "Capability Name", "version": "1.0.0" }, "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] } } } } } }, "responses": { "200": { "description": "Agent registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/RegistryEntry" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "error": null, "id": "registry_id", "name": "Agent Name", "description": "Agent Description", "type": "Standard", "apiBaseUrl": "https://api.example.com", "openApiSpecUrl": null, "x402ResourcesUrl": null, "a2aAgentCardUrl": null, "a2aProtocolVersions": [], "paymentSourceType": "Web3CardanoV1", "Capability": { "name": "Capability Name", "version": "1.0.0" }, "Author": { "name": "Author Name", "contactEmail": "author@example.com", "contactOther": "contact-other", "organization": "Author Org" }, "Legal": { "privacyPolicy": "https://example.com/privacy", "terms": "https://example.com/terms", "other": "https://example.com/other" }, "state": "RegistrationRequested", "Tags": [ "tag1", "tag2" ], "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "ExampleOutputs": [ { "name": "example_output_name", "url": "https://example.com/example_output", "mimeType": "application/json" } ], "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "sendFundingLovelace": null, "supportedPaymentSources": [ { "chain": "Cardano", "network": "Preprod", "paymentSourceType": "Web3CardanoV2", "address": "addr_test1wz7j4kmg2cs7yf92uat3ed4a3u97kr7axxr4avaz0lhwdsqukgwfm", "pricing": { "pricingType": "Fixed", "fixed": [ { "asset": "", "amount": "1000000" } ] } } ], "verifications": [ { "method": "KERI-ACDC", "schemaVersion": "1", "issuer": { "aid": "EIaIeKvfBLmZf3wfqB0oR1uM5n8m9k2pQ7rT4sV1wX3y", "oobi": "https://witness.example.com/oobi/EIaIeKvfBLmZf3wfqB0oR1uM5n8m9k2pQ7rT4sV1wX3y/witness" }, "schema": { "said": "EJ1gXWfzLyW2u0YY5Zb8c4d6e9f1g3h5j7k9l2m4n6p", "oobi": "https://schema.example.com/oobi/EJ1gXWfzLyW2u0YY5Zb8c4d6e9f1g3h5j7k9l2m4n6p" }, "credential": { "said": "EHpH79tPZoSl7VJZ7xMi3JWF4rH9wZ2ntGvKABd9N14z", "oobi": "https://cred.example.com/oobi/EHpH79tPZoSl7VJZ7xMi3JWF4rH9wZ2ntGvKABd9N14z", "registry": "ER7yQ3kL9mN2pT5vX8a1b4c7d0e3f6g9h2j5k8l1m4n7" }, "holder": { "aid": "EBcd1ef2gh3ij4kl5mn6op7qr8st9uv0wx1yz2ab3cd4", "oobi": "https://keria.example.com/oobi/EBcd1ef2gh3ij4kl5mn6op7qr8st9uv0wx1yz2ab3cd4/agent/EAgnt" }, "baseUrl": "https://verify.example.com" } ], "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } } } } } } } }, "delete": { "description": "Permanently deletes an agent registration record from the database. This action is irreversible and should only be used for registrations in specific failed or completed states.", "summary": "Delete an agent registration record. (admin access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "cuid", "description": "The database ID of the agent registration record to be deleted." } }, "required": [ "id" ], "example": { "id": "example_id" } } } } }, "responses": { "200": { "description": "Agent registration deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/RegistryEntry" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "error": null, "id": "registry_id", "name": "Agent Name", "description": "Agent Description", "type": "Standard", "apiBaseUrl": "https://api.example.com", "openApiSpecUrl": null, "x402ResourcesUrl": null, "a2aAgentCardUrl": null, "a2aProtocolVersions": [], "paymentSourceType": "Web3CardanoV1", "Capability": { "name": "Capability Name", "version": "1.0.0" }, "Author": { "name": "Author Name", "contactEmail": "author@example.com", "contactOther": "contact-other", "organization": "Author Org" }, "Legal": { "privacyPolicy": "https://example.com/privacy", "terms": "https://example.com/terms", "other": "https://example.com/other" }, "state": "RegistrationRequested", "Tags": [ "tag1", "tag2" ], "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "ExampleOutputs": [ { "name": "example_output_name", "url": "https://example.com/example_output", "mimeType": "application/json" } ], "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "sendFundingLovelace": null, "supportedPaymentSources": [ { "chain": "Cardano", "network": "Preprod", "paymentSourceType": "Web3CardanoV2", "address": "addr_test1wz7j4kmg2cs7yf92uat3ed4a3u97kr7axxr4avaz0lhwdsqukgwfm", "pricing": { "pricingType": "Fixed", "fixed": [ { "asset": "", "amount": "1000000" } ] } } ], "verifications": [ { "method": "KERI-ACDC", "schemaVersion": "1", "issuer": { "aid": "EIaIeKvfBLmZf3wfqB0oR1uM5n8m9k2pQ7rT4sV1wX3y", "oobi": "https://witness.example.com/oobi/EIaIeKvfBLmZf3wfqB0oR1uM5n8m9k2pQ7rT4sV1wX3y/witness" }, "schema": { "said": "EJ1gXWfzLyW2u0YY5Zb8c4d6e9f1g3h5j7k9l2m4n6p", "oobi": "https://schema.example.com/oobi/EJ1gXWfzLyW2u0YY5Zb8c4d6e9f1g3h5j7k9l2m4n6p" }, "credential": { "said": "EHpH79tPZoSl7VJZ7xMi3JWF4rH9wZ2ntGvKABd9N14z", "oobi": "https://cred.example.com/oobi/EHpH79tPZoSl7VJZ7xMi3JWF4rH9wZ2ntGvKABd9N14z", "registry": "ER7yQ3kL9mN2pT5vX8a1b4c7d0e3f6g9h2j5k8l1m4n7" }, "holder": { "aid": "EBcd1ef2gh3ij4kl5mn6op7qr8st9uv0wx1yz2ab3cd4", "oobi": "https://keria.example.com/oobi/EBcd1ef2gh3ij4kl5mn6op7qr8st9uv0wx1yz2ab3cd4/agent/EAgnt" }, "baseUrl": "https://verify.example.com" } ], "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } } } } } }, "400": { "description": "Bad Request - Invalid state for deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] }, "example": { "status": "error", "error": { "message": "Agent registration cannot be deleted in its current state: RegistrationRequested" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Agent Registration not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] }, "example": { "status": "error", "error": { "message": "Agent Registration not found" } } } } }, "500": { "description": "Internal Server Error" } } } }, "/registry/diff": { "get": { "description": "Returns registry entries that changed since the provided timestamp (registrationStateLastChangedAt).", "summary": "Diff registry entries by state-change timestamp (READ access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of registry entries to return" }, "required": false, "description": "The number of registry entries to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor (registry request id). Used as tie-breaker when lastUpdate equals a state-change timestamp" }, "required": false, "description": "Pagination cursor (registry request id). Used as tie-breaker when lastUpdate equals a state-change timestamp", "name": "cursorId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "default": "1970-01-01T00:00:00.000Z", "description": "Return registry entries whose registration state changed at/after this ISO timestamp" }, "required": false, "description": "Return registry entries whose registration state changed at/after this ISO timestamp", "name": "lastUpdate", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the agent on" }, "required": true, "description": "The Cardano network used to register the agent on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, registry diff defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted with no explicit payment source type, registry diff defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted with no smart-contract-address filter, registry diff defaults to Web3CardanoV1 for backwards compatibility." }, "required": false, "description": "Filter by payment source type. When omitted with no smart-contract-address filter, registry diff defaults to Web3CardanoV1 for backwards compatibility.", "name": "filterPaymentSourceType", "in": "query" } ], "responses": { "200": { "description": "Agent metadata diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Assets": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryListEntry" } } }, "required": [ "Assets" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/registry/deregister": { "post": { "description": "Deregisters a agent from the specified registry (Please note that while the command is put on-chain, the transaction is not yet finalized by the blockchain, as designed finality is only eventually reached. If you need certainty, please check status via the registry(GET) or if you require custom logic, the transaction directly using the txHash)", "summary": "Deregisters an agent from the specified registry. (PAY access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentIdentifier": { "type": "string", "minLength": 57, "maxLength": 250, "pattern": "^[0-9a-fA-F]+$", "description": "The identifier of the registration (asset) to be deregistered" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the registration was made on" }, "smartContractAddress": { "type": "string", "minLength": 58, "maxLength": 120, "pattern": "^(addr1|addr_test1)[0-9a-z]+$", "description": "The smart contract address of the payment contract to which the registration belongs" } }, "required": [ "agentIdentifier", "network" ], "example": { "agentIdentifier": "agentIdentifier", "network": "Preprod" } } } } }, "responses": { "200": { "description": "Agent deregistration requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/RegistryEntry" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "error": null, "id": "registry_id", "name": "Agent Name", "description": "Agent Description", "type": "Standard", "apiBaseUrl": "https://api.example.com", "openApiSpecUrl": null, "x402ResourcesUrl": null, "a2aAgentCardUrl": null, "a2aProtocolVersions": [], "paymentSourceType": "Web3CardanoV1", "Capability": { "name": "Capability Name", "version": "1.0.0" }, "Author": { "name": "Author Name", "contactEmail": "author@example.com", "contactOther": "contact-other", "organization": "Author Org" }, "Legal": { "privacyPolicy": "https://example.com/privacy", "terms": "https://example.com/terms", "other": "https://example.com/other" }, "state": "RegistrationRequested", "Tags": [ "tag1", "tag2" ], "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "ExampleOutputs": [ { "name": "example_output_name", "url": "https://example.com/example_output", "mimeType": "application/json" } ], "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "sendFundingLovelace": null, "supportedPaymentSources": [ { "chain": "Cardano", "network": "Preprod", "paymentSourceType": "Web3CardanoV2", "address": "addr_test1wz7j4kmg2cs7yf92uat3ed4a3u97kr7axxr4avaz0lhwdsqukgwfm", "pricing": { "pricingType": "Fixed", "fixed": [ { "asset": "", "amount": "1000000" } ] } } ], "verifications": [ { "method": "KERI-ACDC", "schemaVersion": "1", "issuer": { "aid": "EIaIeKvfBLmZf3wfqB0oR1uM5n8m9k2pQ7rT4sV1wX3y", "oobi": "https://witness.example.com/oobi/EIaIeKvfBLmZf3wfqB0oR1uM5n8m9k2pQ7rT4sV1wX3y/witness" }, "schema": { "said": "EJ1gXWfzLyW2u0YY5Zb8c4d6e9f1g3h5j7k9l2m4n6p", "oobi": "https://schema.example.com/oobi/EJ1gXWfzLyW2u0YY5Zb8c4d6e9f1g3h5j7k9l2m4n6p" }, "credential": { "said": "EHpH79tPZoSl7VJZ7xMi3JWF4rH9wZ2ntGvKABd9N14z", "oobi": "https://cred.example.com/oobi/EHpH79tPZoSl7VJZ7xMi3JWF4rH9wZ2ntGvKABd9N14z", "registry": "ER7yQ3kL9mN2pT5vX8a1b4c7d0e3f6g9h2j5k8l1m4n7" }, "holder": { "aid": "EBcd1ef2gh3ij4kl5mn6op7qr8st9uv0wx1yz2ab3cd4", "oobi": "https://keria.example.com/oobi/EBcd1ef2gh3ij4kl5mn6op7qr8st9uv0wx1yz2ab3cd4/agent/EAgnt" }, "baseUrl": "https://verify.example.com" } ], "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } } } } } } } } }, "/registry/update": { "post": { "description": "Updates the metadata of an existing agent registration by issuing an UpdateAction on the V2 registry mint contract (atomically burns the current asset and mints a new one with the version segment incremented by one). Web3CardanoV2 only. Please note that while the command is put on-chain, the transaction is not yet finalized by the blockchain, as designed finality is only eventually reached.", "summary": "Update an existing agent registration (V2 only, +PAY access required)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the agent on" }, "type": { "type": "string", "enum": [ "Standard", "OpenApi", "X402", "A2A" ], "description": "The agent access model. Defaults to Standard when omitted (Standard emits no on-chain type field for backwards compatibility). Standard requires apiBaseUrl; OpenApi requires openApiSpecUrl; X402 advertises priced resources; A2A (V2 payment sources only) requires both apiBaseUrl and a2aAgentCardUrl plus a2aProtocolVersions." }, "recipientWalletAddress": { "type": "string", "minLength": 58, "maxLength": 120, "pattern": "^(addr1|addr_test1)[0-9a-z]+$", "description": "Optional managed hot wallet address on the same payment source that should receive the minted registry NFT. If omitted, the minting wallet receives it." }, "sendFundingLovelace": { "type": "string", "maxLength": 17, "pattern": "^\\d+$", "description": "Optional lovelace amount to include with the minted NFT output. If provided below the minimum NFT funding, the current minimum is still used." }, "supportedPaymentSources": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "Cardano" ], "description": "The blockchain this payment source is available on" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network this payment source is available on" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "The configured payment source type" }, "address": { "type": "string", "maxLength": 250, "description": "The escrow smart contract address for this payment source" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "paymentSourceType", "address", "pricing" ] }, { "type": "object", "properties": { "chain": { "type": "string", "enum": [ "EVM" ], "description": "The chain family used by standard x402" }, "network": { "type": "string", "pattern": "^eip155:\\d+$", "description": "CAIP-2 EVM network id, for example eip155:8453" }, "paymentSourceType": { "type": "string", "nullable": true, "enum": [ "Web3CardanoV1", "Web3CardanoV2", null ], "description": "The configured payment source type" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Alias for payTo, kept for existing payment-source shape" }, "scheme": { "type": "string", "enum": [ "Exact" ], "description": "x402 payment scheme" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address receiving the x402 payment" }, "resource": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional absolute resource URL this x402 option protects" }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional x402 metadata" }, "pricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "A fixed amount is advertised for this payment source" }, "fixed": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Chain-native asset identifier" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "Atomic token amount" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset", "amount" ] }, "minItems": 1, "maxItems": 5 } }, "required": [ "pricingType", "fixed" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "The exact positive amount is supplied dynamically for each payment request" }, "dynamic": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 250, "description": "Optional accepted asset identifier" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Asset decimals when required by the rail" } }, "required": [ "asset" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "This payment source does not require payment" } }, "required": [ "pricingType" ] } ] } }, "required": [ "chain", "network", "scheme", "payTo", "pricing" ] } ] }, "minItems": 1, "maxItems": 25, "description": "Payment sources to replace on this V2 registry request. Omit the field to keep existing sources; an empty array is invalid." }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Verification method discriminator, e.g. \"KERI-ACDC\"" }, "schemaVersion": { "type": "string", "maxLength": 16, "description": "Version of this verification block" }, "issuer": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuer KERI AID (ACDC sad.i) — the root trust anchor" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the issuer KEL (key state) for signature verification" } }, "required": [ "aid", "oobi" ], "description": "Credential issuer identity" }, "schema": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential schema SAID (ACDC sad.s)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the JSON schema; a verifier checks its hash equals said" } }, "required": [ "said", "oobi" ], "description": "Credential schema — the ACDC structure definition" }, "credential": { "type": "object", "properties": { "said": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential SAID (ACDC sad.d)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI/endpoint serving the signed ACDC; a verifier checks its hash equals said" }, "registry": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Credential status registry / TEL SAID (ACDC sad.ri) for independent revocation checks" } }, "required": [ "said", "oobi" ], "description": "The verifiable credential (ACDC)" }, "holder": { "type": "object", "properties": { "aid": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Issuee/holder KERI AID (ACDC sad.a.i)" }, "oobi": { "type": "string", "maxLength": 500, "format": "uri", "description": "OOBI resolving the holder KEL" } }, "required": [ "aid", "oobi" ], "description": "Credential holder/issuee identity" }, "baseUrl": { "type": "string", "maxLength": 500, "format": "uri", "description": "Optional witness/KERIA resolver root for live key-state (\"verify at time T\") and TEL queries" } }, "required": [ "method", "issuer", "schema", "credential", "holder" ] }, "maxItems": 10, "description": "Optional KERI/Veridian verification claims advertised in the registry metadata for independent third-party verification. Accepted on any registration; surfaced in the UI for V2 registries only." }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60, "description": "Name of the example output" }, "url": { "type": "string", "maxLength": 250, "description": "URL to the example output" }, "mimeType": { "type": "string", "maxLength": 60, "description": "MIME type of the example output (e.g., image/png, text/plain)" } }, "required": [ "name", "url", "mimeType" ] }, "maxItems": 25, "description": "List of example outputs from the agent" }, "Tags": { "type": "array", "items": { "type": "string", "maxLength": 63 }, "minItems": 1, "maxItems": 15, "description": "Tags used in the registry metadata" }, "name": { "type": "string", "maxLength": 250, "description": "Name of the agent" }, "apiBaseUrl": { "type": "string", "maxLength": 250, "format": "uri", "description": "Base URL of the agent, to request interactions. Required for Standard-type agents; omit for OpenApi/X402." }, "openApiSpecUrl": { "type": "string", "maxLength": 250, "format": "uri", "description": "URL to the agent OpenAPI 3.1.x specification document (JSON or YAML). Required for OpenApi-type agents; omit for others." }, "x402ResourcesUrl": { "type": "string", "maxLength": 250, "format": "uri", "description": "URL to the agent self-hosted x402 resource manifest (e.g. /.well-known/x402.json): a JSON document listing this agent resources, each { resource, type (http|mcp), inputSchema?, outputSchema? }. Payment stays agent-level (supportedPaymentSources), not per resource. Required for X402-type agents; omit for others." }, "a2aAgentCardUrl": { "type": "string", "maxLength": 250, "format": "uri", "description": "URL to the agent MIP-002 Agent Card JSON document. Required for A2A-type agents (V2 payment sources only), alongside apiBaseUrl; omit for others." }, "a2aProtocolVersions": { "type": "array", "items": { "type": "string", "maxLength": 64, "pattern": "^[0-9]+\\.[0-9]+$" }, "minItems": 1, "maxItems": 10, "description": "A2A protocol versions this agent declares support for. Required and non-empty for A2A-type agents; every value must appear in the fetched Agent Card protocolVersions. Omit for other types." }, "skipAgentCardValidation": { "type": "boolean", "description": "A2A-only override: when true, skip fetching/validating the Agent Card before registering. Ignored for other types." }, "description": { "type": "string", "maxLength": 250, "description": "Description of the agent" }, "Capability": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the AI model/capability" }, "version": { "type": "string", "maxLength": 250, "description": "Version of the AI model/capability" } }, "required": [ "name", "version" ], "description": "Provide information about the used AI model and version" }, "AgentPricing": { "anyOf": [ { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ], "description": "Pricing type for the agent" }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 250, "description": "Asset policy id + asset name concatenated. Uses an empty string for ADA/lovelace e.g (1000000 lovelace = 1 ADA)" }, "amount": { "type": "string", "maxLength": 19, "pattern": "^\\d+$", "description": "The quantity of the asset. Make sure to convert it from the underlying smallest unit (in case of decimals, multiply it by the decimal factor e.g. for 1 ADA = 1000000 lovelace)" } }, "required": [ "unit", "amount" ] }, "minItems": 1, "maxItems": 5, "description": "Price for a default interaction" } }, "required": [ "pricingType", "Pricing" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Free" ], "description": "Pricing type for the agent" } }, "required": [ "pricingType" ] }, { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Dynamic" ], "description": "Pricing type for the agent. Amounts are provided per payment/purchase request" } }, "required": [ "pricingType" ] } ], "description": "Required legacy pricing for V1 registrations and forbidden for V2 registrations. V2 pricing belongs inside supportedPaymentSources[].pricing." }, "Legal": { "type": "object", "properties": { "privacyPolicy": { "type": "string", "maxLength": 250, "description": "URL to the privacy policy" }, "terms": { "type": "string", "maxLength": 250, "description": "URL to the terms of service" }, "other": { "type": "string", "maxLength": 250, "description": "Other legal information" } }, "description": "Legal information about the agent" }, "Author": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250, "description": "Name of the agent author" }, "contactEmail": { "type": "string", "maxLength": 250, "description": "Contact email of the author" }, "contactOther": { "type": "string", "maxLength": 250, "description": "Other contact information for the author" }, "organization": { "type": "string", "maxLength": 250, "description": "Organization of the author" } }, "required": [ "name" ], "description": "Author information about the agent" }, "agentIdentifier": { "type": "string", "minLength": 57, "maxLength": 250, "pattern": "^[0-9a-fA-F]+$", "description": "The current on-chain identifier of the agent registration to update" }, "smartContractAddress": { "type": "string", "minLength": 58, "maxLength": 120, "pattern": "^(addr1|addr_test1)[0-9a-z]+$", "description": "The smart contract address of the payment source the registration belongs to" } }, "required": [ "network", "ExampleOutputs", "Tags", "name", "description", "Capability", "Author", "agentIdentifier" ], "example": { "agentIdentifier": "agentIdentifier", "network": "Preprod", "name": "Agent Name", "apiBaseUrl": "https://api.example.com", "description": "Updated agent description", "Tags": [ "ai" ], "ExampleOutputs": [], "Capability": { "name": "capability_name", "version": "1.0.0" }, "Author": { "name": "Author Name" }, "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] } } } } } }, "responses": { "200": { "description": "Agent update requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/RegistryEntry" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "error": null, "id": "registry_id", "name": "Agent Name", "description": "Agent Description", "type": "Standard", "apiBaseUrl": "https://api.example.com", "openApiSpecUrl": null, "x402ResourcesUrl": null, "a2aAgentCardUrl": null, "a2aProtocolVersions": [], "paymentSourceType": "Web3CardanoV1", "Capability": { "name": "Capability Name", "version": "1.0.0" }, "Author": { "name": "Author Name", "contactEmail": "author@example.com", "contactOther": "contact-other", "organization": "Author Org" }, "Legal": { "privacyPolicy": "https://example.com/privacy", "terms": "https://example.com/terms", "other": "https://example.com/other" }, "state": "RegistrationRequested", "Tags": [ "tag1", "tag2" ], "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "ExampleOutputs": [ { "name": "example_output_name", "url": "https://example.com/example_output", "mimeType": "application/json" } ], "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "sendFundingLovelace": null, "supportedPaymentSources": [ { "chain": "Cardano", "network": "Preprod", "paymentSourceType": "Web3CardanoV2", "address": "addr_test1wz7j4kmg2cs7yf92uat3ed4a3u97kr7axxr4avaz0lhwdsqukgwfm", "pricing": { "pricingType": "Fixed", "fixed": [ { "asset": "", "amount": "1000000" } ] } } ], "verifications": [ { "method": "KERI-ACDC", "schemaVersion": "1", "issuer": { "aid": "EIaIeKvfBLmZf3wfqB0oR1uM5n8m9k2pQ7rT4sV1wX3y", "oobi": "https://witness.example.com/oobi/EIaIeKvfBLmZf3wfqB0oR1uM5n8m9k2pQ7rT4sV1wX3y/witness" }, "schema": { "said": "EJ1gXWfzLyW2u0YY5Zb8c4d6e9f1g3h5j7k9l2m4n6p", "oobi": "https://schema.example.com/oobi/EJ1gXWfzLyW2u0YY5Zb8c4d6e9f1g3h5j7k9l2m4n6p" }, "credential": { "said": "EHpH79tPZoSl7VJZ7xMi3JWF4rH9wZ2ntGvKABd9N14z", "oobi": "https://cred.example.com/oobi/EHpH79tPZoSl7VJZ7xMi3JWF4rH9wZ2ntGvKABd9N14z", "registry": "ER7yQ3kL9mN2pT5vX8a1b4c7d0e3f6g9h2j5k8l1m4n7" }, "holder": { "aid": "EBcd1ef2gh3ij4kl5mn6op7qr8st9uv0wx1yz2ab3cd4", "oobi": "https://keria.example.com/oobi/EBcd1ef2gh3ij4kl5mn6op7qr8st9uv0wx1yz2ab3cd4/agent/EAgnt" }, "baseUrl": "https://verify.example.com" } ], "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } } } } } } } } }, "/payment-source": { "get": { "description": "Gets the payment source.", "summary": "List payment sources with their public details. (READ access required)", "tags": [ "payment-source" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of payment sources to return" }, "required": false, "description": "The number of payment sources to return", "name": "take", "in": "query" }, { "schema": { "type": "string", "maxLength": 250, "description": "Used to paginate through the payment sources" }, "required": false, "description": "Used to paginate through the payment sources", "name": "cursorId", "in": "query" } ], "responses": { "200": { "description": "Payment source status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "PaymentSources": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentSource" }, "description": "List of payment sources" } }, "required": [ "PaymentSources" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "PaymentSources": [ { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "network": "Mainnet", "smartContractAddress": "address_of_the_smart_contract", "policyId": "policy_id", "AdminWallets": [ { "walletAddress": "wallet_address", "order": 0 }, { "walletAddress": "wallet_address", "order": 1 }, { "walletAddress": "wallet_address", "order": 2 } ], "feeRatePermille": 50, "FeeReceiverNetworkWallet": { "walletAddress": "wallet_address" }, "lastCheckedAt": "1970-01-20T20:00:36.260Z", "lastIdentifierChecked": "identifier" } ] } } } } } } } } }, "/payment-source-extended": { "get": { "description": "Gets the payment contracts including the status.", "summary": "List payment sources with their public details augmented with internal configuration and sync status information. (read access required)", "tags": [ "payment-source" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of payment sources to return" }, "required": false, "description": "The number of payment sources to return", "name": "take", "in": "query" }, { "schema": { "type": "string", "maxLength": 250, "description": "Used to paginate through the payment sources" }, "required": false, "description": "Used to paginate through the payment sources", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Restrict results to a single Cardano network (still bounded by the key network limit)" }, "required": false, "description": "Restrict results to a single Cardano network (still bounded by the key network limit)", "name": "network", "in": "query" } ], "responses": { "200": { "description": "Payment source status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "ExtendedPaymentSources": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentSourceExtended" }, "description": "List of payment sources with extended details including RPC configuration" } }, "required": [ "ExtendedPaymentSources" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "ExtendedPaymentSources": [ { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "network": "Mainnet", "paymentSourceType": "Web3CardanoV1", "requiredAdminSignatures": null, "feeRatePermille": 50, "syncInProgress": true, "policyId": "policy_id", "smartContractAddress": "address_of_the_smart_contract", "contractSyncStatus": "in_sync", "AdminWallets": [ { "walletAddress": "wallet_address", "order": 0 }, { "walletAddress": "wallet_address", "order": 1 }, { "walletAddress": "wallet_address", "order": 2 } ], "PurchasingWalletsCount": 1, "SellingWalletsCount": 1, "FeeReceiverNetworkWallet": { "walletAddress": "wallet_address" }, "lastCheckedAt": "1970-01-20T20:00:36.260Z", "lastIdentifierChecked": "identifier", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key_blockfrost", "rpcProvider": "Blockfrost" } } ] } } } } } } } }, "post": { "description": "Creates a payment source.", "summary": "Create a new payment source. (+ADMIN access required)", "tags": [ "payment-source" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the payment source will be used on" }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "default": "Web3CardanoV1", "description": "The payment source type to create. Defaults to Web3CardanoV1 for backward compatibility: pre-V2 automation that omits this field (and supplies feeRatePermille / FeeReceiverNetworkWallet / 3 admin wallets) continues to create a V1 source unchanged. New V2 callers must set this explicitly (the admin UI does)." }, "PaymentSourceConfig": { "type": "object", "properties": { "rpcProviderApiKey": { "type": "string", "maxLength": 250, "description": "The rpc provider (blockfrost) api key to be used for the payment source" }, "rpcProvider": { "type": "string", "enum": [ "Blockfrost" ], "description": "The rpc provider to be used for the payment source" } }, "required": [ "rpcProviderApiKey", "rpcProvider" ] }, "feeRatePermille": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1000, "description": "The fee in permille to be used for the payment source. The default contract uses 50 (5%)" }, "cooldownTime": { "type": "number", "nullable": true, "minimum": 0, "description": "The cooldown time in milliseconds to be used for the payment source. The default contract uses 1000 * 60 * 7 (7 minutes)" }, "AdminWallets": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string", "maxLength": 250, "description": "Cardano address of the admin wallet" } }, "required": [ "walletAddress" ] }, "minItems": 1, "maxItems": 50, "description": "V2 admin wallet slots. Repeated addresses ARE permitted and intentional: each entry is an independent voting slot, so the same Cardano address can be added multiple times to give that key proportionally more weight in the M-of-N quorum. Example: [addrA, addrA, addrB] with requiredAdminSignatures=2 means addrA alone satisfies the quorum (2 weighted slots) while addrB alone does not. No distinct-address check is enforced server-side — duplicates are by design, not a bug. Auditing operators must reason about effective vote weight, not raw row count." }, "requiredAdminSignatures": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Required weighted admin signatures for Web3CardanoV2 dispute settlement. Minimum 1 (single-admin custody is allowed by design — operators choosing this trade fast settlement for centralized control). Weight is counted by AdminWallets row position, so duplicate addresses inflate effective weight; see AdminWallets docs." }, "FeeReceiverNetworkWallet": { "type": "object", "properties": { "walletAddress": { "type": "string", "maxLength": 250, "description": "Cardano address that receives network fees" } }, "required": [ "walletAddress" ], "description": "The wallet address of the network fee receiver wallet" }, "PurchasingWallets": { "type": "array", "items": { "type": "object", "properties": { "walletMnemonic": { "type": "string", "maxLength": 1500, "description": "24-word mnemonic phrase for the purchasing wallet. IMPORTANT: Backup this securely" }, "collectionAddress": { "type": "string", "nullable": true, "maxLength": 250, "description": "The collection address of the purchasing wallet" }, "note": { "type": "string", "maxLength": 250, "description": "Note about this purchasing wallet" } }, "required": [ "walletMnemonic", "collectionAddress", "note" ] }, "minItems": 1, "maxItems": 50, "description": "The mnemonic of the purchasing wallets to be added. Please backup the mnemonic of the wallets." }, "SellingWallets": { "type": "array", "items": { "type": "object", "properties": { "walletMnemonic": { "type": "string", "maxLength": 1500, "description": "24-word mnemonic phrase for the selling wallet" }, "collectionAddress": { "type": "string", "nullable": true, "maxLength": 250, "description": "The collection address of the selling wallet" }, "note": { "type": "string", "maxLength": 250, "description": "Note about this selling wallet" } }, "required": [ "walletMnemonic", "collectionAddress", "note" ] }, "minItems": 1, "maxItems": 50, "description": "The mnemonic of the selling wallets to be added. Please backup the mnemonic of the wallets." } }, "required": [ "network", "PaymentSourceConfig", "AdminWallets", "PurchasingWallets", "SellingWallets" ], "example": { "network": "Preprod", "paymentSourceType": "Web3CardanoV2", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key", "rpcProvider": "Blockfrost" }, "AdminWallets": [ { "walletAddress": "wallet_address_1" }, { "walletAddress": "wallet_address_2" }, { "walletAddress": "wallet_address_3" } ], "requiredAdminSignatures": 2, "PurchasingWallets": [ { "walletMnemonic": "wallet mnemonic", "note": "note", "collectionAddress": null } ], "SellingWallets": [ { "walletMnemonic": "wallet mnemonic", "note": "note", "collectionAddress": "collection_address" } ] } } } } }, "responses": { "200": { "description": "Payment source created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/PaymentSourceExtended" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "network": "Mainnet", "paymentSourceType": "Web3CardanoV1", "requiredAdminSignatures": null, "policyId": "policy_id", "smartContractAddress": "address_of_the_smart_contract", "contractSyncStatus": "in_sync", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key_blockfrost", "rpcProvider": "Blockfrost" }, "lastIdentifierChecked": "identifier", "syncInProgress": true, "lastCheckedAt": "1970-01-20T20:00:36.260Z", "AdminWallets": [ { "walletAddress": "wallet_address", "order": 0 }, { "walletAddress": "wallet_address", "order": 1 }, { "walletAddress": "wallet_address", "order": 2 } ], "FeeReceiverNetworkWallet": { "walletAddress": "wallet_address" }, "PurchasingWalletsCount": 1, "SellingWalletsCount": 1, "feeRatePermille": 50 } } } } } } } }, "patch": { "description": "Updates a payment source.", "summary": "Update an existing payment source. (+ADMIN access required)", "tags": [ "payment-source" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 250, "description": "The id of the payment source to be updated" }, "PaymentSourceConfig": { "type": "object", "properties": { "rpcProviderApiKey": { "type": "string", "maxLength": 250, "description": "The rpc provider (blockfrost) api key to be used for the payment source" }, "rpcProvider": { "type": "string", "enum": [ "Blockfrost" ], "description": "The rpc provider to be used for the payment contract" } }, "required": [ "rpcProviderApiKey", "rpcProvider" ] }, "AddPurchasingWallets": { "type": "array", "items": { "type": "object", "properties": { "walletMnemonic": { "type": "string", "maxLength": 1500, "description": "24-word mnemonic phrase for the purchasing wallet. IMPORTANT: Backup this securely" }, "note": { "type": "string", "maxLength": 250, "description": "Note about this purchasing wallet" }, "collectionAddress": { "type": "string", "nullable": true, "maxLength": 250, "description": "The collection address of the purchasing wallet" } }, "required": [ "walletMnemonic", "note", "collectionAddress" ] }, "minItems": 1, "maxItems": 10, "description": "The mnemonic of the purchasing wallets to be added" }, "AddSellingWallets": { "type": "array", "items": { "type": "object", "properties": { "walletMnemonic": { "type": "string", "maxLength": 1500, "description": "24-word mnemonic phrase for the selling wallet" }, "note": { "type": "string", "maxLength": 250, "description": "Note about this selling wallet" }, "collectionAddress": { "type": "string", "nullable": true, "maxLength": 250, "description": "The collection address of the selling wallet" } }, "required": [ "walletMnemonic", "note", "collectionAddress" ] }, "minItems": 1, "maxItems": 10, "description": "The mnemonic of the selling wallets to be added" }, "RemovePurchasingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the purchasing wallet to remove" } }, "required": [ "id" ] }, "maxItems": 10, "description": "The ids of the purchasing wallets to be removed. Please backup the mnemonic of the old wallet before removing it." }, "RemoveSellingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the selling wallet to remove" } }, "required": [ "id" ] }, "maxItems": 10, "description": "The ids of the selling wallets to be removed. Please backup the mnemonic of the old wallet before removing it." }, "lastIdentifierChecked": { "type": "string", "nullable": true, "maxLength": 250, "description": "The latest identifier of the payment source. Usually should not be changed" } }, "required": [ "id" ], "example": { "id": "unique_cuid_v2", "lastIdentifierChecked": "optional_identifier", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key", "rpcProvider": "Blockfrost" }, "AddPurchasingWallets": [ { "walletMnemonic": "wallet_mnemonic", "note": "note", "collectionAddress": "refunds_will_be_sent_to_this_address" } ], "AddSellingWallets": [ { "walletMnemonic": "wallet_mnemonic", "note": "note", "collectionAddress": "revenue_will_be_sent_to_this_address" } ], "RemovePurchasingWallets": [ { "id": "unique_cuid_v2" } ], "RemoveSellingWallets": [ { "id": "unique_cuid_v2" } ] } } } } }, "responses": { "200": { "description": "Payment contract updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/PaymentSourceExtended" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "network": "Mainnet", "paymentSourceType": "Web3CardanoV1", "requiredAdminSignatures": null, "policyId": "policy_id", "smartContractAddress": "address_of_the_smart_contract", "contractSyncStatus": "in_sync", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key_blockfrost", "rpcProvider": "Blockfrost" }, "lastIdentifierChecked": "identifier", "syncInProgress": true, "lastCheckedAt": "1970-01-20T20:00:36.260Z", "AdminWallets": [ { "walletAddress": "wallet_address", "order": 0 }, { "walletAddress": "wallet_address", "order": 1 }, { "walletAddress": "wallet_address", "order": 2 } ], "FeeReceiverNetworkWallet": { "walletAddress": "wallet_address" }, "PurchasingWalletsCount": 1, "SellingWalletsCount": 1, "feeRatePermille": 50 } } } } } }, "400": { "description": "A wallet listed for removal is a fund wallet, which must be deleted via the fund wallet endpoint instead" } } }, "delete": { "description": "Deletes a payment source. WARNING will also delete all associated wallets and transactions.", "summary": "Delete an existing payment source. (+ADMIN access required)", "tags": [ "payment-source" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the payment source to be deleted" } }, "required": [ "id" ], "example": { "id": "unique_cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Payment source deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/PaymentSourceExtended" } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "network": "Mainnet", "paymentSourceType": "Web3CardanoV1", "requiredAdminSignatures": null, "policyId": "policy_id", "smartContractAddress": "address_of_the_smart_contract", "contractSyncStatus": "in_sync", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key_blockfrost", "rpcProvider": "Blockfrost" }, "lastIdentifierChecked": "identifier", "syncInProgress": true, "lastCheckedAt": "1970-01-20T20:00:36.260Z", "AdminWallets": [ { "walletAddress": "wallet_address", "order": 0 }, { "walletAddress": "wallet_address", "order": 1 }, { "walletAddress": "wallet_address", "order": 2 } ], "FeeReceiverNetworkWallet": { "walletAddress": "wallet_address" }, "PurchasingWalletsCount": 1, "SellingWalletsCount": 1, "feeRatePermille": 50 } } } } } } } } }, "/utxos": { "get": { "description": "Gets UTXOs (internal)", "summary": "Helper endpoint that lets you ask the payment service for the current UTXOs sitting at a particular Cardano address. (READ access required)", "tags": [ "utxos" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 150, "description": "The address to get the UTXOs for" }, "required": true, "description": "The address to get the UTXOs for", "name": "address", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network" }, "required": true, "description": "The Cardano network", "name": "network", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of UTXOs to get" }, "required": false, "description": "The number of UTXOs to get", "name": "count", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1, "description": "The page number to get" }, "required": false, "description": "The page number to get", "name": "page", "in": "query" }, { "schema": { "type": "string", "enum": [ "Asc", "Desc" ], "default": "Desc", "description": "The order to get the UTXOs in" }, "required": false, "description": "The order to get the UTXOs in", "name": "order", "in": "query" } ], "responses": { "200": { "description": "UTXOs", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Utxos": { "type": "array", "items": { "$ref": "#/components/schemas/Utxo" }, "description": "List of UTXOs for the specified address" } }, "required": [ "Utxos" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Utxos": [ { "txHash": "tx_hash", "address": "addr1qx2ej34k567890", "Amounts": [ { "unit": "", "quantity": 10000000 } ], "outputIndex": 1, "block": "1", "dataHash": "data_hash", "inlineDatum": "inline_datum", "referenceScriptHash": "reference_script_hash" } ] } } } } } } } } }, "/balance": { "get": { "description": "Gets an address balance (internal)", "summary": "Helper endpoint that returns the complete confirmed balance at a Cardano address, independent of UTXO pagination. (READ access required)", "tags": [ "balance" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 150, "description": "The address to get the confirmed balance for" }, "required": true, "description": "The address to get the confirmed balance for", "name": "address", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network" }, "required": true, "description": "The Cardano network", "name": "network", "in": "query" } ], "responses": { "200": { "description": "Complete confirmed address balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Balance": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceAmount" }, "description": "Complete confirmed address balance aggregated across all UTXOs" } }, "required": [ "Balance" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Balance": [ { "unit": "lovelace", "quantity": 10000000 } ] } } } } } } } } }, "/rpc-api-keys": { "get": { "description": "Gets rpc api keys, currently only blockfrost is supported (internal)", "summary": "List Blockfrost API keys. (admin access required)", "tags": [ "rpc-api-keys" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Used to paginate through the rpc provider keys" }, "required": false, "description": "Used to paginate through the rpc provider keys", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 100, "description": "The number of rpc provider keys to return" }, "required": false, "description": "The number of rpc provider keys to return", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Blockfrost keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "RpcProviderKeys": { "type": "array", "items": { "$ref": "#/components/schemas/RpcProviderKey" }, "description": "List of RPC provider keys" } }, "required": [ "RpcProviderKeys" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "RpcProviderKeys": [ { "network": "Preprod", "id": "unique_cuid_v2", "rpcProviderApiKey": "blockfrost_api_key", "rpcProvider": "Blockfrost", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z" } ] } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/purchase/spending": { "post": { "description": "Get agent spending, fees, and volume analytics for Purchase Request transactions only, over specified time periods.", "summary": "Get agent purchase spending analytics. (READ access required)", "tags": [ "purchase-spending" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentIdentifier": { "type": "string", "nullable": true, "minLength": 57, "maxLength": 250, "description": "The unique identifier of the agent to get purchase spending for, if not provided, will return spending for all agents" }, "startDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" }, { "nullable": true } ], "description": "Start date for spending calculation (date format: 2024-01-01). If null, uses earliest available data. If provided, will be converted to the local time zone of the user" }, "endDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" }, { "nullable": true } ], "description": "End date for spending calculation (date format: 2024-01-31). If null, uses current date. If provided, will be converted to the local time zone of the user" }, "timeZone": { "type": "string", "default": "Etc/UTC", "description": "The time zone to use for the spending calculation. If not provided, will use the UTC time zone. Must be a valid IANA time zone name, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network to query spending from" }, "filterPaymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted, spending totals default to Web3CardanoV1 for backwards compatibility." } }, "required": [ "agentIdentifier", "network" ], "example": { "agentIdentifier": "example_agent_identifier_asset_id", "startDate": "2024-01-01", "endDate": "2024-01-31", "network": "Preprod" } } } } }, "responses": { "200": { "description": "Agent purchase spending analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "agentIdentifier": { "type": "string", "nullable": true }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "totalTransactions": { "type": "number" }, "TotalSpend": { "type": "object", "properties": { "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "Units", "blockchainFees" ] }, "TotalRefunded": { "type": "object", "properties": { "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "Units", "blockchainFees" ] }, "TotalPending": { "type": "object", "properties": { "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "Units", "blockchainFees" ] }, "DailySpend": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "number", "description": "The day of the month" }, "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "day", "month", "year", "Units", "blockchainFees" ] } }, "DailyRefunded": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "number", "description": "The day of the month" }, "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "day", "month", "year", "Units", "blockchainFees" ] } }, "DailyPending": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "number", "description": "The day of the month" }, "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "day", "month", "year", "Units", "blockchainFees" ] } }, "MonthlySpend": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "month", "year", "Units", "blockchainFees" ] } }, "MonthlyRefunded": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "month", "year", "Units", "blockchainFees" ] } }, "MonthlyPending": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "month", "year", "Units", "blockchainFees" ] } } }, "required": [ "agentIdentifier", "periodStart", "periodEnd", "totalTransactions", "TotalSpend", "TotalRefunded", "TotalPending", "DailySpend", "DailyRefunded", "DailyPending", "MonthlySpend", "MonthlyRefunded", "MonthlyPending" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "agentIdentifier": "example_agent_identifier_asset_id", "periodStart": "2024-01-01T00:00:00.000Z", "periodEnd": "2024-01-31T23:59:59.000Z", "totalTransactions": 25, "TotalSpend": { "Units": [ { "unit": "", "amount": 47500000 } ], "blockchainFees": 2500000 }, "TotalRefunded": { "Units": [ { "unit": "", "amount": 2500000 } ], "blockchainFees": 100000 }, "TotalPending": { "Units": [], "blockchainFees": 0 }, "DailySpend": [ { "day": 15, "month": 9, "year": 2024, "Units": [ { "unit": "", "amount": 2100000 } ], "blockchainFees": 100000 } ], "DailyRefunded": [ { "day": 15, "month": 9, "year": 2024, "Units": [ { "unit": "", "amount": 0 } ], "blockchainFees": 0 } ], "DailyPending": [ { "day": 15, "month": 9, "year": 2024, "Units": [ { "unit": "", "amount": 0 } ], "blockchainFees": 0 } ], "MonthlySpend": [ { "month": 9, "year": 2024, "Units": [ { "unit": "", "amount": 2100000 } ], "blockchainFees": 100000 } ], "MonthlyRefunded": [ { "month": 9, "year": 2024, "Units": [], "blockchainFees": 0 } ], "MonthlyPending": [ { "month": 9, "year": 2024, "Units": [], "blockchainFees": 0 } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Agent not found or no spendings data available" }, "500": { "description": "Internal Server Error" } } } }, "/payment/income": { "post": { "description": "Get payment income analytics for Payment Request transactions, over specified time periods.", "summary": "Get payment income analytics. (READ access required)", "tags": [ "payment-income" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentIdentifier": { "type": "string", "nullable": true, "minLength": 57, "maxLength": 250, "description": "The unique identifier of the agent to get payment income for, if not provided, will return income for all agents" }, "startDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" }, { "nullable": true } ], "description": "Start date for income calculation (date format: 2024-01-01). If null, uses earliest available data. If provided, will be converted to the local time zone of the user" }, "endDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" }, { "nullable": true } ], "description": "End date for income calculation (date format: 2024-01-31). If null, uses current date. If provided, will be converted to the local time zone of the user" }, "timeZone": { "type": "string", "default": "Etc/UTC", "description": "The time zone to use for the income calculation. If not provided, will use the UTC time zone. Must be a valid IANA time zone name, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network to query income from" }, "filterPaymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ], "description": "Filter by payment source type. When omitted, income totals default to Web3CardanoV1 for backwards compatibility." }, "paymentRail": { "type": "string", "enum": [ "cardano", "x402" ], "default": "cardano", "description": "cardano: escrow paymentRequest income (default). x402: seller-side settled x402 attempts for the agentIdentifier on this payment node." } }, "required": [ "agentIdentifier", "network" ], "example": { "agentIdentifier": "example_agent_identifier_asset_id", "startDate": "2024-01-01", "endDate": "2024-01-31", "network": "Preprod" } } } } }, "responses": { "200": { "description": "Agent payment income analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "agentIdentifier": { "type": "string", "nullable": true }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "totalTransactions": { "type": "number" }, "TotalIncome": { "type": "object", "properties": { "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "Units", "blockchainFees" ] }, "TotalRefunded": { "type": "object", "properties": { "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "Units", "blockchainFees" ] }, "TotalPending": { "type": "object", "properties": { "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "Units", "blockchainFees" ] }, "DailyIncome": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "number", "description": "The day of the month" }, "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "day", "month", "year", "Units", "blockchainFees" ] } }, "DailyRefunded": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "number", "description": "The day of the month" }, "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "day", "month", "year", "Units", "blockchainFees" ] } }, "DailyPending": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "number", "description": "The day of the month" }, "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "day", "month", "year", "Units", "blockchainFees" ] } }, "MonthlyIncome": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "month", "year", "Units", "blockchainFees" ] } }, "MonthlyRefunded": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "month", "year", "Units", "blockchainFees" ] } }, "MonthlyPending": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "number", "description": "The month" }, "year": { "type": "number", "description": "The year" }, "Units": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "unit", "amount" ], "description": "The amount of the unit in the smallest unit. Meaning if the unit is ADA, the amount is in lovelace (1 ADA = 1000000 lovelace) and its unit is \"\"" } }, "blockchainFees": { "type": "number" } }, "required": [ "month", "year", "Units", "blockchainFees" ] } } }, "required": [ "agentIdentifier", "periodStart", "periodEnd", "totalTransactions", "TotalIncome", "TotalRefunded", "TotalPending", "DailyIncome", "DailyRefunded", "DailyPending", "MonthlyIncome", "MonthlyRefunded", "MonthlyPending" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "agentIdentifier": "example_agent_identifier_asset_id", "periodStart": "2024-01-01T00:00:00.000Z", "periodEnd": "2024-01-31T23:59:59.000Z", "totalTransactions": 25, "TotalIncome": { "Units": [ { "unit": "", "amount": 45000000 } ], "blockchainFees": 2500000 }, "TotalRefunded": { "Units": [ { "unit": "", "amount": 5000000 } ], "blockchainFees": 400000 }, "TotalPending": { "Units": [ { "unit": "", "amount": 2000000 } ], "blockchainFees": 100000 }, "DailyIncome": [ { "day": 10, "month": 1, "year": 2024, "Units": [ { "unit": "", "amount": 2000000 } ], "blockchainFees": 100000 } ], "DailyRefunded": [ { "day": 12, "month": 1, "year": 2024, "Units": [ { "unit": "", "amount": 500000 } ], "blockchainFees": 20000 } ], "DailyPending": [ { "day": 15, "month": 1, "year": 2024, "Units": [ { "unit": "", "amount": 500000 } ], "blockchainFees": 0 } ], "MonthlyIncome": [ { "month": 1, "year": 2024, "Units": [ { "unit": "", "amount": 45000000 } ], "blockchainFees": 2500000 } ], "MonthlyRefunded": [ { "month": 1, "year": 2024, "Units": [ { "unit": "", "amount": 5000000 } ], "blockchainFees": 400000 } ], "MonthlyPending": [ { "month": 1, "year": 2024, "Units": [ { "unit": "", "amount": 2000000 } ], "blockchainFees": 100000 } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Agent not found or no income data available" }, "500": { "description": "Internal Server Error" } } } }, "/webhooks": { "get": { "description": "List webhook endpoints", "summary": "List all webhook endpoints registered by your API key. (pay-authenticated access required)", "tags": [ "webhooks" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Filter by payment source ID" }, "required": false, "description": "Filter by payment source ID", "name": "paymentSourceId", "in": "query" }, { "schema": { "type": "string", "description": "Cursor ID to paginate through the results" }, "required": false, "description": "Cursor ID to paginate through the results", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 50, "default": 10, "description": "Number of webhooks to return" }, "required": false, "description": "Number of webhooks to return", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "List of webhook endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "format": { "type": "string", "enum": [ "EXTENDED", "SLACK", "GOOGLE_CHAT", "DISCORD" ] }, "Events": { "type": "array", "items": { "type": "string", "enum": [ "PURCHASE_ON_CHAIN_STATUS_CHANGED", "PAYMENT_ON_CHAIN_STATUS_CHANGED", "PURCHASE_ON_ERROR", "PAYMENT_ON_ERROR", "WALLET_LOW_BALANCE", "FUND_DISTRIBUTION_SENT", "FUND_DISTRIBUTION_CONFIRMED", "FUND_DISTRIBUTION_FAILED", "X402_PAYMENT_SETTLED", "X402_PAYMENT_FAILED", "X402_WALLET_LOW_BALANCE", "HYDRA_HEAD_LOW_BALANCE" ] } }, "name": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "paymentSourceId": { "type": "string", "nullable": true }, "failureCount": { "type": "number" }, "lastSuccessAt": { "type": "string", "nullable": true, "format": "date-time" }, "disabledAt": { "type": "string", "nullable": true, "format": "date-time" }, "CreatedBy": { "type": "object", "nullable": true, "properties": { "apiKeyId": { "type": "string" }, "apiKeyToken": { "type": "string", "nullable": true } }, "required": [ "apiKeyId", "apiKeyToken" ] } }, "required": [ "id", "url", "format", "Events", "name", "isActive", "createdAt", "updatedAt", "paymentSourceId", "failureCount", "lastSuccessAt", "disabledAt", "CreatedBy" ] } } }, "required": [ "Webhooks" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "Webhooks": [ { "id": "webhook_endpoint_id", "url": "https://your-server.com/webhook", "name": "My Webhook", "Events": [ "PURCHASE_ON_CHAIN_STATUS_CHANGED", "WALLET_LOW_BALANCE" ], "isActive": true, "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "paymentSourceId": null, "failureCount": 0, "lastSuccessAt": "1970-01-20T20:00:36.260Z", "disabledAt": null, "CreatedBy": { "apiKeyId": "api_key_id", "apiKeyToken": "masked_token" } } ] } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } }, "post": { "description": "Register a new webhook endpoint", "summary": "Register a new webhook endpoint to receive event notifications. (pay-authenticated access required)", "tags": [ "webhooks" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Webhook registration details", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri", "description": "The webhook URL to receive notifications. Only public http and https destinations are allowed." }, "authToken": { "type": "string", "nullable": true, "minLength": 10, "maxLength": 200, "description": "Authentication token for extended webhook requests. Required when format is EXTENDED" }, "format": { "type": "string", "enum": [ "EXTENDED", "SLACK", "GOOGLE_CHAT", "DISCORD" ], "default": "EXTENDED", "description": "Webhook delivery format. Defaults to EXTENDED" }, "Events": { "type": "array", "items": { "type": "string", "enum": [ "PURCHASE_ON_CHAIN_STATUS_CHANGED", "PAYMENT_ON_CHAIN_STATUS_CHANGED", "PURCHASE_ON_ERROR", "PAYMENT_ON_ERROR", "WALLET_LOW_BALANCE", "FUND_DISTRIBUTION_SENT", "FUND_DISTRIBUTION_CONFIRMED", "FUND_DISTRIBUTION_FAILED", "X402_PAYMENT_SETTLED", "X402_PAYMENT_FAILED", "X402_WALLET_LOW_BALANCE", "HYDRA_HEAD_LOW_BALANCE" ] }, "minItems": 1, "maxItems": 10, "description": "Array of event types to subscribe to" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name for the webhook" }, "paymentSourceId": { "type": "string", "nullable": true, "description": "Optional: link webhook to specific payment source" } }, "required": [ "url", "Events" ], "example": { "url": "https://your-server.com/webhook", "authToken": "your-webhook-secret-token", "Events": [ "PURCHASE_ON_CHAIN_STATUS_CHANGED", "WALLET_LOW_BALANCE" ], "name": "My Payment Webhook", "paymentSourceId": "payment_source_id_optional" } } } } }, "responses": { "200": { "description": "Webhook endpoint registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "format": { "type": "string", "enum": [ "EXTENDED", "SLACK", "GOOGLE_CHAT", "DISCORD" ] }, "Events": { "type": "array", "items": { "type": "string", "enum": [ "PURCHASE_ON_CHAIN_STATUS_CHANGED", "PAYMENT_ON_CHAIN_STATUS_CHANGED", "PURCHASE_ON_ERROR", "PAYMENT_ON_ERROR", "WALLET_LOW_BALANCE", "FUND_DISTRIBUTION_SENT", "FUND_DISTRIBUTION_CONFIRMED", "FUND_DISTRIBUTION_FAILED", "X402_PAYMENT_SETTLED", "X402_PAYMENT_FAILED", "X402_WALLET_LOW_BALANCE", "HYDRA_HEAD_LOW_BALANCE" ] } }, "name": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "paymentSourceId": { "type": "string", "nullable": true } }, "required": [ "id", "url", "format", "Events", "name", "isActive", "createdAt", "paymentSourceId" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "webhook_endpoint_id", "url": "https://your-server.com/webhook", "name": "My Payment Webhook", "Events": [ "PURCHASE_ON_CHAIN_STATUS_CHANGED", "WALLET_LOW_BALANCE" ], "isActive": true, "createdAt": "1970-01-20T20:00:36.260Z", "paymentSourceId": null } } } } } }, "400": { "description": "Bad Request (invalid webhook URL or configuration)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment source not found" }, "409": { "description": "Webhook URL already registered for this payment source" }, "500": { "description": "Internal Server Error" } } }, "patch": { "description": "Update an existing webhook endpoint", "summary": "Update an existing webhook endpoint. Only the creator or admin can update a webhook. (pay-authenticated access required)", "tags": [ "webhooks" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Webhook update details", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "description": "The ID of the webhook to update" }, "url": { "type": "string", "maxLength": 500, "format": "uri", "description": "The webhook URL to receive notifications. Only public http and https destinations are allowed." }, "authToken": { "type": "string", "nullable": true, "minLength": 10, "maxLength": 200, "description": "Authentication token for extended webhook requests. Omit to keep the stored token; required when changing a webhook to EXTENDED" }, "format": { "type": "string", "enum": [ "EXTENDED", "SLACK", "GOOGLE_CHAT", "DISCORD" ], "description": "Webhook delivery format" }, "Events": { "type": "array", "items": { "type": "string", "enum": [ "PURCHASE_ON_CHAIN_STATUS_CHANGED", "PAYMENT_ON_CHAIN_STATUS_CHANGED", "PURCHASE_ON_ERROR", "PAYMENT_ON_ERROR", "WALLET_LOW_BALANCE", "FUND_DISTRIBUTION_SENT", "FUND_DISTRIBUTION_CONFIRMED", "FUND_DISTRIBUTION_FAILED", "X402_PAYMENT_SETTLED", "X402_PAYMENT_FAILED", "X402_WALLET_LOW_BALANCE", "HYDRA_HEAD_LOW_BALANCE" ] }, "minItems": 1, "maxItems": 10, "description": "Array of event types to subscribe to" }, "name": { "type": "string", "nullable": true, "maxLength": 100, "description": "Human-readable name for the webhook" } }, "required": [ "webhookId", "url", "format", "Events" ], "example": { "webhookId": "webhook_endpoint_id", "url": "https://hooks.slack.com/services/example/path", "format": "SLACK", "Events": [ "PAYMENT_ON_CHAIN_STATUS_CHANGED", "PURCHASE_ON_ERROR" ], "name": "Ops Slack Alerts" } } } } }, "responses": { "200": { "description": "Webhook endpoint updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "format": { "type": "string", "enum": [ "EXTENDED", "SLACK", "GOOGLE_CHAT", "DISCORD" ] }, "Events": { "type": "array", "items": { "type": "string", "enum": [ "PURCHASE_ON_CHAIN_STATUS_CHANGED", "PAYMENT_ON_CHAIN_STATUS_CHANGED", "PURCHASE_ON_ERROR", "PAYMENT_ON_ERROR", "WALLET_LOW_BALANCE", "FUND_DISTRIBUTION_SENT", "FUND_DISTRIBUTION_CONFIRMED", "FUND_DISTRIBUTION_FAILED", "X402_PAYMENT_SETTLED", "X402_PAYMENT_FAILED", "X402_WALLET_LOW_BALANCE", "HYDRA_HEAD_LOW_BALANCE" ] } }, "name": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "paymentSourceId": { "type": "string", "nullable": true } }, "required": [ "id", "url", "format", "Events", "name", "isActive", "createdAt", "updatedAt", "paymentSourceId" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "webhook_endpoint_id", "url": "https://hooks.slack.com/services/example/path", "format": "SLACK", "name": "Ops Slack Alerts", "Events": [ "PAYMENT_ON_CHAIN_STATUS_CHANGED", "PURCHASE_ON_ERROR" ], "isActive": true, "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.360Z", "paymentSourceId": "payment_source_id" } } } } } }, "400": { "description": "Bad Request (invalid webhook URL or configuration)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: only the creator or an admin can update the webhook" }, "404": { "description": "Webhook or payment source not found" }, "409": { "description": "Webhook URL already registered for this payment source" }, "500": { "description": "Internal Server Error" } } }, "delete": { "description": "Delete a webhook endpoint", "summary": "Delete an existing webhook endpoint. Only the creator or admin can delete a webhook. (pay-authenticated access required)", "tags": [ "webhooks" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Webhook deletion request", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "description": "The ID of the webhook to delete" } }, "required": [ "webhookId" ], "example": { "webhookId": "webhook_endpoint_id" } } } } }, "responses": { "200": { "description": "Webhook endpoint deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string", "nullable": true }, "deletedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "name", "deletedAt" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "id": "webhook_endpoint_id", "url": "https://your-server.com/webhook", "name": "My Payment Webhook", "deletedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (only creator or admin can delete)" }, "404": { "description": "Webhook endpoint not found" }, "500": { "description": "Internal Server Error" } } } }, "/webhooks/test": { "post": { "description": "Send a test webhook delivery", "summary": "Send a test webhook delivery using the webhook format currently configured. Only the creator or admin can trigger a test. (pay-authenticated access required)", "tags": [ "webhooks" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Webhook test request", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "description": "The ID of the webhook to send a test delivery to" } }, "required": [ "webhookId" ], "example": { "webhookId": "webhook_endpoint_id" } } } } }, "responses": { "200": { "description": "Webhook test delivery result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "webhookId": { "type": "string" }, "success": { "type": "boolean" }, "responseCode": { "type": "number", "nullable": true, "description": "Always null for test deliveries to avoid exposing upstream response details." }, "errorMessage": { "type": "string", "nullable": true, "description": "Null on success, otherwise a coarse delivery status message." }, "durationMs": { "type": "number", "description": "Always 0 for test deliveries to avoid exposing timing details." } }, "required": [ "webhookId", "success", "responseCode", "errorMessage", "durationMs" ] } }, "required": [ "status", "data" ], "example": { "status": "Success", "data": { "webhookId": "webhook_endpoint_id", "success": true, "responseCode": 200, "errorMessage": null, "durationMs": 184 } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden: only the creator or an admin can test the webhook" }, "404": { "description": "Webhook or payment source not found" }, "500": { "description": "Internal Server Error" } } } }, "/inbox-agents/wallet": { "get": { "description": "Gets the inbox agent metadata.", "summary": "Fetch all inbox agents (and their full metadata) that are registered to a specified wallet. (READ access required)", "tags": [ "inbox-agents" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 250, "description": "The payment key of the wallet to be queried" }, "required": true, "description": "The payment key of the wallet to be queried", "name": "walletVkey", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the inbox agent on" }, "required": true, "description": "The Cardano network used to register the inbox agent on", "name": "network", "in": "query" }, { "schema": { "type": "string", "maxLength": 250, "description": "The smart contract address of the payment source to which the registration belongs" }, "required": false, "description": "The smart contract address of the payment source to which the registration belongs", "name": "smartContractAddress", "in": "query" } ], "responses": { "200": { "description": "Inbox agent metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Assets": { "type": "array", "items": { "$ref": "#/components/schemas/InboxAgentMetadata" }, "description": "List of inbox agent assets registered to this wallet" } }, "required": [ "Assets" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Assets": [ { "policyId": "policy_id", "assetName": "asset_name", "agentIdentifier": "agent_identifier", "Metadata": { "name": "Inbox Agent", "description": "Masumi inbox identity registration", "agentSlug": "inbox-agent", "metadataVersion": 1 } } ] } } } } } } } } }, "/inbox-agents/agent-identifier": { "get": { "description": "Gets the on-chain metadata for a specific inbox agent by its identifier.", "summary": "Fetch the current metadata for a given inbox agentIdentifier. (READ access required)", "tags": [ "inbox-agents" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 57, "maxLength": 250, "description": "Full inbox agent identifier (policy ID + asset name in hex)" }, "required": true, "description": "Full inbox agent identifier (policy ID + asset name in hex)", "name": "agentIdentifier", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network (Preprod or Mainnet)" }, "required": true, "description": "The Cardano network (Preprod or Mainnet)", "name": "network", "in": "query" } ], "responses": { "200": { "description": "Inbox agent metadata retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/InboxAgentIdentifierMetadata" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "policyId": "policy_id", "assetName": "asset_name", "agentIdentifier": "policy_id_asset_name", "Metadata": { "name": "Inbox Agent", "description": "Masumi inbox identity registration", "agentSlug": "inbox-agent", "metadataVersion": 1 } } } } } } }, "400": { "description": "Bad Request (agent identifier is not a valid hex string)" }, "401": { "description": "Unauthorized" }, "404": { "description": "Agent identifier not found or network/policyId combination not supported" }, "422": { "description": "Inbox agent metadata is invalid or malformed" }, "500": { "description": "Internal Server Error" } } } }, "/inbox-agents": { "get": { "description": "Gets the inbox agent metadata.", "summary": "List every inbox agent that is recorded in the Masumi registry inbox. (READ access required)", "tags": [ "inbox-agents" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of inbox registry entries to return" }, "required": false, "description": "The number of inbox registry entries to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "The cursor id to paginate through the results" }, "required": false, "description": "The cursor id to paginate through the results", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the inbox agent on" }, "required": true, "description": "The Cardano network used to register the inbox agent on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted, inbox registry list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted, inbox registry list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" }, { "schema": { "type": "string", "enum": [ "Registered", "Deregistered", "Pending", "Failed" ], "description": "Filter by inbox registration status category" }, "required": false, "description": "Filter by inbox registration status category", "name": "filterStatus", "in": "query" }, { "schema": { "type": "string", "description": "Search query to filter by name, description, agent slug, minting or recipient wallet address, or state" }, "required": false, "description": "Search query to filter by name, description, agent slug, minting or recipient wallet address, or state", "name": "searchQuery", "in": "query" } ], "responses": { "200": { "description": "Inbox agent metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Assets": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryInboxEntry" } } }, "required": [ "Assets" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Assets": [ { "error": null, "id": "inbox_registry_id", "name": "Inbox Agent", "description": "Masumi inbox identity registration", "agentSlug": "inbox-agent", "state": "RegistrationRequested", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "metadataVersion": 1, "sendFundingLovelace": null, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } ] } } } } } } } }, "post": { "description": "Registers an inbox agent to the registry (Please note that while it is put on-chain, the transaction is not yet finalized by the blockchain.)", "summary": "Registers an inbox agent to the registry (+PAY access required)", "tags": [ "inbox-agents" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the inbox agent on" }, "sellingWalletVkey": { "type": "string", "maxLength": 250, "description": "The payment key of a specific wallet used for the registration" }, "recipientWalletAddress": { "type": "string", "maxLength": 250, "pattern": "^(addr1|addr_test1)[0-9a-z]+$", "description": "Optional managed hot wallet address on the same payment source that should receive the minted inbox registry NFT. If omitted, the minting wallet receives it." }, "sendFundingLovelace": { "type": "string", "maxLength": 25, "pattern": "^\\d+$", "description": "Optional lovelace amount to include with the minted inbox registry NFT output. If provided below the minimum NFT funding, the current minimum is still used." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name of the inbox agent" }, "description": { "type": "string", "maxLength": 500, "description": "Optional description of the inbox agent" }, "agentSlug": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Canonical inbox slug. Must already be normalized and not reserved" } }, "required": [ "network", "sellingWalletVkey", "name", "agentSlug" ], "example": { "network": "Preprod", "sellingWalletVkey": "wallet_vkey", "recipientWalletAddress": "recipient_wallet_address", "sendFundingLovelace": "7500000", "name": "Inbox Agent", "description": "Masumi inbox identity registration", "agentSlug": "inbox-agent" } } } } }, "responses": { "200": { "description": "Inbox agent registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/RegistryInboxEntry" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "error": null, "id": "inbox_registry_id", "name": "Inbox Agent", "description": "Masumi inbox identity registration", "agentSlug": "inbox-agent", "state": "RegistrationRequested", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "metadataVersion": 1, "sendFundingLovelace": null, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } } } } } } } }, "delete": { "description": "Permanently deletes an inbox registration record from the database. This action is irreversible and should only be used for registrations in specific failed or completed states.", "summary": "Delete an inbox registration record. (admin access required)", "tags": [ "inbox-agents" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "cuid", "description": "The database ID of the inbox registration record to be deleted." } }, "required": [ "id" ], "example": { "id": "example_id" } } } } }, "responses": { "200": { "description": "Inbox agent registration deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/RegistryInboxEntry" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "error": null, "id": "inbox_registry_id", "name": "Inbox Agent", "description": "Masumi inbox identity registration", "agentSlug": "inbox-agent", "state": "RegistrationRequested", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "metadataVersion": 1, "sendFundingLovelace": null, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } } } } } } } } }, "/inbox-agents/diff": { "get": { "description": "Returns inbox registry entries that changed since the provided timestamp (registrationStateLastChangedAt).", "summary": "Diff inbox registry entries by state-change timestamp (READ access required)", "tags": [ "inbox-agents" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of inbox registry entries to return" }, "required": false, "description": "The number of inbox registry entries to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Pagination cursor (inbox registry request id). Used as tie-breaker when lastUpdate equals a state-change timestamp" }, "required": false, "description": "Pagination cursor (inbox registry request id). Used as tie-breaker when lastUpdate equals a state-change timestamp", "name": "cursorId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" }, { "type": "string", "format": "date-time" } ], "default": "1970-01-01T00:00:00.000Z", "description": "Return inbox registry entries whose registration state changed at/after this ISO timestamp" }, "required": false, "description": "Return inbox registry entries whose registration state changed at/after this ISO timestamp", "name": "lastUpdate", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the inbox agent on" }, "required": true, "description": "The Cardano network used to register the inbox agent on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted, inbox registry diff defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted, inbox registry diff defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" } ], "responses": { "200": { "description": "Inbox agent metadata diff", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Assets": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryInboxEntry" } } }, "required": [ "Assets" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Assets": [ { "error": null, "id": "inbox_registry_id", "name": "Inbox Agent", "description": "Masumi inbox identity registration", "agentSlug": "inbox-agent", "state": "RegistrationRequested", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "metadataVersion": 1, "sendFundingLovelace": null, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } ] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/inbox-agents/deregister": { "post": { "description": "Deregisters an inbox agent from the specified registry (Please note that while the command is put on-chain, the transaction is not yet finalized by the blockchain.)", "summary": "Deregisters an inbox agent from the specified registry. (PAY access required)", "tags": [ "inbox-agents" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentIdentifier": { "type": "string", "minLength": 57, "maxLength": 250, "description": "The identifier of the inbox registration (asset) to be deregistered" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the inbox registration was made on" }, "smartContractAddress": { "type": "string", "maxLength": 250, "description": "The smart contract address of the payment contract to which the inbox registration belongs" } }, "required": [ "agentIdentifier", "network" ], "example": { "agentIdentifier": "agentIdentifier", "network": "Preprod" } } } } }, "responses": { "200": { "description": "Inbox agent deregistration requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/RegistryInboxEntry" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "error": null, "id": "inbox_registry_id", "name": "Inbox Agent", "description": "Masumi inbox identity registration", "agentSlug": "inbox-agent", "state": "RegistrationRequested", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "lastCheckedAt": null, "agentIdentifier": "policy_id_asset_name_policy_id_asset_name_policy_id_asset_name", "metadataVersion": 1, "sendFundingLovelace": null, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "RecipientWallet": null, "CurrentTransaction": null } } } } } } } } }, "/inbox-agents/count": { "get": { "description": "Counts all inbox agents in the registry.", "summary": "Count every inbox agent that is recorded in the Masumi registry inbox. (READ access required)", "tags": [ "inbox-agents" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The Cardano network used to register the inbox agent on" }, "required": true, "description": "The Cardano network used to register the inbox agent on", "name": "network", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The smart contract address of the payment source. When omitted, inbox registry count defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source." }, "required": false, "description": "The smart contract address of the payment source. When omitted, inbox registry count defaults to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.", "name": "filterSmartContractAddress", "in": "query" } ], "responses": { "200": { "description": "Count returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of inbox agents" } }, "required": [ "total" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "total": 42 } } } } } } } } }, "/monitoring": { "get": { "description": "Gets the current status of the blockchain state monitoring service", "summary": "Get monitoring service status. (admin access required)", "tags": [ "monitoring" ], "security": [ { "API-Key": [] } ], "responses": { "200": { "description": "Monitoring service status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/MonitoringStatus" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "MonitoringStatus": { "isMonitoring": true, "Stats": { "trackedEntities": 42, "PurchaseCursor": { "timestamp": "2024-01-01T00:00:00.000Z", "lastId": "cuid_v2_auto_generated" }, "PaymentCursor": { "timestamp": "2024-01-01T00:00:00.000Z", "lastId": "cuid_v2_auto_generated" }, "MemoryUsage": { "heapUsed": "50MB", "heapTotal": "100MB", "external": "10MB" } } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/monitoring/trigger-cycle": { "post": { "description": "Manually triggers a monitoring cycle to check blockchain state", "summary": "Trigger a manual monitoring cycle. (admin access required)", "tags": [ "monitoring" ], "security": [ { "API-Key": [] } ], "responses": { "200": { "description": "Monitoring cycle trigger result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/TriggeredMonitoringCycle" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "message": "Manual monitoring cycle completed successfully", "triggered": true } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/monitoring/start": { "post": { "description": "Starts the blockchain state monitoring service with a specified interval", "summary": "Start the monitoring service. (admin access required)", "tags": [ "monitoring" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Monitoring start configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "intervalMs": { "type": "number", "minimum": 5000, "maximum": 300000, "default": 30000, "description": "Monitoring interval in milliseconds" } }, "example": { "intervalMs": 30000 } } } } }, "responses": { "200": { "description": "Monitoring service start result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/StartedMonitoring" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "message": "Monitoring service started with 30000ms interval", "started": true } } } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Conflict (monitoring service is already running)" }, "500": { "description": "Internal Server Error" } } } }, "/monitoring/stop": { "post": { "description": "Stops the blockchain state monitoring service", "summary": "Stop the monitoring service. (admin access required)", "tags": [ "monitoring" ], "security": [ { "API-Key": [] } ], "responses": { "200": { "description": "Monitoring service stop result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/StoppedMonitoring" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "message": "Monitoring service stopped successfully", "stopped": true } } } } } }, "400": { "description": "Bad Request (monitoring service is not currently running)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/x402/networks/available": { "get": { "description": "Lists the safe network projection needed to create managed wallets. Non-admin results are restricted to the API key CAIP-2 network limit; RPC and facilitator configuration are never returned.", "summary": "List accessible x402 EVM chains. (read access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Filter chains by environment: true for testnet (Preprod), false for mainnet" }, "required": false, "description": "Filter chains by environment: true for testnet (Preprod), false for mainnet", "name": "isTestnet", "in": "query" } ], "responses": { "200": { "description": "Accessible x402 EVM chains", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Networks": { "type": "array", "items": { "$ref": "#/components/schemas/X402AvailableNetwork" } } }, "required": [ "Networks" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Networks": [ { "id": "clx402network0001", "caip2Id": "eip155:8453", "displayName": "Base", "isTestnet": false, "isEnabled": true, "canSettle": true, "defaultAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "defaultAssetDecimals": 6 } ] } } } } } } } } }, "/x402/networks": { "get": { "description": "Lists the EVM chains configured for the standard x402 payment rail.", "summary": "List configured x402 EVM chains. (admin access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Filter chains by environment: true for testnet (Preprod), false for mainnet" }, "required": false, "description": "Filter chains by environment: true for testnet (Preprod), false for mainnet", "name": "isTestnet", "in": "query" } ], "responses": { "200": { "description": "Configured x402 EVM chains", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Networks": { "type": "array", "items": { "$ref": "#/components/schemas/X402Network" } } }, "required": [ "Networks" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Networks": [ { "id": "clx402network0001", "caip2Id": "eip155:8453", "displayName": "Base", "rpcUrl": "https://mainnet.base.org", "isTestnet": false, "isEnabled": true, "defaultAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "defaultAssetDecimals": 6, "facilitatorWalletId": "clmanagedwallet0002", "facilitatorWalletAddress": "0x5555555555555555555555555555555555555555", "facilitatorUrl": null, "createdById": "api_key_id", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" } ] } } } } } } } }, "post": { "description": "Creates or updates an EVM chain configuration, keyed by its CAIP-2 id.", "summary": "Create or update an x402 EVM chain. (admin access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Chain configuration to upsert", "content": { "application/json": { "schema": { "type": "object", "properties": { "caip2Id": { "type": "string", "pattern": "^eip155:\\d+$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "rpcUrl": { "type": "string", "pattern": "^https?:\\/\\/" }, "isTestnet": { "type": "boolean" }, "isEnabled": { "type": "boolean" }, "defaultAsset": { "type": "string", "nullable": true, "pattern": "^0x[a-fA-F0-9]{40}$" }, "defaultAssetDecimals": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 255 }, "facilitatorWalletId": { "type": "string", "nullable": true, "description": "Self-hosted facilitator: owned Selling wallet id (null clears it)" }, "facilitatorUrl": { "type": "string", "nullable": true, "pattern": "^https:\\/\\/", "description": "Remote facilitator: HTTPS endpoint (null clears it)" }, "facilitatorAuth": { "type": "string", "nullable": true, "description": "Authorization header value for the remote facilitator, stored encrypted at rest. Omit to preserve it only when the URL origin is unchanged; changing origin clears it. Send a string to set/rotate it, or null to clear it. Requires a remote facilitator URL (existing or set in the same request)." } }, "required": [ "caip2Id", "displayName", "rpcUrl" ], "example": { "caip2Id": "eip155:8453", "displayName": "Base", "rpcUrl": "https://mainnet.base.org", "isTestnet": false, "isEnabled": true, "defaultAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "defaultAssetDecimals": 6, "facilitatorWalletId": "clmanagedwallet0002" } } } } }, "responses": { "200": { "description": "Chain configuration saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/X402Network" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "clx402network0001", "caip2Id": "eip155:8453", "displayName": "Base", "rpcUrl": "https://mainnet.base.org", "isTestnet": false, "isEnabled": true, "defaultAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "defaultAssetDecimals": 6, "facilitatorWalletId": "clmanagedwallet0002", "facilitatorWalletAddress": "0x5555555555555555555555555555555555555555", "facilitatorUrl": null, "createdById": "api_key_id", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" } } } } } } } } }, "/x402/wallets": { "get": { "description": "Lists managed EVM wallets used to fund x402 payments and settle inbound payments. Results are limited by the key's permitted networks; a key with wallet scoping enabled additionally sees only its assigned and self-created wallets (an unscoped key sees all, the Cardano-parity default). createdById is only returned to admins and for the caller's own wallets.", "summary": "List managed x402 EVM wallets. (read access required; no key material)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of managed wallets to return" }, "required": false, "description": "Number of managed wallets to return", "name": "take", "in": "query" }, { "schema": { "type": "string", "maxLength": 550, "description": "Pagination cursor (provide the id of the last returned wallet)" }, "required": false, "description": "Pagination cursor (provide the id of the last returned wallet)", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Purchasing", "Selling" ], "description": "Filter wallets by direction (Purchasing or Selling)" }, "required": false, "description": "Filter wallets by direction (Purchasing or Selling)", "name": "type", "in": "query" }, { "schema": { "type": "string", "description": "Filter wallets by the bound x402 network id" }, "required": false, "description": "Filter wallets by the bound x402 network id", "name": "networkId", "in": "query" } ], "responses": { "200": { "description": "Managed x402 EVM wallets", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Wallets": { "type": "array", "items": { "$ref": "#/components/schemas/X402Wallet" } } }, "required": [ "Wallets" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Wallets": [ { "id": "clmanagedwallet0001", "networkId": "clx402network0001", "caip2Network": "eip155:8453", "address": "0x1111111111111111111111111111111111111111", "type": "Purchasing", "note": "Agent payout buyer wallet", "createdById": "api_key_id", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" }, { "id": "clmanagedwallet0002", "networkId": "clx402network0001", "caip2Network": "eip155:8453", "address": "0x5555555555555555555555555555555555555555", "type": "Selling", "note": "Base facilitator", "createdById": "api_key_id", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" } ] } } } } } } } }, "post": { "description": "Creates a managed EVM wallet on a network permitted for the API key. When no key is supplied, the generated private key is returned once for backup and stored only in encrypted form.", "summary": "Create a managed x402 EVM wallet. (admin access required; returns the generated private key once)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Optional private key to import", "content": { "application/json": { "schema": { "type": "object", "properties": { "networkId": { "type": "string", "description": "Id of the x402 network (payment source) to bind this wallet to" }, "type": { "type": "string", "enum": [ "Purchasing", "Selling" ], "description": "Purchasing wallets fund outbound payments; Selling wallets settle inbound ones as facilitators" }, "note": { "type": "string", "maxLength": 250, "description": "Optional human-readable label for the wallet" }, "privateKey": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Optional 0x-prefixed 32-byte hex private key. A new key is generated when omitted." } }, "required": [ "networkId", "type" ], "example": { "networkId": "clx402network0001", "type": "Purchasing" } } } } }, "responses": { "200": { "description": "Managed wallet created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/X402WalletCreated" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "clmanagedwallet0001", "networkId": "clx402network0001", "caip2Network": "eip155:8453", "address": "0x1111111111111111111111111111111111111111", "type": "Purchasing", "note": "Agent payout buyer wallet", "createdById": "api_key_id", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z", "privateKey": "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d" } } } } } } } } }, "/x402/wallets/detail": { "get": { "description": "Fetches a single managed EVM wallet by id, including its bound network. Non-admin keys receive 404 outside their permitted networks, and outside their wallet scope when scoping is enabled (an unscoped key can fetch any wallet, the Cardano-parity default). createdById is only returned to admins and for the caller's own wallets.", "summary": "Get a managed x402 EVM wallet by id. (read access required; no key material)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Id of the managed EVM wallet to fetch" }, "required": true, "description": "Id of the managed EVM wallet to fetch", "name": "id", "in": "query" } ], "responses": { "200": { "description": "Managed x402 EVM wallet", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/X402Wallet" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "clmanagedwallet0001", "networkId": "clx402network0001", "caip2Network": "eip155:8453", "address": "0x1111111111111111111111111111111111111111", "type": "Purchasing", "note": "Agent payout buyer wallet", "createdById": "api_key_id", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" } } } } } } } } }, "/x402/wallets/delete": { "post": { "description": "Retires a managed EVM wallet: soft-deletes it and detaches it from any chain it facilitates so a compromised key can no longer sign or settle.", "summary": "Retire a managed x402 EVM wallet. (admin access required; network scoped)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Managed wallet to retire", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the managed EVM wallet to retire" } }, "required": [ "id" ], "example": { "id": "clmanagedwallet0001" } } } } }, "responses": { "200": { "description": "Managed wallet retired", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "clmanagedwallet0001" } } } } } } } } }, "/x402/verify": { "post": { "description": "Verifies a buyer x402 payment payload against a registered resource without settling it, so a resource server can check a payment before serving content.", "summary": "Verify an inbound x402 payment. (pay access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "The registered supported payment source id and the buyer payment payload to verify", "content": { "application/json": { "schema": { "type": "object", "properties": { "supportedPaymentSourceId": { "type": "string" }, "paymentPayload": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "resource": { "type": "object", "properties": { "url": { "type": "string" } } }, "accepted": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "ERC-20 token contract address" }, "amount": { "type": "string", "pattern": "^\\d+$" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "maxTimeoutSeconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 86400 }, "extra": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds" ] }, "payload": { "type": "object", "additionalProperties": { "nullable": true } }, "extensions": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "x402Version", "accepted", "payload" ] }, "paymentRequirements": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "ERC-20 token contract address" }, "amount": { "type": "string", "pattern": "^\\d+$" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "maxTimeoutSeconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 86400 }, "extra": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds" ], "description": "Trusted requirements originally issued by the authenticated resource server. Required for Dynamic registry pricing; Fixed pricing is derived from the registry." } }, "required": [ "supportedPaymentSourceId", "paymentPayload" ], "example": { "supportedPaymentSourceId": "supported_payment_source_id", "paymentPayload": { "x402Version": 1, "resource": { "url": "https://api.example-agent.com/run" }, "accepted": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1000000", "payTo": "0x2222222222222222222222222222222222222222", "maxTimeoutSeconds": 300 }, "payload": { "signature": "0x..." } } } } } } }, "responses": { "200": { "description": "x402 verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "attemptId": { "type": "string" }, "paymentPayloadHash": { "type": "string" }, "paymentIdentifier": { "type": "string", "nullable": true }, "verifyResponse": { "type": "object", "properties": { "isValid": { "type": "boolean" }, "invalidReason": { "type": "string" }, "invalidMessage": { "type": "string" }, "payer": { "type": "string" }, "extensions": { "type": "object", "additionalProperties": { "nullable": true } }, "extra": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "isValid" ] } }, "required": [ "attemptId", "paymentPayloadHash", "paymentIdentifier", "verifyResponse" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "attemptId": "clx402attempt0001", "paymentPayloadHash": "b3f1c2a4d5e6f70819203a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f", "paymentIdentifier": null, "verifyResponse": { "isValid": true, "payer": "0x3333333333333333333333333333333333333333" } } } } } } } } } }, "/x402/settle": { "post": { "description": "Settles a buyer x402 payment payload on-chain for a registered resource and records the settlement. Idempotent per payment payload hash.", "summary": "Settle an inbound x402 payment on-chain. (pay access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "The registered supported payment source id and the buyer payment payload to settle", "content": { "application/json": { "schema": { "type": "object", "properties": { "supportedPaymentSourceId": { "type": "string" }, "paymentPayload": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "resource": { "type": "object", "properties": { "url": { "type": "string" } } }, "accepted": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "ERC-20 token contract address" }, "amount": { "type": "string", "pattern": "^\\d+$" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "maxTimeoutSeconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 86400 }, "extra": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds" ] }, "payload": { "type": "object", "additionalProperties": { "nullable": true } }, "extensions": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "x402Version", "accepted", "payload" ] }, "paymentRequirements": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "ERC-20 token contract address" }, "amount": { "type": "string", "pattern": "^\\d+$" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "maxTimeoutSeconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 86400 }, "extra": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds" ], "description": "Trusted requirements originally issued by the authenticated resource server. Required for Dynamic registry pricing; Fixed pricing is derived from the registry." } }, "required": [ "supportedPaymentSourceId", "paymentPayload" ], "example": { "supportedPaymentSourceId": "supported_payment_source_id", "paymentPayload": { "x402Version": 1, "resource": { "url": "https://api.example-agent.com/run" }, "accepted": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1000000", "payTo": "0x2222222222222222222222222222222222222222", "maxTimeoutSeconds": 300 }, "payload": { "signature": "0x..." } } } } } } }, "responses": { "200": { "description": "x402 settlement result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "attemptId": { "type": "string" }, "paymentPayloadHash": { "type": "string" }, "paymentIdentifier": { "type": "string", "nullable": true }, "replay": { "type": "boolean" }, "settleResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "errorReason": { "type": "string" }, "errorMessage": { "type": "string" }, "payer": { "type": "string" }, "transaction": { "type": "string" }, "network": { "type": "string", "pattern": "^eip155:\\d+$" }, "amount": { "type": "string" }, "extensions": { "type": "object", "additionalProperties": { "nullable": true } }, "extra": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "success", "transaction", "network" ] } }, "required": [ "attemptId", "paymentPayloadHash", "paymentIdentifier", "replay", "settleResponse" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "attemptId": "clx402attempt0001", "paymentPayloadHash": "b3f1c2a4d5e6f70819203a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f", "paymentIdentifier": null, "replay": false, "settleResponse": { "success": true, "payer": "0x3333333333333333333333333333333333333333", "transaction": "0x4242424242424242424242424242424242424242424242424242424242424242", "network": "eip155:8453", "amount": "1000000" } } } } } } } } } }, "/x402/pay": { "post": { "description": "Signs a payment for a forwarded 402 using a managed EVM wallet, debited against the caller's usage credits when the key is usage limited. Returns the X-PAYMENT header for the caller to send with its own retried request; this service never fetches the resource itself.", "summary": "Sign a payment for a forwarded 402. (pay access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "The 402 Payment Required response the buyer received", "content": { "application/json": { "schema": { "type": "object", "properties": { "evmWalletId": { "type": "string", "description": "Managed EVM wallet to sign the payment with" }, "paymentRequired": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "resource": { "type": "object", "properties": { "url": { "type": "string" } } }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+$" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "extra": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "scheme", "network", "asset", "amount", "payTo", "maxTimeoutSeconds" ] }, "minItems": 1, "maxItems": 20, "description": "The payment options advertised by the 402 response" }, "extensions": { "type": "object", "additionalProperties": { "nullable": true } }, "error": { "type": "string" } }, "required": [ "x402Version", "accepts" ], "description": "The 402 Payment Required response the buyer received" }, "preferredNetwork": { "type": "string", "pattern": "^eip155:\\d+$", "description": "Restrict signing to this CAIP-2 network" }, "preferredAsset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Restrict signing to this token asset" }, "paymentIdentifier": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "evmWalletId", "paymentRequired" ], "example": { "evmWalletId": "clmanagedwallet0001", "paymentRequired": { "x402Version": 1, "resource": { "url": "https://api.example-agent.com/run" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1000000", "payTo": "0x2222222222222222222222222222222222222222", "maxTimeoutSeconds": 300 } ] } } } } } }, "responses": { "200": { "description": "Signed x402 payment", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "attemptId": { "type": "string" }, "payer": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "The managed wallet address that signed the payment" }, "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "ERC-20 token contract address" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Signed payment amount in token base units" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "xPaymentHeader": { "type": "string", "description": "Base64 X-PAYMENT header value; the buyer sends this with its own retried request" }, "paymentPayload": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The signed x402 payment payload" }, "paymentPayloadHash": { "type": "string" }, "paymentIdentifier": { "type": "string", "nullable": true } }, "required": [ "attemptId", "payer", "caip2Network", "asset", "amount", "payTo", "xPaymentHeader", "paymentPayload", "paymentPayloadHash", "paymentIdentifier" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "attemptId": "clx402attempt0001", "payer": "0x1111111111111111111111111111111111111111", "caip2Network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1000000", "payTo": "0x2222222222222222222222222222222222222222", "xPaymentHeader": "eyJ4NDAyVmVyc2lvbiI6MSwicGF5bG9hZCI6eyJzaWduYXR1cmUiOiIweC4uLiJ9fQ==", "paymentPayload": { "x402Version": 1, "accepted": { "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1000000", "payTo": "0x2222222222222222222222222222222222222222", "maxTimeoutSeconds": 300 }, "payload": { "signature": "0x..." } }, "paymentPayloadHash": "b3f1c2a4d5e6f70819203a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f", "paymentIdentifier": null } } } } } } } } }, "/x402/payments": { "get": { "description": "Lists x402 payment attempts (inbound verify/settle and outbound payments), newest first, with their settlement result.", "summary": "List x402 payment attempts. (read access required; non-admin keys see only their own)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of payment attempts to return" }, "required": false, "description": "Number of payment attempts to return", "name": "take", "in": "query" }, { "schema": { "type": "string", "maxLength": 550, "description": "Pagination cursor (provide the id of the last returned attempt)" }, "required": false, "description": "Pagination cursor (provide the id of the last returned attempt)", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "enum": [ "PaymentRequired", "Verified", "Settled", "Failed", "Replayed" ], "description": "Filter by payment status" }, "required": false, "description": "Filter by payment status", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "InboundVerify", "InboundSettle", "OutboundPayment" ], "description": "Filter by payment direction" }, "required": false, "description": "Filter by payment direction", "name": "direction", "in": "query" }, { "schema": { "type": "string", "enum": [ "buy", "sell" ], "description": "Coarse side filter: buy = outbound payments, sell = inbound (verify + settle). A direction wins." }, "required": false, "description": "Coarse side filter: buy = outbound payments, sell = inbound (verify + settle). A direction wins.", "name": "side", "in": "query" }, { "schema": { "type": "string", "pattern": "^eip155:\\d+$", "description": "Filter by CAIP-2 chain id" }, "required": false, "description": "Filter by CAIP-2 chain id", "name": "caip2Network", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When true, only returns attempts that require manual reconciliation: a settle that failed, threw, or was interrupted without recording its outcome (a stale Verified marker, or a stale Settled attempt missing its settlement record). Overrides the status filter." }, "required": false, "description": "When true, only returns attempts that require manual reconciliation: a settle that failed, threw, or was interrupted without recording its outcome (a stale Verified marker, or a stale Settled attempt missing its settlement record). Overrides the status filter.", "name": "filterNeedsManualAction", "in": "query" } ], "responses": { "200": { "description": "x402 payment attempts", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "PaymentAttempts": { "type": "array", "items": { "$ref": "#/components/schemas/X402PaymentAttempt" } } }, "required": [ "PaymentAttempts" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "PaymentAttempts": [ { "id": "clx402attempt0001", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z", "direction": "InboundSettle", "status": "Settled", "apiKeyId": "api_key_id", "evmWalletId": "clmanagedwallet0002", "registryRequestId": null, "supportedPaymentSourceId": "supported_payment_source_id", "caip2Network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1000000", "payTo": "0x2222222222222222222222222222222222222222", "payer": "0x3333333333333333333333333333333333333333", "resource": null, "paymentIdentifier": null, "errorReason": null, "errorMessage": null, "facilitator": { "mode": "self_hosted", "address": "0x5555555555555555555555555555555555555555" }, "Settlement": { "id": "clx402settlement0001", "success": true, "txHash": "0x4242424242424242424242424242424242424242424242424242424242424242", "amount": "1000000", "payer": "0x3333333333333333333333333333333333333333", "createdAt": "2026-06-02T12:00:00.000Z" } } ] } } } } } } } } }, "/x402/payments/reconcile": { "post": { "description": "Manually resolves an inbound settle left awaiting reconciliation: a Verified attempt whose settle threw, timed out, or was interrupted becomes eligible once stale; a stale Settled attempt missing its settlement record is also eligible but only accepts \"settled\". The operator confirms on-chain whether funds moved: \"settled\" records the settlement (txHash required), while \"failed\" marks it Failed so a fresh settle can retry.", "summary": "Reconcile an ambiguous x402 settlement. (admin access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "The attempt to reconcile and the operator-confirmed outcome", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "attemptId": { "type": "string", "description": "Id of the InboundSettle attempt awaiting reconciliation" }, "resolution": { "type": "string", "enum": [ "settled" ], "description": "Funds moved on-chain" }, "txHash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "On-chain settlement transaction hash" } }, "required": [ "attemptId", "resolution", "txHash" ], "additionalProperties": false }, { "type": "object", "properties": { "attemptId": { "type": "string", "description": "Id of the InboundSettle attempt awaiting reconciliation" }, "resolution": { "type": "string", "enum": [ "failed" ], "description": "Funds did not move on-chain and the payment is safe to retry" } }, "required": [ "attemptId", "resolution" ], "additionalProperties": false } ], "example": { "attemptId": "clx402attempt0001", "resolution": "settled", "txHash": "0x4242424242424242424242424242424242424242424242424242424242424242" } } } } }, "responses": { "200": { "description": "Reconciliation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "attemptId": { "type": "string" }, "status": { "type": "string", "enum": [ "PaymentRequired", "Verified", "Settled", "Failed", "Replayed" ] } }, "required": [ "attemptId", "status" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "attemptId": "clx402attempt0001", "status": "Settled" } } } } } } } } }, "/x402/settlements": { "get": { "description": "Lists x402 on-chain settlements, newest first.", "summary": "List x402 settlements. (read access required; non-admin keys see only their own)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of settlements to return" }, "required": false, "description": "Number of settlements to return", "name": "take", "in": "query" }, { "schema": { "type": "string", "maxLength": 550, "description": "Pagination cursor (provide the id of the last returned settlement)" }, "required": false, "description": "Pagination cursor (provide the id of the last returned settlement)", "name": "cursorId", "in": "query" }, { "schema": { "type": "string", "pattern": "^eip155:\\d+$", "description": "Filter by CAIP-2 chain id" }, "required": false, "description": "Filter by CAIP-2 chain id", "name": "caip2Network", "in": "query" } ], "responses": { "200": { "description": "x402 settlements", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Settlements": { "type": "array", "items": { "$ref": "#/components/schemas/X402SettlementRecord" } } }, "required": [ "Settlements" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Settlements": [ { "id": "clx402settlement0001", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z", "paymentAttemptId": "clx402attempt0001", "success": true, "txHash": "0x4242424242424242424242424242424242424242424242424242424242424242", "caip2Network": "eip155:8453", "amount": "1000000", "payer": "0x3333333333333333333333333333333333333333" } ] } } } } } } } } }, "/x402/wallets/update": { "post": { "description": "Updates the human-readable note of a managed EVM wallet.", "summary": "Update a managed x402 EVM wallet. (admin access required; network scoped)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Wallet note to set", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the managed EVM wallet to update" }, "note": { "type": "string", "nullable": true, "maxLength": 250, "description": "New label for the wallet; null clears it" } }, "required": [ "id", "note" ], "example": { "id": "clmanagedwallet0001", "note": "Renamed buyer wallet" } } } } }, "responses": { "200": { "description": "Managed wallet updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/X402Wallet" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "clmanagedwallet0001", "networkId": "clx402network0001", "caip2Network": "eip155:8453", "address": "0x1111111111111111111111111111111111111111", "type": "Purchasing", "note": "Agent payout buyer wallet", "createdById": "api_key_id", "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" } } } } } } } } }, "/x402/wallets/balance": { "get": { "description": "Reads on-chain balances (native gas plus the default token) of a managed EVM wallet on the wallet's bound network.", "summary": "Read managed x402 wallet balances. (read access required; owner and network scoped)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Id of the managed EVM wallet to read balances for" }, "required": true, "description": "Id of the managed EVM wallet to read balances for", "name": "id", "in": "query" }, { "schema": { "type": "string", "pattern": "^eip155:\\d+$", "description": "Optional CAIP-2 chain id; must be the wallet's bound network (any other chain returns no balances)" }, "required": false, "description": "Optional CAIP-2 chain id; must be the wallet's bound network (any other chain returns no balances)", "name": "caip2Network", "in": "query" } ], "responses": { "200": { "description": "Managed wallet balances", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "evmWalletId": { "type": "string" }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "Balances": { "type": "array", "items": { "type": "object", "properties": { "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "displayName": { "type": "string" }, "native": { "type": "object", "nullable": true, "properties": { "symbol": { "type": "string" }, "decimals": { "type": "number" }, "amount": { "type": "string", "description": "Native gas balance in wei" } }, "required": [ "symbol", "decimals", "amount" ] }, "asset": { "type": "object", "nullable": true, "properties": { "asset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "symbol": { "type": "string", "nullable": true }, "decimals": { "type": "number" }, "amount": { "type": "string", "description": "Token balance in base units" } }, "required": [ "asset", "symbol", "decimals", "amount" ] }, "error": { "type": "string", "nullable": true, "description": "Set when this chain could not be read" } }, "required": [ "caip2Network", "displayName", "native", "asset", "error" ] } } }, "required": [ "evmWalletId", "address", "Balances" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "evmWalletId": "clmanagedwallet0001", "address": "0x1111111111111111111111111111111111111111", "Balances": [ { "caip2Network": "eip155:8453", "displayName": "Base", "native": { "symbol": "ETH", "decimals": 18, "amount": "12000000000000000" }, "asset": { "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "symbol": "USDC", "decimals": 6, "amount": "4200000" }, "error": null } ] } } } } } } } } }, "/x402/wallets/count": { "get": { "description": "Counts active managed EVM wallets, optionally filtered by direction. Non-admin counts are limited by owner and permitted network.", "summary": "Count managed x402 wallets. (read access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Purchasing", "Selling" ] }, "required": false, "name": "type", "in": "query" } ], "responses": { "200": { "description": "Managed wallet count", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of matching records" } }, "required": [ "total" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "total": 3 } } } } } } } } }, "/x402/low-balance": { "get": { "description": "Lists low-balance rules for managed EVM wallets.", "summary": "List x402 low-balance rules. (admin access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Filter rules to a single wallet" }, "required": false, "description": "Filter rules to a single wallet", "name": "evmWalletId", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Only return rules currently in the Low state" }, "required": false, "description": "Only return rules currently in the Low state", "name": "onlyLow", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Include disabled rules" }, "required": false, "description": "Include disabled rules", "name": "includeDisabled", "in": "query" } ], "responses": { "200": { "description": "x402 low-balance rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Rules": { "type": "array", "items": { "$ref": "#/components/schemas/X402LowBalanceRule" } } }, "required": [ "Rules" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Rules": [ { "id": "clx402lbrule0001", "evmWalletId": "clmanagedwallet0002", "evmWalletAddress": "0x5555555555555555555555555555555555555555", "caip2Network": "eip155:8453", "asset": "native", "thresholdAmount": "10000000000000000", "enabled": true, "status": "Healthy", "lastKnownAmount": "50000000000000000", "lastCheckedAt": "2026-06-02T12:00:00.000Z", "lastAlertedAt": null, "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" } ] } } } } } } } }, "post": { "description": "Creates or updates a low-balance rule for a managed EVM wallet on a chain and asset (\"native\" for gas, otherwise an ERC-20 contract).", "summary": "Set an x402 low-balance rule. (admin access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Low-balance rule to set", "content": { "application/json": { "schema": { "type": "object", "properties": { "evmWalletId": { "type": "string" }, "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "anyOf": [ { "type": "string", "enum": [ "native" ] }, { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } ], "description": "Asset to monitor: \"native\" for the gas token, or an ERC-20 contract address" }, "thresholdAmount": { "type": "string", "pattern": "^\\d+$", "description": "Alert threshold in base units" }, "enabled": { "type": "boolean" } }, "required": [ "evmWalletId", "caip2Network", "asset", "thresholdAmount" ], "example": { "evmWalletId": "clmanagedwallet0002", "caip2Network": "eip155:8453", "asset": "native", "thresholdAmount": "10000000000000000" } } } } }, "responses": { "200": { "description": "Low-balance rule saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/X402LowBalanceRule" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "clx402lbrule0001", "evmWalletId": "clmanagedwallet0002", "evmWalletAddress": "0x5555555555555555555555555555555555555555", "caip2Network": "eip155:8453", "asset": "native", "thresholdAmount": "10000000000000000", "enabled": true, "status": "Healthy", "lastKnownAmount": "50000000000000000", "lastCheckedAt": "2026-06-02T12:00:00.000Z", "lastAlertedAt": null, "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" } } } } } } } }, "patch": { "description": "Updates the threshold or enabled flag of an x402 low-balance rule.", "summary": "Update an x402 low-balance rule. (admin access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Low-balance rule fields to update", "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string" }, "thresholdAmount": { "type": "string", "pattern": "^\\d+$" }, "enabled": { "type": "boolean" } }, "required": [ "ruleId" ], "example": { "ruleId": "clx402lbrule0001", "thresholdAmount": "20000000000000000" } } } } }, "responses": { "200": { "description": "Low-balance rule updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/X402LowBalanceRule" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "clx402lbrule0001", "evmWalletId": "clmanagedwallet0002", "evmWalletAddress": "0x5555555555555555555555555555555555555555", "caip2Network": "eip155:8453", "asset": "native", "thresholdAmount": "10000000000000000", "enabled": true, "status": "Healthy", "lastKnownAmount": "50000000000000000", "lastCheckedAt": "2026-06-02T12:00:00.000Z", "lastAlertedAt": null, "createdAt": "2026-06-02T12:00:00.000Z", "updatedAt": "2026-06-02T12:00:00.000Z" } } } } } } } }, "delete": { "description": "Deletes an x402 low-balance rule.", "summary": "Delete an x402 low-balance rule. (admin access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Low-balance rule to delete", "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string" } }, "required": [ "ruleId" ], "example": { "ruleId": "clx402lbrule0001" } } } } }, "responses": { "200": { "description": "Low-balance rule deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "ruleId": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time" } }, "required": [ "ruleId", "deletedAt" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "ruleId": "clx402lbrule0001", "deletedAt": "2026-06-02T12:00:00.000Z" } } } } } } } } }, "/x402/payments/count": { "get": { "description": "Counts x402 payment attempts, optionally filtered by status, direction and chain.", "summary": "Count x402 payment attempts. (read access required; non-admin keys count only their own)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "PaymentRequired", "Verified", "Settled", "Failed", "Replayed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "InboundVerify", "InboundSettle", "OutboundPayment" ] }, "required": false, "name": "direction", "in": "query" }, { "schema": { "type": "string", "enum": [ "buy", "sell" ], "description": "Coarse side filter: buy = outbound, sell = inbound" }, "required": false, "description": "Coarse side filter: buy = outbound, sell = inbound", "name": "side", "in": "query" }, { "schema": { "type": "string", "pattern": "^eip155:\\d+$" }, "required": false, "name": "caip2Network", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When true, only counts attempts that require manual reconciliation: a settle that failed, threw, or was interrupted without recording its outcome (a stale Verified marker, or a stale Settled attempt missing its settlement record). Overrides the status filter." }, "required": false, "description": "When true, only counts attempts that require manual reconciliation: a settle that failed, threw, or was interrupted without recording its outcome (a stale Verified marker, or a stale Settled attempt missing its settlement record). Overrides the status filter.", "name": "filterNeedsManualAction", "in": "query" } ], "responses": { "200": { "description": "x402 payment attempt count", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of matching records" } }, "required": [ "total" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "total": 3 } } } } } } } } }, "/x402/settlements/count": { "get": { "description": "Counts x402 settlements, optionally filtered by chain and success.", "summary": "Count x402 settlements. (read access required; non-admin keys count only their own)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^eip155:\\d+$" }, "required": false, "name": "caip2Network", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "success", "in": "query" } ], "responses": { "200": { "description": "x402 settlement count", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of matching records" } }, "required": [ "total" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "total": 3 } } } } } } } } }, "/x402/analytics": { "post": { "description": "Aggregates settled inbound (income) and signed outbound (spend) x402 flows over a window, bucketed by day and month and split by chain and asset.", "summary": "x402 income/spend analytics. (admin access required)", "tags": [ "x402" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Analytics window and timezone", "content": { "application/json": { "schema": { "type": "object", "properties": { "startDate": { "type": "string", "nullable": true, "format": "date-time", "description": "Window start (defaults to 30 days ago)" }, "endDate": { "type": "string", "nullable": true, "format": "date-time", "description": "Window end (defaults to now)" }, "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$", "description": "Restrict to a single chain" }, "timeZone": { "type": "string", "description": "IANA timezone for day/month bucketing (default Etc/UTC)" } }, "example": { "timeZone": "Etc/UTC" } } } } }, "responses": { "200": { "description": "x402 analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "incomeCount": { "type": "number", "description": "Number of settled inbound payments" }, "spendCount": { "type": "number", "description": "Number of signed outbound payments" }, "TotalIncome": { "type": "array", "items": { "type": "object", "properties": { "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string" }, "amount": { "type": "string", "description": "Summed amount in base units" } }, "required": [ "caip2Network", "asset", "amount" ] } }, "TotalSpend": { "type": "array", "items": { "type": "object", "properties": { "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string" }, "amount": { "type": "string", "description": "Summed amount in base units" } }, "required": [ "caip2Network", "asset", "amount" ] } }, "Daily": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "number" }, "month": { "type": "number" }, "day": { "type": "number" }, "Income": { "type": "array", "items": { "type": "object", "properties": { "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string" }, "amount": { "type": "string", "description": "Summed amount in base units" } }, "required": [ "caip2Network", "asset", "amount" ] } }, "Spend": { "type": "array", "items": { "type": "object", "properties": { "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string" }, "amount": { "type": "string", "description": "Summed amount in base units" } }, "required": [ "caip2Network", "asset", "amount" ] } } }, "required": [ "year", "month", "day", "Income", "Spend" ] } }, "Monthly": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "number" }, "month": { "type": "number" }, "Income": { "type": "array", "items": { "type": "object", "properties": { "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string" }, "amount": { "type": "string", "description": "Summed amount in base units" } }, "required": [ "caip2Network", "asset", "amount" ] } }, "Spend": { "type": "array", "items": { "type": "object", "properties": { "caip2Network": { "type": "string", "pattern": "^eip155:\\d+$" }, "asset": { "type": "string" }, "amount": { "type": "string", "description": "Summed amount in base units" } }, "required": [ "caip2Network", "asset", "amount" ] } } }, "required": [ "year", "month", "Income", "Spend" ] } } }, "required": [ "periodStart", "periodEnd", "incomeCount", "spendCount", "TotalIncome", "TotalSpend", "Daily", "Monthly" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "periodStart": "2026-05-09T12:00:00.000Z", "periodEnd": "2026-06-02T12:00:00.000Z", "incomeCount": 2, "spendCount": 1, "TotalIncome": [ { "caip2Network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1500000" } ], "TotalSpend": [ { "caip2Network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "200000" } ], "Daily": [ { "year": 2026, "month": 6, "day": 2, "Income": [ { "caip2Network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1500000" } ], "Spend": [ { "caip2Network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "200000" } ] } ], "Monthly": [ { "year": 2026, "month": 6, "Income": [ { "caip2Network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1500000" } ], "Spend": [ { "caip2Network": "eip155:8453", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "200000" } ] } ] } } } } } } } } }, "/fund-wallet": { "get": { "description": "Lists active fund wallets with their distribution configuration and low-balance summary. Filter by payment source id to get every treasury serving that source, or by id for one wallet. An unconfigured source returns an empty FundWallets array.", "summary": "List fund wallets. (admin access required)", "tags": [ "fund-wallet" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Fund wallet id" }, "required": false, "description": "Fund wallet id", "name": "id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Payment source id" }, "required": false, "description": "Payment source id", "name": "paymentSourceId", "in": "query" } ], "responses": { "200": { "description": "Fund wallets", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/FundWalletList" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "FundWallets": [ { "id": "cuid_v2_auto_generated", "walletAddress": "addr_test1...", "walletVkey": "a1b2c3d4e5f6...", "note": "Treasury for preprod V2", "paymentSourceId": "cuid_v2_auto_generated", "lockedAt": null, "LowBalanceSummary": { "isLow": false, "lowRuleCount": 0, "lastCheckedAt": "2024-01-01T00:00:00.000Z" }, "FundDistributionConfig": { "id": "cuid_v2_auto_generated", "enabled": true, "batchWindowMs": 300000 }, "pendingRequestCount": 0 } ] } } } } } }, "400": { "description": "Neither id nor paymentSourceId was provided" }, "401": { "description": "Unauthorized" } } }, "post": { "description": "Creates an enabled fund wallet for a payment source from an existing mnemonic. A source may have several fund wallets; dispatch uses the first one with enough funds. Auto-top-up thresholds and amounts are configured on each target wallet low-balance rule, not on the treasury. Fund the returned address before distribution can run. A mnemonic can back only one active wallet at a time; deleting that wallet frees it for re-registration.", "summary": "Create a fund wallet for a payment source. (admin access required)", "tags": [ "fund-wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Fund wallet mnemonic and batch cadence", "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentSourceId": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Payment source to associate the fund wallet with" }, "walletMnemonic": { "type": "string", "minLength": 1, "maxLength": 1500, "description": "BIP-39 mnemonic phrase for the fund wallet (12-24 words)" }, "batchWindowMs": { "type": "integer", "minimum": 1000, "maximum": 86400000, "default": 300000, "description": "Batch window in milliseconds (default 5 min, max 24 h)" }, "note": { "type": "string", "maxLength": 250, "description": "Optional note for this fund wallet" } }, "required": [ "paymentSourceId", "walletMnemonic" ], "example": { "paymentSourceId": "cuid_v2_auto_generated", "walletMnemonic": "word1 word2 word3 ... word24", "batchWindowMs": 300000, "note": "Treasury for preprod V2" } } } } }, "responses": { "200": { "description": "Fund wallet created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/FundWalletCreated" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated", "walletAddress": "addr_test1...", "walletVkey": "a1b2c3d4e5f6...", "paymentSourceId": "cuid_v2_auto_generated", "FundDistributionConfig": { "id": "cuid_v2_auto_generated", "enabled": true, "batchWindowMs": 300000 } } } } } } }, "400": { "description": "The mnemonic is invalid or the batch window is outside its allowed range" }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment source not found" }, "409": { "description": "The payment source became inactive, or this mnemonic already backs another active wallet" } } }, "patch": { "description": "Updates the distribution configuration of a fund wallet. Set enabled to false to pause automatic distribution without deleting the wallet or its funds.", "summary": "Update fund wallet distribution settings. (admin access required)", "tags": [ "fund-wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Distribution settings to change", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Fund wallet id to update" }, "enabled": { "type": "boolean", "description": "Enable or disable this wallet as a funding source" }, "batchWindowMs": { "type": "integer", "minimum": 1000, "maximum": 86400000, "description": "New batch window in milliseconds (max 24 h)" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated", "enabled": true, "batchWindowMs": 300000 } } } } }, "responses": { "200": { "description": "Fund wallet updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/FundWalletUpdated" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated", "FundDistributionConfig": { "id": "cuid_v2_auto_generated", "enabled": true, "batchWindowMs": 300000 } } } } } } }, "400": { "description": "No changes were requested, or the batch window is outside its allowed range" }, "401": { "description": "Unauthorized" }, "404": { "description": "Fund wallet not found, or it has no distribution config" } } }, "delete": { "description": "Soft-deletes a fund wallet and disables its distribution config. Unclaimed source-level requests continue through another enabled fund wallet, or are cancelled when none remains. Does NOT move funds. A wallet with a broadcast or ambiguous distribution in flight cannot be deleted, even with force=true; wait for the transaction to settle first. Also refuses with 409 while the wallet still holds ADA or native assets, because deletion makes the mnemonic unexportable through the API — withdraw every asset first. Pass force=true only to skip the balance check, accepting that any remaining balance is recoverable only with direct database access.", "summary": "Delete a fund wallet. (admin access required)", "tags": [ "fund-wallet" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Fund wallet to delete", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Fund wallet id to delete" }, "force": { "type": "boolean", "description": "Delete even if the wallet still holds funds, or if the balance cannot be checked. Deletion makes the mnemonic unexportable, so the remaining balance would be recoverable only with direct database access" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated", "force": false } } } } }, "responses": { "200": { "description": "Fund wallet deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/FundWalletDeleted" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Fund wallet not found" }, "409": { "description": "Fund wallet has a distribution in flight, or still holds funds. In-flight transactions must settle; balance-only conflicts can be bypassed with force=true" }, "503": { "description": "Balance could not be checked; retry or pass force=true" } } } }, "/fund-distribution": { "get": { "description": "Lists fund distribution requests, newest first. A request moves Pending -> Submitted -> Confirmed, or to Failed if it could not be sent or never landed on chain. Requests sharing a batchId went out in one transaction. Pagination is cursor-inclusive: the cursor row is returned again, so clients should dedupe by id.", "summary": "List fund distribution requests. (admin access required)", "tags": [ "fund-distribution" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Filter by payment source" }, "required": false, "description": "Filter by payment source", "name": "paymentSourceId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Filter by fund wallet" }, "required": false, "description": "Filter by fund wallet", "name": "fundWalletId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Pending", "Submitted", "Confirmed", "Failed" ], "description": "Filter by status" }, "required": false, "description": "Filter by status", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of results (max 100, default 20)" }, "required": false, "description": "Number of results (max 100, default 20)", "name": "take", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Cursor id for pagination" }, "required": false, "description": "Cursor id for pagination", "name": "cursorId", "in": "query" } ], "responses": { "200": { "description": "Fund distribution requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/FundDistributionList" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "FundDistributions": [ { "id": "cuid_v2_auto_generated", "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z", "fundWalletId": "cuid_v2_auto_generated", "targetWalletId": "cuid_v2_auto_generated", "priority": "Warning", "assetUnit": "lovelace", "amount": "100000000", "status": "Confirmed", "txHash": "a1b2c3d4e5f6...", "error": null, "batchId": "cuid_v2_auto_generated" } ] } } } } } }, "401": { "description": "Unauthorized" } } } }, "/fund-distribution/trigger": { "post": { "description": "Runs a distribution cycle now instead of waiting for the next scheduled one. Returns immediately; the cycle runs in the background, so a 200 means the request was accepted, not that any funds moved. If a cycle is already running this is a no-op and alreadyRunning is true.", "summary": "Trigger a fund distribution cycle. (admin access required)", "tags": [ "fund-distribution" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "No parameters", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "example": {} } } } }, "responses": { "200": { "description": "Distribution cycle triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/FundDistributionTriggered" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "triggered": true, "alreadyRunning": false } } } } } }, "401": { "description": "Unauthorized" } } } }, "/hydra/invite": { "get": { "summary": "List head invites. (admin access required)", "description": "Invites this service has issued or redeemed. An issued invite holds a provisioned node and a peer port until it is redeemed, revoked or expires.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "Issued", "Redeemed", "Started", "Completed", "Expired", "Revoked" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Filter by Cardano network" }, "required": false, "description": "Filter by Cardano network", "name": "network", "in": "query" } ], "responses": { "200": { "description": "Head invites", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "invites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nonce": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "role": { "type": "string", "enum": [ "Issuer", "Redeemer" ] }, "status": { "type": "string", "enum": [ "Issued", "Redeemed", "Started", "Completed", "Expired", "Revoked" ] }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "hydraHostId": { "type": "string" }, "hostNodeId": { "type": "string" }, "issuerWalletAddress": { "type": "string" }, "issuerExchangeUrl": { "type": "string" }, "redeemedAt": { "type": "string", "nullable": true }, "redeemerWalletAddress": { "type": "string", "nullable": true }, "hydraHeadId": { "type": "string", "nullable": true } }, "required": [ "id", "nonce", "network", "role", "status", "createdAt", "expiresAt", "hydraHostId", "hostNodeId", "issuerWalletAddress", "issuerExchangeUrl", "redeemedAt", "redeemerWalletAddress", "hydraHeadId" ] } } }, "required": [ "invites" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "invites": [] } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Mint a head invite. (admin access required)", "description": "Provisions a node on a Hydra Host and signs its full public material with the given wallet, producing a code to hand a counterparty out of band. The node and its peer port are reserved from this moment and cannot be re-pointed, because --peer is fixed at boot — so an invite that is never redeemed must be revoked or left to expire. Redeeming it is what supplies the counterparty's material and lets the node start.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hotWalletId": { "type": "string", "minLength": 1, "description": "Wallet that will identify us on the resulting head" }, "ttlHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the invite may sit before its reservation is released. Defaults to 168 (7 days)." }, "autoFund": { "type": "boolean", "default": true, "description": "Send the node's L1 fuel from the chosen wallet straight away. On unless set false, since a node cannot post Init, Commit, Close or Fanout without it. Opt out only if you fund that key yourself." }, "depositPeriodSeconds": { "type": "integer", "minimum": 300, "maximum": 86400, "description": "How long a deposit must settle before this head will take it — and, since this service always keeps hydra-node 2.4's deposit-activation equal to this same value, also how long before the deposit matures. Both nodes run the value signed here. A top-up is unusable until it matures, absorbable for one period after that, and cannot be recovered until two periods after it matures. Defaults to 600 on preprod and 1200 on mainnet: on mainnet the funds are real, so the wait is what rules out a rollback before they count on L2." }, "contestationPeriodSeconds": { "type": "integer", "minimum": 300, "maximum": 1209600, "description": "How long after closing the head anyone may dispute the final state. Nobody can settle on chain until it elapses, so it is also the wait between closing a head and getting the funds back. Longer is the safe direction: it is the only protection against a counterparty closing on a stale state while your node is down, and settling can take several transactions. Defaults to 5 days on mainnet and 12 hours on preprod." }, "unsyncedPeriodSeconds": { "type": "integer", "minimum": 120, "maximum": 604800, "description": "How long a node may see no new block before it declares itself out of sync and refuses commands, rather than acting on a stale view of the chain. Defaults to 30 minutes on both networks, or half the dispute window where that is tighter. Half the window is the ceiling and may not be exceeded, which is checked against the resolved pair when the invite is minted rather than here, since either field may be defaulted. Raising it buys availability with the time a node needs to contest a close." } }, "required": [ "hotWalletId" ], "example": {} } } } }, "responses": { "200": { "description": "Invite minted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "nonce": { "type": "string" }, "expiresAt": { "type": "string" }, "code": { "type": "string", "description": "The invite itself. Hand this to the counterparty out of band." } }, "required": [ "id", "nonce", "expiresAt", "code" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": {} } } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "No usable Hydra Host, or the host has no admin token" } } }, "delete": { "summary": "Revoke an unredeemed invite. (admin access required)", "description": "Stops the Host honouring the nonce and releases the node and peer port it reserved. Refused once redeemed: by then the reservation is a running node with a peer, and removing that is closing a head.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "example": {} } } } }, "responses": { "200": { "description": "Invite revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "Issued", "Redeemed", "Started", "Completed", "Expired", "Revoked" ] } }, "required": [ "id", "status" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": {} } } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Already redeemed, or not an invite we issued" } } } }, "/hydra/invite/preview": { "post": { "summary": "Inspect an invite without acting on it. (admin access required)", "description": "Decodes an invite code and reports whether its signature matches the wallet it claims to be from. Nothing is provisioned and no counterparty is contacted, so this is safe to call on an invite of unknown provenance. A false `signatureValid` is reported rather than thrown, because an operator looking at a forged invite is better served by being told so.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "An invite code received from a counterparty" } }, "required": [ "code" ], "example": {} } } } }, "responses": { "200": { "description": "Invite contents", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "nonce": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "issuerWalletAddress": { "type": "string" }, "issuerWalletRole": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "advertise": { "type": "string" }, "exchangeUrl": { "type": "string" }, "expiresAt": { "type": "string" }, "contestationPeriodSeconds": { "type": "number" }, "depositPeriodSeconds": { "type": "number" }, "unsyncedPeriodSeconds": { "type": "number" }, "exchangeUsesPrivateNetwork": { "type": "boolean", "nullable": true }, "exchangeNetworkWarning": { "type": "string", "nullable": true }, "signatureValid": { "type": "boolean" }, "alreadyKnown": { "type": "boolean" }, "identity": { "type": "object", "properties": { "policyId": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "assetName": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "unit", "assetName", "name" ] } }, "lookupError": { "type": "string", "nullable": true } }, "required": [ "policyId", "entries", "lookupError" ], "description": "Registry entries held by the issuing wallet, so an operator can recognise who this is" } }, "required": [ "nonce", "network", "issuerWalletAddress", "advertise", "exchangeUrl", "expiresAt", "contestationPeriodSeconds", "depositPeriodSeconds", "unsyncedPeriodSeconds", "exchangeUsesPrivateNetwork", "exchangeNetworkWarning", "signatureValid", "alreadyKnown", "identity" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": {} } } } } }, "400": { "description": "Not a well-formed invite code" }, "401": { "description": "Unauthorized" } } } }, "/hydra/invite/redeem": { "post": { "summary": "Redeem a counterparty invite. (admin access required)", "description": "Verifies the issuer's signature, provisions our own node, sends our material to the issuer's Exchange Plane and records the resulting relation and head. Spends a node and a peer port, and tells the counterparty we are ready, so it is deliberate rather than automatic.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "hotWalletId": { "type": "string", "minLength": 1, "description": "Wallet that will identify us on the resulting head" }, "autoFund": { "type": "boolean", "default": true, "description": "Send the node's L1 fuel from the chosen wallet straight away. On unless set false." }, "allowInsecureExchangeHttp": { "type": "boolean", "default": false, "description": "Explicitly allow redemption over HTTP when a separately secured network protects the exchange" }, "allowPrivateExchangeNetwork": { "type": "boolean", "default": false, "description": "Explicitly allow redemption to private, loopback, link-local, or other special-use IP space" } }, "required": [ "code", "hotWalletId" ], "example": {} } } } }, "responses": { "200": { "description": "Invite redeemed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "hydraHeadId": { "type": "string" }, "counterpartyWalletAddress": { "type": "string" } }, "required": [ "id", "hydraHeadId", "counterpartyWalletAddress" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": {} } } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Wrong network, already redeemed, expired, or our own invite" }, "502": { "description": "The counterparty's exchange plane refused or could not be reached" } } } }, "/hydra/host": { "get": { "summary": "List registered Hydra Hosts. (admin access required)", "description": "Lists the Hydra Host deployments that can run hydra-node processes for this service. Tokens are never returned; `hasAdminToken` reports whether a Host can be provisioned on.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Restrict to one network" }, "required": false, "description": "Restrict to one network", "name": "network", "in": "query" } ], "responses": { "200": { "description": "Registered hosts", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/HydraHost" } } }, "required": [ "hosts" ] } }, "required": [ "status", "data" ], "example": { "status": "success" } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Register a Hydra Host. (admin access required)", "description": "Registers a Hydra Host control plane. The user token grants runtime access to the proxied node API; the optional admin token additionally allows provisioning nodes on this Host. Both are stored encrypted and never returned.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Operator-facing label" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "baseUrl": { "type": "string", "maxLength": 250, "description": "Control-plane URL, e.g. https://hydra1.example.com. HTTPS is recommended." }, "allowInsecureHttp": { "type": "boolean", "default": false, "description": "Explicitly allow bearer tokens over HTTP. Use only on a separately secured network." }, "publicPeerHost": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Hostname the counterparty dials for this head’s peer port. Defaults to the host in baseUrl, which is right unless peers reach the Host by a different name than this service does." }, "userToken": { "type": "string", "minLength": 32, "maxLength": 512, "description": "Runtime token for proxied node API access. Optional: the admin token also satisfies runtime calls, so supply this only to keep a lower-privilege token for day-to-day use." }, "adminToken": { "type": "string", "minLength": 32, "maxLength": 512, "description": "Provision, escrow-ack, reconfigure, delete. Required: without it no head can be opened here." } }, "required": [ "name", "network", "baseUrl", "adminToken" ] } } } }, "responses": { "200": { "description": "Registered host", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/HydraHost" } }, "required": [ "status", "data" ], "example": { "status": "success" } } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "A host for this network and base URL is already registered" } } }, "patch": { "summary": "Update a Hydra Host. (admin access required)", "description": "Updates a Host label, status or tokens. Setting status to Draining keeps existing heads served while accepting no new placements, which matters because a head cannot be moved to another Host.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "Active", "Draining", "Unreachable", "Disabled" ], "description": "Draining keeps serving existing heads (they cannot be moved) but takes no new placements" }, "userToken": { "type": "string", "minLength": 32, "maxLength": 512, "description": "Opaque bearer token issued by the Hydra Host. Stored encrypted and never returned." }, "adminToken": { "type": "string", "nullable": true, "minLength": 32, "maxLength": 512, "description": "Null clears the admin token, disabling provisioning" }, "allowInsecureHttp": { "type": "boolean", "description": "Explicitly allow bearer tokens over this Host HTTP connection" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Updated host", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/HydraHost" } }, "required": [ "status", "data" ], "example": { "status": "success" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra host not found" } } }, "delete": { "summary": "Remove a Hydra Host. (admin access required)", "description": "Removes a Host registration. Refused while the Host still runs nodes, because their heads cannot be relocated.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Removed host", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "status", "data" ], "example": { "status": "success" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra host not found" }, "409": { "description": "Host still runs nodes" } } } }, "/hydra/host/check": { "post": { "summary": "Probe a Hydra Host and record its capabilities. (admin access required)", "description": "Asks the Host which hydra-node version, script catalogue and ledger parameters it runs, and records the answer. A failed probe marks the Host Unreachable, which stops new placements without disturbing the heads already on it.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Host capabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/HydraHost" } }, "required": [ "status", "data" ], "example": { "status": "success" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra host not found" }, "409": { "description": "Host has no admin token" } } } }, "/hydra/wallet-base": { "get": { "summary": "List candidate wallets for Hydra participants. (admin access required)", "description": "Lists the WalletBase entries eligible to back a Hydra participant, optionally filtered by network and payment source.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Filter wallet bases by Cardano network" }, "required": false, "description": "Filter wallet bases by Cardano network", "name": "network", "in": "query" }, { "schema": { "type": "string", "description": "Filter wallet bases by payment source" }, "required": false, "description": "Filter wallet bases by payment source", "name": "paymentSourceId", "in": "query" }, { "schema": { "type": "string", "description": "Filter wallet bases by payment key hash" }, "required": false, "description": "Filter wallet bases by payment key hash", "name": "walletVkey", "in": "query" }, { "schema": { "type": "string", "description": "Cursor ID for pagination" }, "required": false, "description": "Cursor ID for pagination", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of results" }, "required": false, "description": "Number of results", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Candidate wallets", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "paymentSourceId": { "type": "string" }, "type": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "note": { "type": "string", "nullable": true }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string" } }, "required": [ "id", "network", "paymentSourceType" ] } }, "required": [ "id", "createdAt", "updatedAt", "paymentSourceId", "type", "walletVkey", "walletAddress", "note", "PaymentSource" ] } } }, "required": [ "wallets" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "wallets": [] } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Ensure a WalletBase exists for a Hydra counterparty. (admin access required)", "description": "Idempotently records a counterparty wallet (vkey + address) so it can be referenced as a remote Hydra participant.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "hotWalletId": { "type": "string", "minLength": 1, "description": "HotWallet to expose as a public WalletBase option" } }, "required": [ "hotWalletId" ] }, { "type": "object", "properties": { "paymentSourceId": { "type": "string", "minLength": 1, "description": "Payment source this counterparty belongs to" }, "walletAddress": { "type": "string", "minLength": 1, "maxLength": 250, "description": "The counterparty's Cardano address, as they gave it to you" }, "type": { "type": "string", "enum": [ "Buyer", "Seller" ], "description": "Their role in the trade. Defaults to Seller." }, "note": { "type": "string", "maxLength": 250, "description": "Label, so the picker shows more than a bare type" } }, "required": [ "paymentSourceId", "walletAddress" ] } ], "example": {} } } } }, "responses": { "200": { "description": "WalletBase ensured", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "paymentSourceId": { "type": "string" }, "type": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "note": { "type": "string", "nullable": true }, "PaymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string" } }, "required": [ "id", "network", "paymentSourceType" ] } }, "required": [ "id", "createdAt", "updatedAt", "paymentSourceId", "type", "walletVkey", "walletAddress", "note", "PaymentSource" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": {} } } } } }, "401": { "description": "Unauthorized" } } } }, "/hydra/relation": { "get": { "summary": "List Hydra relations. (admin access required)", "description": "Lists the local↔remote wallet pairings that Hydra heads are created from.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Get a single relation by ID" }, "required": false, "description": "Get a single relation by ID", "name": "id", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Filter by Cardano network" }, "required": false, "description": "Filter by Cardano network", "name": "network", "in": "query" }, { "schema": { "type": "string", "description": "Cursor ID for pagination" }, "required": false, "description": "Cursor ID for pagination", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of results" }, "required": false, "description": "Number of results", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Hydra relations", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "relations": { "type": "array", "items": { "$ref": "#/components/schemas/HydraRelationDetail" } } }, "required": [ "relations" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "relations": [] } } } } } }, "401": { "description": "Unauthorized" } } }, "delete": { "summary": "Delete a Hydra relation. (admin access required)", "description": "Deletes a relation that has no active (non-final) head.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of the HydraRelation to delete" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Hydra relation deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated", "deleted": true } } } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Relation still has an active head" } } } }, "/hydra/head": { "get": { "summary": "List or get Hydra heads. (admin access required)", "description": "Lists Hydra heads with lifecycle status, participants and reconciliation state. Filter by id, relationId, status, or isEnabled.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Get a single head by ID" }, "required": false, "description": "Get a single head by ID", "name": "id", "in": "query" }, { "schema": { "type": "string", "description": "Filter by HydraRelation ID" }, "required": false, "description": "Filter by HydraRelation ID", "name": "relationId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Filter by Cardano network" }, "required": false, "description": "Filter by Cardano network", "name": "network", "in": "query" }, { "schema": { "type": "string", "enum": [ "Disconnected", "Connected", "Connecting", "Idle", "Initializing", "Open", "Closed", "FanoutPossible", "Final" ], "description": "Filter by head status" }, "required": false, "description": "Filter by head status", "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Filter by isEnabled" }, "required": false, "description": "Filter by isEnabled", "name": "isEnabled", "in": "query" }, { "schema": { "type": "string", "description": "Cursor ID for pagination" }, "required": false, "description": "Cursor ID for pagination", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of results" }, "required": false, "description": "Number of results", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Hydra heads", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "heads": { "type": "array", "items": { "$ref": "#/components/schemas/HydraHead" } } }, "required": [ "heads" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "heads": [] } } } } } }, "401": { "description": "Unauthorized" } } }, "patch": { "summary": "Enable or disable a Hydra head. (admin access required)", "description": "Enabling re-verifies the head/participants/InitTx on L1 before re-admitting it; disabling quarantines it (drops its InitTx admission).", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of the HydraHead to update" }, "isEnabled": { "type": "boolean", "description": "Whether the head should be enabled" } }, "required": [ "id", "isEnabled" ], "example": { "id": "cuid_v2_auto_generated", "isEnabled": true } } } } }, "responses": { "200": { "description": "Hydra head updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/HydraHead" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "502": { "description": "On-chain verification failed" }, "503": { "description": "Independent L1 evidence not yet available" } } } }, "/hydra/head/init": { "post": { "summary": "Run the Hydra head init lifecycle action. (admin access required)", "description": "Submits the init transaction for the head through the local Hydra node.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "headId": { "type": "string", "minLength": 1, "description": "ID of the HydraHead" } }, "required": [ "headId" ], "example": { "headId": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Head init result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "headId": { "type": "string" }, "status": { "type": "string", "enum": [ "Disconnected", "Connected", "Connecting", "Idle", "Initializing", "Open", "Closed", "FanoutPossible", "Final" ] } }, "required": [ "headId", "status" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "headId": "cuid_v2_auto_generated", "status": "Open" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "409": { "description": "Head is not in a state that permits init" } } } }, "/hydra/head/fanout": { "post": { "summary": "Run the Hydra head fanout lifecycle action. (admin access required)", "description": "Submits the fanout transaction for the head through the local Hydra node.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "headId": { "type": "string", "minLength": 1, "description": "ID of the HydraHead" } }, "required": [ "headId" ], "example": { "headId": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Head fanout result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "headId": { "type": "string" }, "status": { "type": "string", "enum": [ "Disconnected", "Connected", "Connecting", "Idle", "Initializing", "Open", "Closed", "FanoutPossible", "Final" ] } }, "required": [ "headId", "status" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "headId": "cuid_v2_auto_generated", "status": "Open" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "409": { "description": "Head is not in a state that permits fanout" } } } }, "/hydra/head/close": { "post": { "summary": "Run the Hydra head close lifecycle action. (admin access required)", "description": "Submits the close transaction for the head through the local Hydra node. Refused while the head still holds escrows or unconfirmed L2 work unless `acknowledgeActiveEscrows` is set, which accepts that those escrows move to L1 and must be collected there.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "headId": { "type": "string", "minLength": 1, "description": "ID of the HydraHead" }, "acknowledgeActiveEscrows": { "type": "boolean" } }, "required": [ "headId" ], "example": { "headId": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Head close result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "headId": { "type": "string" }, "status": { "type": "string", "enum": [ "Disconnected", "Connected", "Connecting", "Idle", "Initializing", "Open", "Closed", "FanoutPossible", "Final" ] } }, "required": [ "headId", "status" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "headId": "cuid_v2_auto_generated", "status": "Closed" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "409": { "description": "Head is not in a state that permits close, or still holds active escrows" } } } }, "/hydra/head/commit": { "post": { "summary": "Commit the local participant funds into the head. (admin access required)", "description": "Funds the head from the local participant's own L1 wallet UTxOs: builds and validates the node's commit draft, signs it, and submits it to L1.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "headId": { "type": "string", "minLength": 1, "description": "ID of the HydraHead" }, "lovelace": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "How much to put into the head. A dedicated UTxO of exactly this amount is carved on L1 first and only that is committed, so the rest of the wallet — its other ADA, its stablecoins, an agent's registry NFT — stays on L1 and spendable. Costs one L1 confirmation before the deposit is built." } }, "required": [ "headId", "lovelace" ], "example": { "headId": "cuid_v2_auto_generated", "lovelace": "10000000" } } } } }, "responses": { "200": { "description": "Commit result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "headId": { "type": "string" }, "committed": { "type": "boolean" }, "commitTxHash": { "type": "string", "nullable": true } }, "required": [ "headId", "committed", "commitTxHash" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "headId": "cuid_v2_auto_generated", "committed": true, "commitTxHash": null } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "409": { "description": "Head not committable, or the local participant already committed" }, "502": { "description": "The node returned an unsafe or invalid commit draft" } } } }, "/hydra/head/topup": { "post": { "summary": "Top up additional funds into an open head. (admin access required)", "description": "Repeatable incremental commit into an already-Open head, reusing the same draft/validate/sign safety path as the initial commit. Each top-up is its own L1 deposit. With `exactAmount`, that amount is first carved into its own L1 UTxO and only that UTxO is deposited, so everything else in the wallet — an agent's registry NFT included — stays on L1; this is the way to top up from a mixed wallet. Without it, Hydra commits WHOLE UTxOs, so every wallet UTxO matching `assetFilter`/`assetUnit` goes into the head.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "headId": { "type": "string", "description": "The Hydra head to top up" }, "assetFilter": { "type": "string", "enum": [ "all", "ada-only" ], "default": "all", "description": "Which plain wallet UTxOs to commit: all, or ADA-only (ignored when assetUnit is set)" }, "assetUnit": { "type": "string", "pattern": "^[0-9a-fA-F]{56,120}$", "description": "Commit only UTxOs containing this native-asset unit (policyId + assetName hex)" }, "exactAmount": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "Exact top-up amount (base unit) of assetUnit (or lovelace). Pre-splits a dedicated L1 UTxO first, then commits it — adds an L1 confirmation wait." } }, "required": [ "headId" ], "example": { "headId": "cuid_v2_auto_generated", "assetFilter": "ada-only", "exactAmount": "50000000" } } } } }, "responses": { "200": { "description": "Top-up accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "headId": { "type": "string" }, "accepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "headId", "accepted" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "headId": "cuid_v2_auto_generated", "accepted": true } } } } } }, "400": { "description": "Head has no local participant, or `exactAmount` is below the minimum a UTxO can hold" }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "409": { "description": "Head not open, disabled, not yet identified on chain, or its node is still catching up" }, "502": { "description": "No live connection to the head" } } }, "get": { "summary": "List the deposits made into a head. (admin access required)", "description": "Every top-up of this head, newest first, with the status of its L1 deposit. This is where a top-up is followed after POST /hydra/head/topup returns.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The Hydra head whose top-ups to list" }, "required": true, "description": "The Hydra head whose top-ups to list", "name": "headId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Head top-ups", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "topups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "status": { "type": "string", "enum": [ "Preparing", "Pending", "Confirmed", "Failed", "Absorbed", "Recovered" ] }, "depositTxHash": { "type": "string", "nullable": true }, "splitTxHash": { "type": "string", "nullable": true, "description": "The L1 transaction that carved the exact amount, while a top-up is still preparing" }, "committedLovelace": { "type": "string" }, "committedAssets": { "type": "object", "additionalProperties": { "type": "string" } }, "deadline": { "type": "string", "nullable": true }, "usableFrom": { "type": "string", "nullable": true }, "absorbBy": { "type": "string", "nullable": true }, "recoveryRequestedAt": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "status", "depositTxHash", "splitTxHash", "committedLovelace", "committedAssets", "deadline", "usableFrom", "absorbBy", "recoveryRequestedAt" ] } } }, "required": [ "topups" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "topups": [] } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" } } } }, "/hydra/head/withdraw": { "post": { "summary": "Withdraw funds from an open head back to L1. (admin access required)", "description": "Incremental decommit out of an already-Open head, without closing it. Withdraws the local participant's in-head funds to their own L1 address. A decommit removes every output of its transaction from the head, so an exact `lovelace` amount is first split off inside the head — free, and about a second — while omitting it withdraws whole UTxOs. One whole UTxO is held back as collateral so the wallet can still spend escrows inside the head — the smallest it holds worth at least 5 ADA, so the amount withheld is often more than that; `drain` takes it too, for winding a head down. Returns as soon as the request is accepted: the head must then sign a snapshot removing the funds before its node posts the L1 payout.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "headId": { "type": "string", "description": "The Hydra head to withdraw from" }, "lovelace": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "Exact lovelace to withdraw. Omit to withdraw every eligible in-head UTxO whole. An exact amount is split off inside the head first, which costs nothing and takes about a second." }, "assetUnit": { "type": "string", "pattern": "^[0-9a-fA-F]{56,120}$", "description": "Withdraw a native asset instead of ADA: policy id and asset name concatenated. Exactly the amount asked for is split off inside the head first, the same as an ADA withdrawal, so the rest stays where it is." }, "assetAmount": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "How much of assetUnit to withdraw, in that asset's own smallest unit." }, "drain": { "type": "boolean", "default": false, "description": "Also withdraw the UTxO held back as collateral. Without collateral this wallet can no longer spend escrows inside the head, so this is for winding a head down." } }, "required": [ "headId" ], "example": { "headId": "cuid_v2_auto_generated", "lovelace": "10000000", "drain": false } } } } }, "responses": { "200": { "description": "Withdrawal accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "headId": { "type": "string" }, "accepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "headId", "accepted" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "headId": "cuid_v2_auto_generated", "accepted": true } } } } } }, "400": { "description": "Asked for lovelace and a native asset in one request, gave only one half of the asset pair, or the head has no local participant" }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "409": { "description": "Head not open, disabled, not yet identified on chain, or its node is still catching up" }, "502": { "description": "No live connection to the head" } } }, "get": { "summary": "List withdrawals from a head. (admin access required)", "description": "Withdrawals out of this head, newest first. `approvedAt` is the point of no return: the head has signed the removal and the funds have left it, whether or not L1 has them yet. `finalizedAt` is when they became spendable on L1.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The Hydra head whose withdrawals to list" }, "required": true, "description": "The Hydra head whose withdrawals to list", "name": "headId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Withdrawals", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "withdrawals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "status": { "type": "string", "enum": [ "Preparing", "Pending", "Approved", "Finalized", "Failed" ] }, "splitTxId": { "type": "string", "nullable": true }, "decommitTxId": { "type": "string", "nullable": true }, "l1TxId": { "type": "string", "nullable": true }, "requestedLovelace": { "type": "string" }, "requestedAssets": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Native assets this withdrawal set out to remove, as { unit: quantity }." }, "settledLovelace": { "type": "string", "nullable": true }, "settledAssets": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "destinationAddress": { "type": "string" }, "failureReason": { "type": "string", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "finalizedAt": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "status", "splitTxId", "decommitTxId", "l1TxId", "requestedLovelace", "requestedAssets", "settledLovelace", "settledAssets", "destinationAddress", "failureReason", "approvedAt", "finalizedAt" ] } } }, "required": [ "withdrawals" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "withdrawals": [ { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-01T00:00:00.000Z", "updatedAt": "1970-01-01T00:00:00.000Z", "status": "Approved", "splitTxId": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "decommitTxId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "l1TxId": null, "requestedLovelace": "10000000", "requestedAssets": {}, "settledLovelace": null, "settledAssets": null, "destinationAddress": "addr_test1...", "failureReason": null, "approvedAt": "1970-01-01T00:00:00.000Z", "finalizedAt": null } ] } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" } } } }, "/hydra/head/balance": { "get": { "summary": "Read this node's own in-head balance. (admin access required)", "description": "Reports the local participant's own funds currently inside the head (ADA + native tokens), aggregated per asset. Excludes the counterparty. Requires an open/connected head.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "ID of the HydraHead" }, "required": true, "description": "ID of the HydraHead", "name": "headId", "in": "query" } ], "responses": { "200": { "description": "Own in-head balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "hydraHeadId": { "type": "string" }, "address": { "type": "string", "description": "The local participant wallet address whose in-head funds are reported" }, "connected": { "type": "boolean", "description": "True when a live head snapshot was read; false when the head has no active connection" }, "utxoCount": { "type": "number", "description": "Number of in-head UTxOs held by the local address" }, "unbackedLovelace": { "type": "string", "description": "Lovelace the head reports holding whose L1 deposit was recovered to the wallet. hydra-node can keep a deposit in its L2 ledger that was never really absorbed, so the balance above reads high by this much and a close would fail on the overhead it implies." }, "hasUnbackedUtxos": { "type": "boolean", "description": "True when any reported UTxO is unbacked, so the balance is optimistic" }, "balance": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "description": "Empty string for ADA/lovelace; otherwise policyId+assetName hex" }, "quantity": { "type": "string", "description": "Aggregate quantity across the local address in-head UTxOs" } }, "required": [ "unit", "quantity" ] }, "description": "This node's own funds currently inside the head (ADA + native tokens). Excludes the counterparty." } }, "required": [ "hydraHeadId", "address", "connected", "utxoCount", "unbackedLovelace", "hasUnbackedUtxos", "balance" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "hydraHeadId": "cuid_v2_auto_generated", "address": "addr_test1...", "connected": true, "utxoCount": 1, "unbackedLovelace": "0", "hasUnbackedUtxos": false, "balance": [ { "unit": "", "quantity": "10000000" } ] } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head or its local participant wallet not found" } } } }, "/hydra/head/transactions": { "get": { "summary": "List a Hydra head's transactions. (admin access required)", "description": "Every transaction recorded against this head, newest first: L1 for on-chain and L2 for inside the head. The head record itself carries only the Init, Close and Fanout hashes.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The Hydra head whose transactions to list" }, "required": true, "description": "The Hydra head whose transactions to list", "name": "headId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of results" }, "required": false, "description": "Number of results", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Hydra head transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "Ledger", "Deposit", "NodeFunding" ], "description": "Ledger is a payment this head carried. Deposit is money being moved into the head. NodeFunding is ADA sent to the node key that pays this head’s on-chain fees." }, "createdAt": { "type": "string", "format": "date-time" }, "txHash": { "type": "string", "nullable": true, "description": "Null while a transaction is built but not yet broadcast; intendedTxHash names it in the meantime" }, "intendedTxHash": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "FailedViaManualReset", "RolledBack" ] }, "layer": { "type": "string", "enum": [ "L1", "L2" ], "description": "L1 for on-chain, L2 for inside the head" }, "confirmations": { "type": "number", "nullable": true }, "fees": { "type": "string", "nullable": true }, "lovelace": { "type": "string", "nullable": true, "description": "The amount moved, for deposits and node funding. Null for ledger rows." }, "blockTime": { "type": "number", "nullable": true }, "lastCheckedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "kind", "createdAt", "txHash", "intendedTxHash", "status", "layer", "confirmations", "fees", "lovelace", "blockTime", "lastCheckedAt" ] } } }, "required": [ "transactions" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "transactions": [] } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" } } } }, "/hydra/head/topup/recover": { "post": { "summary": "Recover a deposit the head never absorbed. (admin access required)", "description": "A hydra-node only considers a deposit while it is inside its window, so a deposit can confirm on L1 and never reach the head. This asks the node to return it to the wallet it came from; it is refused before the deposit deadline has passed.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topupId": { "type": "string", "minLength": 1, "description": "The deposit to recover" } }, "required": [ "topupId" ], "example": { "topupId": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Recovery request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "depositTxHash": { "type": "string", "nullable": true }, "requested": { "type": "boolean" }, "reason": { "type": "string", "nullable": true } }, "required": [ "depositTxHash", "requested", "reason" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "depositTxHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "requested": true, "reason": null } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "409": { "description": "The deposit is not recoverable yet, or has already been absorbed or recovered" } } } }, "/hydra/head/connection": { "get": { "summary": "Read the state of this service's connection to the head's node. (admin access required)", "description": "Whether a verified live session exists for this head, and what the node last reported. The first thing to read when a head is Open but L2 operations are failing.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "headId", "in": "query" } ], "responses": { "200": { "description": "Head connection", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "headId": { "type": "string" }, "connected": { "type": "boolean" }, "nodeState": { "type": "string" }, "isReady": { "type": "boolean" }, "peerConnected": { "type": "boolean", "nullable": true, "description": "Whether this node is in its Hydra cluster, which for a two-party head means the counterparty's node is up and reachable. Null until the node reports either way. Not a statement about their chain sync." }, "reason": { "type": "string", "nullable": true }, "paramDrift": { "type": "array", "items": { "type": "object", "properties": { "parameter": { "type": "string" }, "head": { "type": "number" }, "chain": { "type": "number" }, "blocksFanout": { "type": "boolean" } }, "required": [ "parameter", "head", "chain", "blocksFanout" ] }, "description": "Empty when the head ledger matches the chain." }, "l2Blocked": { "type": "string", "nullable": true }, "closeWithActiveWork": { "type": "string", "nullable": true, "description": "Null when closing costs nothing beyond the close itself." }, "checkedAt": { "type": "string" } }, "required": [ "headId", "connected", "nodeState", "isReady", "peerConnected", "reason", "paramDrift", "l2Blocked", "closeWithActiveWork", "checkedAt" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "headId": "cuid_v2_auto_generated" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" } } } }, "/hydra/head/errors": { "get": { "summary": "List recorded Hydra head errors. (admin access required)", "description": "Lists the most recent errors recorded for a head (lifecycle command failures, etc.).", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "ID of the HydraHead" }, "required": true, "description": "ID of the HydraHead", "name": "headId", "in": "query" }, { "schema": { "type": "string", "description": "Cursor ID for pagination" }, "required": false, "description": "Cursor ID for pagination", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of results" }, "required": false, "description": "Number of results", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Hydra head errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "errorType": { "type": "string", "enum": [ "CommandFailed", "PostTxOnChainFailed", "TxInvalid", "InvalidInput" ] }, "errorMessage": { "type": "string" }, "headStatus": { "type": "string", "enum": [ "Disconnected", "Connected", "Connecting", "Idle", "Initializing", "Open", "Closed", "FanoutPossible", "Final" ] }, "clientInput": { "type": "string", "nullable": true }, "txHash": { "type": "string", "nullable": true }, "errorAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "createdAt", "errorType", "errorMessage", "headStatus", "clientInput", "txHash", "errorAt" ] } } }, "required": [ "errors" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "errors": [] } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" } } }, "delete": { "summary": "Clear the recorded errors for a head. (admin access required)", "description": "Acknowledges the errors recorded against a head. It changes nothing about the head itself — it only clears what the operator has already read.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "headId": { "type": "string", "minLength": 1, "description": "ID of the HydraHead" } }, "required": [ "headId" ], "example": { "headId": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Cleared head errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "cleared": { "type": "number" } }, "required": [ "cleared" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "cleared": 0 } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" } } } }, "/hydra/participant/local/fund": { "get": { "summary": "Read a node's own balance and funding history. (admin access required)", "description": "A hydra-node posts its head's L1 transactions from a Cardano key of its own, so it needs ADA that is not the head's. This reports what it holds and what has been sent to it.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "query" } ], "responses": { "200": { "description": "Node funding", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "autoFund": { "type": "boolean" }, "automaticFundingLimitLovelace": { "type": "string", "nullable": true, "description": "Lifetime node funding limit in lovelace. Null means unlimited." }, "fundedLovelace": { "type": "string", "description": "Queued or confirmed funding to this address, including historical and manual transfers." }, "remainingFundingLovelace": { "type": "string", "nullable": true }, "address": { "type": "string" }, "balanceLovelace": { "type": "string" }, "isUnderfunded": { "type": "boolean" }, "shortfallLovelace": { "type": "string" }, "checked": { "type": "boolean", "description": "False when the chain could not be consulted — unknown, not zero" }, "node": { "type": "object", "properties": { "state": { "type": "string" }, "isReady": { "type": "boolean" }, "reason": { "type": "string", "nullable": true, "description": "Why it is not ready, when it is not" } }, "required": [ "state", "isReady", "reason" ] } }, "required": [ "autoFund", "automaticFundingLimitLovelace", "fundedLovelace", "remainingFundingLovelace", "address", "balanceLovelace", "isUnderfunded", "shortfallLovelace", "checked", "node" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Local participant not found" } } }, "post": { "summary": "Send ADA to a node's own Cardano key. (admin access required)", "description": "Tops the node up now rather than waiting for the funding cycle. Without this balance the node cannot post an Init, a Close or a Fanout.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Local participant whose node should be funded" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Node funding result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "address": { "type": "string", "description": "The node's own Cardano address, derived from its key hash" }, "balanceLovelace": { "type": "string" }, "transferredLovelace": { "type": "string", "nullable": true, "description": "Null unless this request started a transfer; read `outcome` for why" }, "outcome": { "type": "string", "enum": [ "sent", "sufficient", "in-flight" ], "description": "`sent`: a transfer was started. `sufficient`: the node already holds enough. `in-flight`: an earlier transfer to this node has not confirmed yet, so nothing was sent. The balance below is still the pre-transfer one." } }, "required": [ "address", "balanceLovelace", "transferredLovelace", "outcome" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Local participant not found" } } }, "patch": { "summary": "Set optional automatic node funding limits. (admin access required)", "description": "Automatic funding is unlimited by default. A lifetime limit counts pending and confirmed transfers to the node address, including manual and historical transfers. A refill is skipped if it would exceed the limit. Explicit admin funding remains available.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "autoFund": { "type": "boolean" }, "automaticFundingLimitLovelace": { "type": "string", "nullable": true, "maxLength": 19, "pattern": "^(0|[1-9][0-9]*)$", "description": "Null removes the limit. Zero blocks automatic funding." } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated", "automaticFundingLimitLovelace": null } } } } }, "responses": { "200": { "description": "Automatic funding settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "autoFund": { "type": "boolean" }, "automaticFundingLimitLovelace": { "type": "string", "nullable": true } }, "required": [ "id", "autoFund", "automaticFundingLimitLovelace" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated", "autoFund": true, "automaticFundingLimitLovelace": null } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Local participant not found" } } } }, "/hydra/participant/local/withdraw": { "post": { "summary": "Sweep what a node did not spend back to its wallet. (admin access required)", "description": "Returns the node's remaining ADA once its head is final. Refused while the head is still live or an invite still holds the node, because the node would need those funds.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Local participant whose node should be swept" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Node sweep result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "address": { "type": "string" }, "balanceLovelace": { "type": "string" }, "txHash": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true, "description": "Why nothing was swept, when nothing was" } }, "required": [ "address", "balanceLovelace", "txHash", "reason" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Local participant not found" }, "409": { "description": "The node is still needed, so its funds are kept" } } } }, "/hydra/low-balance": { "get": { "summary": "List Hydra in-head low-balance rules. (admin access required)", "description": "Lists low-balance monitoring rules for local participants' own in-head balances.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Filter rules by local participant" }, "required": false, "description": "Filter rules by local participant", "name": "hydraLocalParticipantId", "in": "query" } ], "responses": { "200": { "description": "Hydra low-balance rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/HydraLowBalanceRule" } } }, "required": [ "rules" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "rules": [] } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Create or update a Hydra in-head low-balance rule. (admin access required)", "description": "Upserts a rule (keyed by participant + asset) that alerts when the participant's own in-head balance for the asset falls below the threshold, and optionally auto-tops-up from its assigned funding wallet.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hydraLocalParticipantId": { "type": "string", "description": "Local participant whose in-head balance to monitor" }, "assetUnit": { "type": "string", "description": "\"lovelace\" or a policyId+assetName hex unit" }, "thresholdAmount": { "type": "string", "pattern": "^\\d+$", "description": "Alert when the in-head balance falls below this" }, "enabled": { "type": "boolean", "default": true }, "topupEnabled": { "type": "boolean", "default": false, "description": "Auto top-up from the assigned funding wallet when low" }, "topupAmount": { "type": "string", "pattern": "^\\d+$", "description": "Exact amount deposited by each auto top-up (carved into its own L1 UTxO first)" } }, "required": [ "hydraLocalParticipantId", "assetUnit", "thresholdAmount" ], "example": { "hydraLocalParticipantId": "cuid_v2_auto_generated", "assetUnit": "lovelace", "thresholdAmount": "50000000", "enabled": true, "topupEnabled": false } } } } }, "responses": { "200": { "description": "Upserted rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/HydraLowBalanceRule" } }, "required": [ "rule" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "rule": { "id": "cuid_v2_auto_generated", "createdAt": "1970-01-01T00:00:00.000Z", "updatedAt": "1970-01-01T00:00:00.000Z", "hydraLocalParticipantId": "cuid_v2_auto_generated", "assetUnit": "lovelace", "thresholdAmount": "50000000", "enabled": true, "topupEnabled": false, "topupAmount": null, "status": "Unknown", "lastKnownAmount": null, "lastCheckedAt": null, "lastAlertedAt": null } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra local participant not found" } } }, "delete": { "summary": "Delete a Hydra in-head low-balance rule. (admin access required)", "description": "Removes a low-balance rule by id.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Low-balance rule id" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Deleted rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra low-balance rule not found" } } } }, "/hydra/participant/local": { "get": { "summary": "List local Hydra participants. (admin access required)", "description": "Lists this server's Hydra participants, optionally filtered by wallet or assignment state.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Get a single participant by ID" }, "required": false, "description": "Get a single participant by ID", "name": "id", "in": "query" }, { "schema": { "type": "string", "description": "Filter by HotWallet ID" }, "required": false, "description": "Filter by HotWallet ID", "name": "walletId", "in": "query" }, { "schema": { "type": "string", "description": "Filter by the connected node running them" }, "required": false, "description": "Filter by the connected node running them", "name": "hydraHostId", "in": "query" }, { "schema": { "type": "string", "description": "Filter to only unassigned participants (no head)" }, "required": false, "description": "Filter to only unassigned participants (no head)", "name": "unassigned", "in": "query" }, { "schema": { "type": "string", "description": "Cursor ID for pagination" }, "required": false, "description": "Cursor ID for pagination", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of results" }, "required": false, "description": "Number of results", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Local participants", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "participants": { "type": "array", "items": { "$ref": "#/components/schemas/HydraLocalParticipant" } } }, "required": [ "participants" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "participants": [] } } } } } }, "401": { "description": "Unauthorized" } } }, "delete": { "summary": "Delete a local Hydra participant. (admin access required)", "description": "Deletes an unassigned local participant, or one whose head is safely finalized/quiesced.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of the local participant to delete" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Local participant deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated", "deleted": true } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Local participant not found" } } } }, "/hydra/participant/local/keys": { "post": { "summary": "Back up a node's signing keys, once. (admin access required)", "description": "Returns the node Hydra and Cardano signing keys a single time, then seals the path: every later call is refused. The keys are generated by the Hydra Host and disclosed by it once at provisioning, so this is the only way to take an off-site copy.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of the local participant whose node keys to back up" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Node signing keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "disclosedAt": { "type": "string" }, "hydraSigningKey": { "type": "string", "description": "Text-envelope cborHex of the node Hydra signing key" }, "cardanoSigningKey": { "type": "string", "nullable": true, "description": "Text-envelope cborHex of the node Cardano signing key. Null for nodes provisioned before it was captured." } }, "required": [ "id", "disclosedAt", "hydraSigningKey", "cardanoSigningKey" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Local participant not found" }, "409": { "description": "The keys have already been handed out once" } } } }, "/hydra/participant/remote": { "get": { "summary": "List remote Hydra participants. (admin access required)", "description": "Lists counterparty participants, optionally filtered by wallet or assignment state.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Get a single participant by ID" }, "required": false, "description": "Get a single participant by ID", "name": "id", "in": "query" }, { "schema": { "type": "string", "description": "Filter by WalletBase ID" }, "required": false, "description": "Filter by WalletBase ID", "name": "walletId", "in": "query" }, { "schema": { "type": "string", "description": "Filter to only unassigned participants (no head)" }, "required": false, "description": "Filter to only unassigned participants (no head)", "name": "unassigned", "in": "query" }, { "schema": { "type": "string", "description": "Cursor ID for pagination" }, "required": false, "description": "Cursor ID for pagination", "name": "cursorId", "in": "query" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of results" }, "required": false, "description": "Number of results", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Remote participants", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "participants": { "type": "array", "items": { "$ref": "#/components/schemas/HydraRemoteParticipant" } } }, "required": [ "participants" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "participants": [] } } } } } }, "401": { "description": "Unauthorized" } } }, "delete": { "summary": "Delete a remote Hydra participant. (admin access required)", "description": "Deletes an unassigned remote participant, or one whose head is safely finalized/quiesced.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of the remote participant to delete" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Remote participant deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated", "deleted": true } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Remote participant not found" } } } }, "/hydra/head/chain-check": { "post": { "summary": "Read a Hydra head state on L1. (admin access required)", "description": "Reads the newest transaction that moved the head's state token, through the payment source's independent L1 observer. Returns whether the head is still open, closed (contestation running), or fanned out. Read-only.", "tags": [ "hydra" ], "security": [ { "API-Key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of the HydraHead to check" } }, "required": [ "id" ], "example": { "id": "cuid_v2_auto_generated" } } } } }, "responses": { "200": { "description": "Head state on chain", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "chainState": { "type": "string", "enum": [ "open", "closed", "gone" ], "description": "Head state after its newest state-token transaction; gone means fanned out" }, "latestTxHash": { "type": "string", "description": "Newest transaction that moved the head state token" } }, "required": [ "chainState", "latestTxHash" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "chainState": "open", "latestTxHash": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Hydra head not found" }, "409": { "description": "Head identifier not observed yet, or no independent L1 observer configured" }, "502": { "description": "The head state could not be read on chain" }, "503": { "description": "Independent L1 evidence not yet available" } } } }, "/rail-readiness": { "get": { "description": "Reports whether each payment rail is actually configured well enough to take payments, so setup UIs do not have to re-derive it from several list endpoints. Each rail returns isReady plus the individual checks behind it, each with a stable id the admin UI maps its setup steps onto. CardanoV2 also returns per-policy/contract PurchaseSources so read-auth consumers can gate outbound purchases against the exact source; these identifiers are public on-chain values. isReady covers blocking checks only: for x402 that means an enabled chain with a usable RPC URL and exactly one facilitator mode configured (a row with both a facilitator wallet and a facilitator URL fails at settle time), while the purchasing wallet is reported but optional. Only configuration presence is exposed — no keys or private wallet data.", "summary": "Get payment rail readiness. (read access required)", "tags": [ "rail-readiness" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Cardano environment to report on. x402 chains are grouped in by their testnet flag" }, "required": true, "description": "Cardano environment to report on. x402 chains are grouped in by their testnet flag", "name": "network", "in": "query" } ], "responses": { "200": { "description": "Rail readiness", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/RailReadiness" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "network": "Preprod", "Rails": [ { "rail": "CardanoV2", "isReady": false, "PurchaseSources": [ { "policyId": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffff", "smartContractAddress": "addr_test1_v2_contract", "isPurchaseReady": true, "Checks": [ { "id": "cardano.payment_source", "label": "Payment source", "isComplete": true, "detail": "Active Web3CardanoV2 source found" }, { "id": "cardano.contract_current", "label": "Current contract", "isComplete": true, "detail": null }, { "id": "cardano.rpc_provider", "label": "Blockfrost API key", "isComplete": true, "detail": null }, { "id": "cardano.admin_signatures", "label": "Admin wallets", "isComplete": true, "detail": null }, { "id": "cardano.purchasing_wallet", "label": "Purchasing wallet", "isComplete": true, "detail": null }, { "id": "cardano.payments_enabled", "label": "Payments enabled", "isComplete": true, "detail": null } ] } ], "Checks": [ { "id": "cardano.payment_source", "label": "Payment source", "isComplete": true, "detail": "Active Web3CardanoV2 source found" }, { "id": "cardano.contract_current", "label": "Current contract", "isComplete": true, "detail": null }, { "id": "cardano.rpc_provider", "label": "Blockfrost API key", "isComplete": true, "detail": null }, { "id": "cardano.admin_signatures", "label": "Admin wallets", "isComplete": true, "detail": null }, { "id": "cardano.selling_wallet", "label": "Selling wallet", "isComplete": false, "detail": "No selling wallet — the source cannot receive payments" }, { "id": "cardano.purchasing_wallet", "label": "Purchasing wallet", "isComplete": true, "detail": null }, { "id": "cardano.payments_enabled", "label": "Payments enabled", "isComplete": true, "detail": null } ] }, { "rail": "X402", "isReady": true, "Checks": [ { "id": "x402.enabled_chain", "label": "Enabled chain", "isComplete": true, "detail": "eip155:84532" }, { "id": "x402.rpc_url", "label": "RPC endpoint", "isComplete": true, "detail": null }, { "id": "x402.facilitator", "label": "Facilitator", "isComplete": true, "detail": "Self-hosted facilitator wallet" }, { "id": "x402.selling_wallet", "label": "Selling wallet", "isComplete": true, "detail": null }, { "id": "x402.purchasing_wallet", "label": "Purchasing wallet", "isComplete": false, "detail": "Optional — needed only to pay other agents" } ] } ] } } } } } }, "401": { "description": "Unauthorized" } } } }, "/tx-sync-quarantine": { "get": { "description": "Lists transactions the chain sync could not apply. The checkpoint has already advanced past these, so anything still pending is chain state the database has NOT caught up with — some request is running on stale information until it is applied.", "summary": "List quarantined sync transactions. (admin access required)", "tags": [ "tx-sync-quarantine" ], "security": [ { "API-Key": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "Filter to a single network" }, "required": false, "description": "Filter to a single network", "name": "network", "in": "query" }, { "schema": { "type": "string", "description": "Filter to a single payment source" }, "required": false, "description": "Filter to a single payment source", "name": "paymentSourceId", "in": "query" }, { "schema": { "type": "string", "enum": [ "Unresolved", "Pending", "NeedsOperator", "Resolved", "All" ], "default": "Unresolved", "description": "Unresolved: every unapplied entry. Pending: awaiting retry. NeedsOperator: retries exhausted or a non-retryable failure. Resolved: successfully applied or independently confirmed rolled back." }, "required": false, "description": "Unresolved: every unapplied entry. Pending: awaiting retry. NeedsOperator: retries exhausted or a non-retryable failure. Resolved: successfully applied or independently confirmed rolled back.", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "How many entries to return" }, "required": false, "description": "How many entries to return", "name": "take", "in": "query" }, { "schema": { "type": "string", "description": "Id of the last entry of the previous page" }, "required": false, "description": "Id of the last entry of the previous page", "name": "cursorId", "in": "query" } ], "responses": { "200": { "description": "Quarantine entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "Quarantine": { "type": "array", "items": { "$ref": "#/components/schemas/TxSyncQuarantineEntry" } } }, "required": [ "Quarantine" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Quarantine": [ { "id": "quarantine_entry_id", "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:05:00.000Z", "txHash": "0000000000000000000000000000000000000000000000000000000000000000", "blockHeight": 10000000, "txIndex": 3, "reason": "ProcessingFailed", "attempts": 4, "lastError": "Could not decode the datum of output 0", "nextRetryAt": "2024-01-01T00:10:00.000Z", "resolvedAt": null, "needsOperator": true, "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "smartContractAddress": "addr_test1..." } } ] } } } } } }, "401": { "description": "Unauthorized" } } }, "delete": { "description": "Permanently removes a quarantine entry. Deleting does NOT apply the transaction — the database stays behind the chain for whatever that transaction would have changed. Intended for entries that are genuinely irrelevant, or ones already repaired by hand.", "summary": "Delete a quarantine entry without applying it. (admin access required)", "tags": [ "tx-sync-quarantine" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Quarantine entry to delete", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The quarantine entry to delete" } }, "required": [ "id" ], "example": { "id": "quarantine_entry_id" } } } } }, "responses": { "200": { "description": "Quarantine entry deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "txHash": { "type": "string" } }, "required": [ "id", "txHash" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "quarantine_entry_id", "txHash": "0000000000000000000000000000000000000000000000000000000000000000" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Quarantine entry not found" }, "409": { "description": "Quarantine entry is currently being processed or changed concurrently" } } } }, "/tx-sync-quarantine/retry": { "post": { "description": "Schedules an immediate retry of a quarantined transaction and clears its operator flag. The retry itself is performed by the reconciler, not inline.", "summary": "Retry a quarantined sync transaction. (admin access required)", "tags": [ "tx-sync-quarantine" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Quarantine entry to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The quarantine entry to retry" } }, "required": [ "id" ], "example": { "id": "quarantine_entry_id" } } } } }, "responses": { "200": { "description": "Quarantine entry re-queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/TxSyncQuarantineEntry" } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "quarantine_entry_id", "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:05:00.000Z", "txHash": "0000000000000000000000000000000000000000000000000000000000000000", "blockHeight": 10000000, "txIndex": 3, "reason": "ProcessingFailed", "attempts": 0, "lastError": "Could not decode the datum of output 0", "nextRetryAt": "2024-01-01T00:10:00.000Z", "resolvedAt": null, "needsOperator": false, "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "smartContractAddress": "addr_test1..." } } } } } } }, "400": { "description": "Quarantine entry is already resolved" }, "401": { "description": "Unauthorized" }, "404": { "description": "Quarantine entry not found" }, "409": { "description": "Quarantine entry is currently being processed or changed concurrently" } } } }, "/request-repair/preview": { "post": { "description": "Dry run of a repair: validates the contract version, confirmation depth, unspent output and immutable request fields, then reports what would change without writing. Pass the returned requestVersion to apply; apply returns 409 if tx-sync changes the request after preview. A failed transaction check returns 400; an inconclusive chain-provider lookup returns 502.", "summary": "Preview a manual request repair. (admin access required)", "tags": [ "request-repair" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Request and transaction to validate", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "Purchase", "Payment" ], "description": "Whether the blockchainIdentifier refers to a purchase or a payment" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the request belongs to" }, "blockchainIdentifier": { "type": "string", "minLength": 1, "description": "The request to repair" }, "txHash": { "type": "string", "minLength": 64, "maxLength": 64, "description": "The transaction that should become the request's CurrentTransaction" } }, "required": [ "kind", "network", "blockchainIdentifier", "txHash" ], "example": { "kind": "Purchase", "network": "Preprod", "blockchainIdentifier": "blockchain_identifier", "txHash": "0000000000000000000000000000000000000000000000000000000000000000" } } } } }, "responses": { "200": { "description": "Repair preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "txHash": { "type": "string" }, "outputIndex": { "type": "number" }, "derivedOnChainState": { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "resultHash": { "type": "string", "nullable": true }, "currentOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ] }, "requestVersion": { "type": "string", "description": "Opaque version to pass to the apply endpoint as requestVersion" } }, "required": [ "txHash", "outputIndex", "derivedOnChainState", "resultHash", "currentOnChainState", "requestVersion" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "txHash": "0000000000000000000000000000000000000000000000000000000000000000", "outputIndex": 0, "derivedOnChainState": "FundsLocked", "resultHash": null, "currentOnChainState": null, "requestVersion": "yF6hS5jPq0yNlTTDyc7mwHt18ZMYbn1RGv5C49VqX74" } } } } } }, "400": { "description": "The transaction does not validate against this request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Request not found for the given blockchainIdentifier and network" }, "502": { "description": "Chain provider could not complete validation; retry later" } } } }, "/request-repair": { "post": { "description": "Repoints a purchase or payment at a specific transaction and syncs its on-chain state. By default the transaction is fetched, checked for confirmation depth and a unique unspent output at this payment source's contract address, then its versioned datum and immutable fields are matched against the request. Pass requestVersion from preview so a concurrent tx-sync update returns 409 instead of being overwritten. Force skips chain checks but still requires requestVersion or expectedRequestUpdatedAt from the operator dialog to prevent a stale forced write.", "summary": "Repair a request by repointing it at a transaction. (admin access required)", "tags": [ "request-repair" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "Request and transaction to repair with", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "Purchase", "Payment" ], "description": "Whether the blockchainIdentifier refers to a purchase or a payment" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ], "description": "The network the request belongs to" }, "blockchainIdentifier": { "type": "string", "minLength": 1, "description": "The request to repair" }, "txHash": { "type": "string", "minLength": 64, "maxLength": 64, "description": "The transaction that should become the request's CurrentTransaction" }, "force": { "type": "boolean", "default": false, "description": "Skip chain validation and write the supplied onChainState verbatim. Only for cases validation cannot cover — a mistake here points the request at the wrong escrow and the automatic refund/withdraw logic will act on it." }, "onChainState": { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ], "description": "Required when force is true. Ignored otherwise — the state is read from the transaction datum." }, "requestVersion": { "type": "string", "minLength": 1, "description": "Opaque request version returned by preview. Required unless force is true; rejects an apply when tx-sync changed the request after preview." }, "expectedRequestUpdatedAt": { "type": "string", "format": "date-time", "description": "Required for force when requestVersion is unavailable. Pass the request updatedAt shown in the operator dialog to reject stale forced writes." } }, "required": [ "kind", "network", "blockchainIdentifier", "txHash" ], "example": { "kind": "Purchase", "network": "Preprod", "blockchainIdentifier": "blockchain_identifier", "txHash": "0000000000000000000000000000000000000000000000000000000000000000", "requestVersion": "yF6hS5jPq0yNlTTDyc7mwHt18ZMYbn1RGv5C49VqX74" } } } } }, "responses": { "200": { "description": "Request repaired", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "requestId": { "type": "string" }, "txHash": { "type": "string" }, "transactionId": { "type": "string" }, "previousOnChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ] }, "newOnChainState": { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "forced": { "type": "boolean", "description": "True when chain validation was skipped" } }, "required": [ "requestId", "txHash", "transactionId", "previousOnChainState", "newOnChainState", "forced" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "requestId": "request_id", "txHash": "0000000000000000000000000000000000000000000000000000000000000000", "transactionId": "transaction_id", "previousOnChainState": null, "newOnChainState": "FundsLocked", "forced": false } } } } } }, "400": { "description": "The transaction does not validate against this request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Request not found for the given blockchainIdentifier and network" }, "409": { "description": "Request changed after preview or after the force dialog loaded" }, "502": { "description": "Chain provider could not complete validation; retry later" } } } }, "/reports/facets": { "get": { "description": "Lists accessible payment sources and their managed buyer and seller wallets. Results include archived records so historical reports can retain their original labels.", "summary": "List transaction report filters. (read access required)", "tags": [ "reports" ], "security": [ { "API-Key": [] } ], "responses": { "200": { "description": "Accessible report filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "fiat": { "type": "object", "properties": { "isConfigured": { "type": "boolean" }, "isDemoKey": { "type": "boolean" }, "historyDays": { "type": "integer", "nullable": true }, "earliestPriceableDate": { "type": "string", "nullable": true, "format": "date-time" }, "currencies": { "type": "array", "items": { "type": "string" } }, "modes": { "type": "array", "items": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ] } }, "attribution": { "type": "string" }, "setupHint": { "type": "string" } }, "required": [ "isConfigured", "isDemoKey", "historyDays", "earliestPriceableDate", "currencies", "modes", "attribution", "setupHint" ] }, "paymentSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "feeRatePermille": { "type": "integer", "minimum": 0, "maximum": 1000 }, "smartContractAddress": { "type": "string" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "network", "paymentSourceType", "feeRatePermille", "smartContractAddress", "deletedAt" ] } }, "managedWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "paymentSourceId": { "type": "string" }, "type": { "type": "string", "enum": [ "Selling", "Purchasing" ] }, "walletAddress": { "type": "string" }, "walletVkey": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "paymentSourceId", "type", "walletAddress", "walletVkey", "collectionAddress", "note", "deletedAt" ] } } }, "required": [ "fiat", "paymentSources", "managedWallets" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "paymentSources": [ { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV2", "feeRatePermille": 0, "smartContractAddress": "addr_test1_contract", "deletedAt": null } ], "managedWallets": [ { "id": "managed_wallet_id", "walletAddress": "addr_test1_wallet", "walletVkey": "wallet_verification_key", "collectionAddress": null, "deletedAt": null, "paymentSourceId": "payment_source_id", "type": "Selling", "note": "Primary seller wallet" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "413": { "description": "The report exceeds its row or file size limit; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "429": { "description": "The API key exceeded its report request rate", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "503": { "description": "All report processing slots are in use", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } } } } }, "/reports/transactions": { "post": { "description": "Returns paginated buyer and seller report rows for one payment source. The cursor preserves the initial asOf boundary and source fee settings, but it does not preserve historical row values. Amounts include raw atomic units and decimal metadata for supported assets.", "summary": "Get transaction report rows. (read access required)", "tags": [ "reports" ], "security": [ { "API-Key": [] } ], "requestBody": { "required": true, "description": "Payment source, wallet, role, state, accounting date, revenue, and pagination filters", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "paymentSourceId": { "type": "string", "minLength": 1, "maxLength": 250 }, "managedWalletIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "externalAddresses": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "minItems": 1, "maxItems": 2, "default": [ "Buyer", "Seller" ] }, "states": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, { "type": "string", "enum": [ "Pending" ] } ] }, "maxItems": 11 }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" }, "dateBasis": { "type": "string", "enum": [ "CreatedAt", "FundsLockedAt", "RevenueRecognizedAt" ], "default": "RevenueRecognizedAt" }, "revenueMode": { "type": "string", "enum": [ "Billable", "CashReceived", "RequestedGross" ], "default": "Billable" }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100, "default": "Etc/UTC" }, "fiat": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "usd", "eur", "gbp", "jpy", "chf", "aed" ] }, "mode": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ], "default": "PeriodAverage" }, "suppliedRates": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 200 }, "rate": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)(?:\\.\\d+)?$" }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "unit", "rate" ] }, "maxItems": 100 } }, "required": [ "currency" ] } }, "required": [ "paymentSourceId", "from", "to" ] }, { "type": "object", "properties": { "cursor": { "type": "string", "maxLength": 4000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } } ], "example": { "paymentSourceId": "payment_source_id", "managedWalletIds": [ "managed_wallet_id" ], "externalAddresses": [ "addr_test1_external" ], "roles": [ "Buyer", "Seller" ], "states": [ "FundsLocked", "Withdrawn" ], "from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00.000Z", "dateBasis": "RevenueRecognizedAt", "revenueMode": "Billable", "timeZone": "Etc/UTC", "limit": 50 } } } } }, "responses": { "200": { "description": "Transaction report rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "requestType": { "type": "string", "enum": [ "PaymentRequest", "PurchaseRequest" ] }, "createdAt": { "type": "string", "format": "date-time" }, "blockchainIdentifier": { "type": "string" }, "agentIdentifier": { "type": "string", "nullable": true }, "agentName": { "type": "string", "nullable": true }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ] }, "metadata": { "type": "string", "nullable": true }, "managedWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletAddress": { "type": "string" }, "walletVkey": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "walletAddress", "walletVkey", "collectionAddress", "deletedAt" ] }, "counterpartyAddress": { "type": "string", "nullable": true }, "buyerReturnAddress": { "type": "string", "nullable": true }, "sellerReturnAddress": { "type": "string", "nullable": true }, "timestamps": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time" }, "fundsLockedAt": { "type": "string", "nullable": true, "format": "date-time" }, "sellerRevenueRecognizedAt": { "type": "string", "nullable": true, "format": "date-time" }, "buyerGrossSpendAt": { "type": "string", "nullable": true, "format": "date-time" }, "buyerReturnedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "createdAt", "fundsLockedAt", "sellerRevenueRecognizedAt", "buyerGrossSpendAt", "buyerReturnedAt" ] }, "settlement": { "type": "object", "properties": { "resultSubmittedTxHash": { "type": "string", "nullable": true }, "settlementTxHash": { "type": "string", "nullable": true }, "settlementTxType": { "type": "string", "nullable": true, "enum": [ "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn", null ] } }, "required": [ "resultSubmittedTxHash", "settlementTxHash", "settlementTxType" ] }, "seller": { "type": "object", "nullable": true, "properties": { "grossRevenue": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "protocolFee": { "type": "object", "properties": { "configuredRatePermille": { "type": "integer", "minimum": 0, "maximum": 1000 }, "appliedRatePermille": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 1000 }, "amounts": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "provenance": { "type": "string", "enum": [ "calculated", "projected", "exact_zero", "not_applicable", "insufficient_data" ] }, "basis": { "type": "string", "nullable": true, "enum": [ "stored_requested_plus_collateral", "contract_version", null ] }, "completeness": { "type": "string", "enum": [ "exact", "reconstructed", "not_applicable", "insufficient_data" ] } }, "required": [ "configuredRatePermille", "appliedRatePermille", "amounts", "provenance", "basis", "completeness" ] }, "cardanoFees": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "cardanoFeeTiming": { "type": "string", "enum": [ "stored_cumulative", "accounting_allocation" ] }, "netRevenue": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "payoutCompleteness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "grossRevenue", "protocolFee", "cardanoFees", "cardanoFeeTiming", "netRevenue", "payoutCompleteness" ] }, "buyer": { "type": "object", "nullable": true, "properties": { "grossSpend": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "returnedFunds": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "cardanoFees": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "cardanoFeeTiming": { "type": "string", "enum": [ "stored_cumulative", "accounting_allocation" ] }, "netSpend": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "payoutCompleteness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "grossSpend", "returnedFunds", "cardanoFees", "cardanoFeeTiming", "netSpend", "payoutCompleteness" ] }, "actorCardanoFeeAllocation": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "accounting_allocation", "lifetime_cohort" ] }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] }, "attachedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "strategy", "completeness", "attachedAt" ] }, "feeAllocationScope": { "type": "string", "enum": [ "single_request", "shared_or_unknown" ] }, "feeComponentScope": { "type": "string", "enum": [ "complete", "partial" ] }, "cardanoFeeReconciliation": { "type": "object", "properties": { "buyerCardanoFees": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] }, "sellerCardanoFees": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] }, "adminCardanoFees": { "type": "object", "nullable": true, "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] }, "totalCardanoFees": { "type": "object", "nullable": true, "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] }, "completeness": { "type": "string", "enum": [ "complete", "partial", "inconsistent" ] }, "isAggregationOwner": { "type": "boolean" } }, "required": [ "buyerCardanoFees", "sellerCardanoFees", "adminCardanoFees", "totalCardanoFees", "completeness", "isAggregationOwner" ] } }, "required": [ "id", "role", "requestType", "createdAt", "blockchainIdentifier", "agentIdentifier", "agentName", "onChainState", "metadata", "managedWallet", "counterpartyAddress", "buyerReturnAddress", "sellerReturnAddress", "timestamps", "settlement", "seller", "buyer", "actorCardanoFeeAllocation", "feeAllocationScope", "feeComponentScope", "cardanoFeeReconciliation" ] } }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "nextCursor", "hasMore" ] }, "metadata": { "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "asOf": { "type": "string", "format": "date-time" }, "paymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "feeRatePermille": { "type": "integer", "minimum": 0, "maximum": 1000 }, "smartContractAddress": { "type": "string" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "network", "paymentSourceType", "feeRatePermille", "smartContractAddress", "deletedAt" ] }, "filters": { "type": "object", "properties": { "paymentSourceId": { "type": "string" }, "managedWalletIds": { "type": "array", "nullable": true, "items": { "type": "string" } }, "externalAddresses": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "Buyer", "Seller" ] } }, "states": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, { "type": "string", "enum": [ "Pending" ] } ] } }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "dateBasis": { "type": "string", "enum": [ "CreatedAt", "FundsLockedAt", "RevenueRecognizedAt" ] }, "revenueMode": { "type": "string", "enum": [ "Billable", "CashReceived", "RequestedGross" ] }, "timeZone": { "type": "string" } }, "required": [ "paymentSourceId", "managedWalletIds", "externalAddresses", "roles", "states", "from", "to", "dateBasis", "revenueMode", "timeZone" ] }, "fiat": { "type": "object", "nullable": true, "properties": { "currency": { "type": "string" }, "mode": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ] }, "provider": { "type": "string", "enum": [ "coingecko", "supplied" ] }, "attribution": { "type": "string", "nullable": true }, "isDemoKey": { "type": "boolean" }, "demoHistoryDays": { "type": "integer", "nullable": true }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] }, "unpricedUnits": { "type": "array", "items": { "type": "string" } }, "rates": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "coinId": { "type": "string", "nullable": true }, "rate": { "type": "string" }, "source": { "type": "string", "enum": [ "supplied", "coingecko" ] }, "provenance": { "type": "object", "nullable": true, "properties": { "cadence": { "type": "string", "enum": [ "daily" ] }, "sampleCount": { "type": "integer", "minimum": 0 }, "requestedDayCount": { "type": "integer", "minimum": 0 }, "firstSampleAt": { "type": "string" }, "lastSampleAt": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "cadence", "sampleCount", "requestedDayCount", "firstSampleAt", "lastSampleAt", "currency" ] } }, "required": [ "unit", "coinId", "rate", "source", "provenance" ] } }, "fetchedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "currency", "mode", "provider", "attribution", "isDemoKey", "demoHistoryDays", "completeness", "unpricedUnits", "rates", "fetchedAt" ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "rowId": { "type": "string", "nullable": true } }, "required": [ "code", "message", "rowId" ] } } }, "required": [ "generatedAt", "asOf", "paymentSource", "filters", "fiat", "warnings" ] } }, "required": [ "rows", "page", "metadata" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "rows": [], "page": { "nextCursor": null, "hasMore": false }, "metadata": { "generatedAt": "2026-02-01T00:00:01.000Z", "asOf": "2026-02-01T00:00:00.000Z", "paymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV2", "feeRatePermille": 0, "smartContractAddress": "addr_test1_contract", "deletedAt": null }, "filters": { "paymentSourceId": "payment_source_id", "managedWalletIds": [ "managed_wallet_id" ], "externalAddresses": [ "addr_test1_external" ], "roles": [ "Buyer", "Seller" ], "states": [ "FundsLocked", "Withdrawn" ], "from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00.000Z", "dateBasis": "RevenueRecognizedAt", "revenueMode": "Billable", "timeZone": "Etc/UTC" }, "warnings": [] } } } } } } }, "400": { "description": "The report filters or cursor are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "404": { "description": "The payment source or requested managed wallet is not accessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "413": { "description": "The report exceeds its row or file size limit; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "429": { "description": "The API key exceeded its report request rate", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "502": { "description": "The exchange rate provider could not price a requested asset", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "503": { "description": "All report processing slots are in use", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "504": { "description": "The report calculation timed out; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } } } } }, "/reports/summary": { "post": { "description": "Returns totals, per-wallet and role totals, and time buckets from one database snapshot. The service calculates applicable V1 protocol fees from the payment source rate. Applicable V2 protocol fees are exact zero.", "summary": "Get transaction report totals and history. (read access required)", "tags": [ "reports" ], "security": [ { "API-Key": [] } ], "requestBody": { "required": true, "description": "Report filters and history bucket size", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "paymentSourceId": { "type": "string", "minLength": 1, "maxLength": 250 }, "managedWalletIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "externalAddresses": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "minItems": 1, "maxItems": 2, "default": [ "Buyer", "Seller" ] }, "states": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, { "type": "string", "enum": [ "Pending" ] } ] }, "maxItems": 11 }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" }, "dateBasis": { "type": "string", "enum": [ "CreatedAt", "FundsLockedAt", "RevenueRecognizedAt" ], "default": "RevenueRecognizedAt" }, "revenueMode": { "type": "string", "enum": [ "Billable", "CashReceived", "RequestedGross" ], "default": "Billable" }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100, "default": "Etc/UTC" }, "fiat": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "usd", "eur", "gbp", "jpy", "chf", "aed" ] }, "mode": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ], "default": "PeriodAverage" }, "suppliedRates": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 200 }, "rate": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)(?:\\.\\d+)?$" }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "unit", "rate" ] }, "maxItems": 100 } }, "required": [ "currency" ] } }, "required": [ "paymentSourceId", "from", "to" ] }, { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "Auto", "Day", "Week", "Month" ], "default": "Auto" } } } ], "example": { "paymentSourceId": "payment_source_id", "managedWalletIds": [ "managed_wallet_id" ], "externalAddresses": [ "addr_test1_external" ], "roles": [ "Buyer", "Seller" ], "states": [ "FundsLocked", "Withdrawn" ], "from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00.000Z", "dateBasis": "RevenueRecognizedAt", "revenueMode": "Billable", "timeZone": "Etc/UTC", "bucket": "Auto" } } } } }, "responses": { "200": { "description": "Transaction report totals and history", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "transactionCount": { "type": "integer", "minimum": 0 }, "transactionCountCompleteness": { "type": "string", "enum": [ "complete", "partial" ] }, "sellerGrossRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerPendingRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "protocolFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "actorCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerNetRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerGrossSpend": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "returnedFunds": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerNetSpend": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "adminCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "totalCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] } }, "required": [ "transactionCount", "transactionCountCompleteness", "sellerGrossRevenue", "sellerPendingRevenue", "protocolFees", "sellerCardanoFees", "actorCardanoFees", "sellerNetRevenue", "buyerGrossSpend", "returnedFunds", "buyerCardanoFees", "buyerNetSpend", "adminCardanoFees", "totalCardanoFees" ] }, "wallets": { "type": "array", "items": { "type": "object", "properties": { "managedWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletAddress": { "type": "string" }, "walletVkey": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "walletAddress", "walletVkey", "collectionAddress", "deletedAt" ] }, "role": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "metrics": { "type": "object", "properties": { "transactionCount": { "type": "integer", "minimum": 0 }, "transactionCountCompleteness": { "type": "string", "enum": [ "complete", "partial" ] }, "sellerGrossRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerPendingRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "protocolFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "actorCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerNetRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerGrossSpend": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "returnedFunds": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerNetSpend": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "adminCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "totalCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] } }, "required": [ "transactionCount", "transactionCountCompleteness", "sellerGrossRevenue", "sellerPendingRevenue", "protocolFees", "sellerCardanoFees", "actorCardanoFees", "sellerNetRevenue", "buyerGrossSpend", "returnedFunds", "buyerCardanoFees", "buyerNetSpend", "adminCardanoFees", "totalCardanoFees" ] } }, "required": [ "managedWallet", "role", "metrics" ] } }, "history": { "type": "array", "items": { "type": "object", "properties": { "bucketStart": { "type": "string", "format": "date-time" }, "bucketEnd": { "type": "string", "format": "date-time" }, "metrics": { "type": "object", "properties": { "transactionCount": { "type": "integer", "minimum": 0 }, "transactionCountCompleteness": { "type": "string", "enum": [ "complete", "partial" ] }, "sellerGrossRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerPendingRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "protocolFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "actorCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "sellerNetRevenue": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerGrossSpend": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "returnedFunds": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "buyerNetSpend": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "adminCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] }, "totalCardanoFees": { "type": "object", "properties": { "amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "rawAmount": { "type": "string", "pattern": "^-?\\d+$" }, "decimalAmount": { "type": "string", "nullable": true }, "decimals": { "type": "integer", "nullable": true, "minimum": 0 }, "symbol": { "type": "string", "nullable": true } }, "required": [ "unit", "rawAmount", "decimalAmount", "decimals", "symbol" ] } }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "amounts", "completeness" ] } }, "required": [ "transactionCount", "transactionCountCompleteness", "sellerGrossRevenue", "sellerPendingRevenue", "protocolFees", "sellerCardanoFees", "actorCardanoFees", "sellerNetRevenue", "buyerGrossSpend", "returnedFunds", "buyerCardanoFees", "buyerNetSpend", "adminCardanoFees", "totalCardanoFees" ] } }, "required": [ "bucketStart", "bucketEnd", "metrics" ] } }, "bucket": { "type": "string", "enum": [ "Day", "Week", "Month" ] }, "metadata": { "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "asOf": { "type": "string", "format": "date-time" }, "paymentSource": { "type": "object", "properties": { "id": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "paymentSourceType": { "type": "string", "enum": [ "Web3CardanoV1", "Web3CardanoV2" ] }, "feeRatePermille": { "type": "integer", "minimum": 0, "maximum": 1000 }, "smartContractAddress": { "type": "string" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "id", "network", "paymentSourceType", "feeRatePermille", "smartContractAddress", "deletedAt" ] }, "filters": { "type": "object", "properties": { "paymentSourceId": { "type": "string" }, "managedWalletIds": { "type": "array", "nullable": true, "items": { "type": "string" } }, "externalAddresses": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "Buyer", "Seller" ] } }, "states": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, { "type": "string", "enum": [ "Pending" ] } ] } }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "dateBasis": { "type": "string", "enum": [ "CreatedAt", "FundsLockedAt", "RevenueRecognizedAt" ] }, "revenueMode": { "type": "string", "enum": [ "Billable", "CashReceived", "RequestedGross" ] }, "timeZone": { "type": "string" } }, "required": [ "paymentSourceId", "managedWalletIds", "externalAddresses", "roles", "states", "from", "to", "dateBasis", "revenueMode", "timeZone" ] }, "fiat": { "type": "object", "nullable": true, "properties": { "currency": { "type": "string" }, "mode": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ] }, "provider": { "type": "string", "enum": [ "coingecko", "supplied" ] }, "attribution": { "type": "string", "nullable": true }, "isDemoKey": { "type": "boolean" }, "demoHistoryDays": { "type": "integer", "nullable": true }, "completeness": { "type": "string", "enum": [ "complete", "partial" ] }, "unpricedUnits": { "type": "array", "items": { "type": "string" } }, "rates": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "unit": { "type": "string" }, "coinId": { "type": "string", "nullable": true }, "rate": { "type": "string" }, "source": { "type": "string", "enum": [ "supplied", "coingecko" ] }, "provenance": { "type": "object", "nullable": true, "properties": { "cadence": { "type": "string", "enum": [ "daily" ] }, "sampleCount": { "type": "integer", "minimum": 0 }, "requestedDayCount": { "type": "integer", "minimum": 0 }, "firstSampleAt": { "type": "string" }, "lastSampleAt": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "cadence", "sampleCount", "requestedDayCount", "firstSampleAt", "lastSampleAt", "currency" ] } }, "required": [ "unit", "coinId", "rate", "source", "provenance" ] } }, "fetchedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "currency", "mode", "provider", "attribution", "isDemoKey", "demoHistoryDays", "completeness", "unpricedUnits", "rates", "fetchedAt" ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "rowId": { "type": "string", "nullable": true } }, "required": [ "code", "message", "rowId" ] } } }, "required": [ "generatedAt", "asOf", "paymentSource", "filters", "fiat", "warnings" ] } }, "required": [ "totals", "wallets", "history", "bucket", "metadata" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "totals": { "transactionCount": 0, "transactionCountCompleteness": "complete", "sellerGrossRevenue": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "protocolFees": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "sellerCardanoFees": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "actorCardanoFees": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "sellerNetRevenue": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "buyerGrossSpend": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "returnedFunds": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "buyerCardanoFees": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "buyerNetSpend": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "adminCardanoFees": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" }, "totalCardanoFees": { "amounts": [ { "unit": "lovelace", "rawAmount": "0", "decimalAmount": "0.000000", "decimals": 6, "symbol": "ADA" } ], "completeness": "complete" } }, "wallets": [], "history": [], "bucket": "Day", "metadata": { "generatedAt": "2026-02-01T00:00:01.000Z", "asOf": "2026-02-01T00:00:00.000Z", "paymentSource": { "id": "payment_source_id", "network": "Preprod", "paymentSourceType": "Web3CardanoV2", "feeRatePermille": 0, "smartContractAddress": "addr_test1_contract", "deletedAt": null }, "filters": { "paymentSourceId": "payment_source_id", "managedWalletIds": [ "managed_wallet_id" ], "externalAddresses": [ "addr_test1_external" ], "roles": [ "Buyer", "Seller" ], "states": [ "FundsLocked", "Withdrawn" ], "from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00.000Z", "dateBasis": "RevenueRecognizedAt", "revenueMode": "Billable", "timeZone": "Etc/UTC" }, "warnings": [] } } } } } } }, "400": { "description": "The report filters or cursor are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "404": { "description": "The payment source or requested managed wallet is not accessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "413": { "description": "The report exceeds its row or file size limit; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "429": { "description": "The API key exceeded its report request rate", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "502": { "description": "The exchange rate provider could not price a requested asset", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "503": { "description": "All report processing slots are in use", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "504": { "description": "The report calculation timed out; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } } } } }, "/reports/transactions.csv": { "post": { "description": "Downloads one row per buyer or seller transaction as CSV.", "summary": "Transaction rows CSV. (read access required)", "tags": [ "reports" ], "security": [ { "API-Key": [] } ], "requestBody": { "required": true, "description": "Report filters and history bucket size", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "paymentSourceId": { "type": "string", "minLength": 1, "maxLength": 250 }, "managedWalletIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "externalAddresses": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "minItems": 1, "maxItems": 2, "default": [ "Buyer", "Seller" ] }, "states": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, { "type": "string", "enum": [ "Pending" ] } ] }, "maxItems": 11 }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" }, "dateBasis": { "type": "string", "enum": [ "CreatedAt", "FundsLockedAt", "RevenueRecognizedAt" ], "default": "RevenueRecognizedAt" }, "revenueMode": { "type": "string", "enum": [ "Billable", "CashReceived", "RequestedGross" ], "default": "Billable" }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100, "default": "Etc/UTC" }, "fiat": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "usd", "eur", "gbp", "jpy", "chf", "aed" ] }, "mode": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ], "default": "PeriodAverage" }, "suppliedRates": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 200 }, "rate": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)(?:\\.\\d+)?$" }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "unit", "rate" ] }, "maxItems": 100 } }, "required": [ "currency" ] } }, "required": [ "paymentSourceId", "from", "to" ] }, { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "Auto", "Day", "Week", "Month" ], "default": "Auto" } } } ], "example": { "paymentSourceId": "payment_source_id", "managedWalletIds": [ "managed_wallet_id" ], "externalAddresses": [ "addr_test1_external" ], "roles": [ "Buyer", "Seller" ], "states": [ "FundsLocked", "Withdrawn" ], "from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00.000Z", "dateBasis": "RevenueRecognizedAt", "revenueMode": "Billable", "timeZone": "Etc/UTC", "bucket": "Auto" } } } } }, "responses": { "200": { "description": "Transaction rows CSV", "headers": { "Content-Disposition": { "description": "Attachment filename, including an RFC 5987 UTF-8 filename", "schema": { "type": "string" } }, "Content-Length": { "description": "Artifact size in bytes", "schema": { "type": "integer", "format": "int64", "minimum": 0 } } }, "content": { "text/csv; charset=utf-8": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The report filters or cursor are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "404": { "description": "The payment source or requested managed wallet is not accessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "413": { "description": "The report exceeds its row or file size limit; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "429": { "description": "The API key exceeded its report request rate", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "502": { "description": "The exchange rate provider could not price a requested asset", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "503": { "description": "All report processing slots are in use", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "504": { "description": "The report calculation timed out; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } } } } }, "/reports/wallet-summary.csv": { "post": { "description": "Downloads totals grouped by managed wallet and buyer or seller role as CSV.", "summary": "Wallet and role totals CSV. (read access required)", "tags": [ "reports" ], "security": [ { "API-Key": [] } ], "requestBody": { "required": true, "description": "Report filters and history bucket size", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "paymentSourceId": { "type": "string", "minLength": 1, "maxLength": 250 }, "managedWalletIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "externalAddresses": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "minItems": 1, "maxItems": 2, "default": [ "Buyer", "Seller" ] }, "states": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, { "type": "string", "enum": [ "Pending" ] } ] }, "maxItems": 11 }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" }, "dateBasis": { "type": "string", "enum": [ "CreatedAt", "FundsLockedAt", "RevenueRecognizedAt" ], "default": "RevenueRecognizedAt" }, "revenueMode": { "type": "string", "enum": [ "Billable", "CashReceived", "RequestedGross" ], "default": "Billable" }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100, "default": "Etc/UTC" }, "fiat": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "usd", "eur", "gbp", "jpy", "chf", "aed" ] }, "mode": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ], "default": "PeriodAverage" }, "suppliedRates": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 200 }, "rate": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)(?:\\.\\d+)?$" }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "unit", "rate" ] }, "maxItems": 100 } }, "required": [ "currency" ] } }, "required": [ "paymentSourceId", "from", "to" ] }, { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "Auto", "Day", "Week", "Month" ], "default": "Auto" } } } ], "example": { "paymentSourceId": "payment_source_id", "managedWalletIds": [ "managed_wallet_id" ], "externalAddresses": [ "addr_test1_external" ], "roles": [ "Buyer", "Seller" ], "states": [ "FundsLocked", "Withdrawn" ], "from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00.000Z", "dateBasis": "RevenueRecognizedAt", "revenueMode": "Billable", "timeZone": "Etc/UTC", "bucket": "Auto" } } } } }, "responses": { "200": { "description": "Wallet and role totals CSV", "headers": { "Content-Disposition": { "description": "Attachment filename, including an RFC 5987 UTF-8 filename", "schema": { "type": "string" } }, "Content-Length": { "description": "Artifact size in bytes", "schema": { "type": "integer", "format": "int64", "minimum": 0 } } }, "content": { "text/csv; charset=utf-8": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The report filters or cursor are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "404": { "description": "The payment source or requested managed wallet is not accessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "413": { "description": "The report exceeds its row or file size limit; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "429": { "description": "The API key exceeded its report request rate", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "502": { "description": "The exchange rate provider could not price a requested asset", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "503": { "description": "All report processing slots are in use", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "504": { "description": "The report calculation timed out; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } } } } }, "/reports/totals.csv": { "post": { "description": "Downloads payment source totals as CSV.", "summary": "Payment source totals CSV. (read access required)", "tags": [ "reports" ], "security": [ { "API-Key": [] } ], "requestBody": { "required": true, "description": "Report filters and history bucket size", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "paymentSourceId": { "type": "string", "minLength": 1, "maxLength": 250 }, "managedWalletIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "externalAddresses": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "minItems": 1, "maxItems": 2, "default": [ "Buyer", "Seller" ] }, "states": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, { "type": "string", "enum": [ "Pending" ] } ] }, "maxItems": 11 }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" }, "dateBasis": { "type": "string", "enum": [ "CreatedAt", "FundsLockedAt", "RevenueRecognizedAt" ], "default": "RevenueRecognizedAt" }, "revenueMode": { "type": "string", "enum": [ "Billable", "CashReceived", "RequestedGross" ], "default": "Billable" }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100, "default": "Etc/UTC" }, "fiat": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "usd", "eur", "gbp", "jpy", "chf", "aed" ] }, "mode": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ], "default": "PeriodAverage" }, "suppliedRates": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 200 }, "rate": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)(?:\\.\\d+)?$" }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "unit", "rate" ] }, "maxItems": 100 } }, "required": [ "currency" ] } }, "required": [ "paymentSourceId", "from", "to" ] }, { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "Auto", "Day", "Week", "Month" ], "default": "Auto" } } } ], "example": { "paymentSourceId": "payment_source_id", "managedWalletIds": [ "managed_wallet_id" ], "externalAddresses": [ "addr_test1_external" ], "roles": [ "Buyer", "Seller" ], "states": [ "FundsLocked", "Withdrawn" ], "from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00.000Z", "dateBasis": "RevenueRecognizedAt", "revenueMode": "Billable", "timeZone": "Etc/UTC", "bucket": "Auto" } } } } }, "responses": { "200": { "description": "Payment source totals CSV", "headers": { "Content-Disposition": { "description": "Attachment filename, including an RFC 5987 UTF-8 filename", "schema": { "type": "string" } }, "Content-Length": { "description": "Artifact size in bytes", "schema": { "type": "integer", "format": "int64", "minimum": 0 } } }, "content": { "text/csv; charset=utf-8": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The report filters or cursor are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "404": { "description": "The payment source or requested managed wallet is not accessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "413": { "description": "The report exceeds its row or file size limit; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "429": { "description": "The API key exceeded its report request rate", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "502": { "description": "The exchange rate provider could not price a requested asset", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "503": { "description": "All report processing slots are in use", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "504": { "description": "The report calculation timed out; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } } } } }, "/reports/export.zip": { "post": { "description": "Downloads a ZIP archive containing transactions.csv, wallet-summary.csv, and totals.csv from one database snapshot.", "summary": "Complete transaction report ZIP archive. (read access required)", "tags": [ "reports" ], "security": [ { "API-Key": [] } ], "requestBody": { "required": true, "description": "Report filters and history bucket size", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "paymentSourceId": { "type": "string", "minLength": 1, "maxLength": 250 }, "managedWalletIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "externalAddresses": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 250 }, "maxItems": 100 }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "Buyer", "Seller" ] }, "minItems": 1, "maxItems": 2, "default": [ "Buyer", "Seller" ] }, "states": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "WithdrawAuthorized", "RefundAuthorized", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, { "type": "string", "enum": [ "Pending" ] } ] }, "maxItems": 11 }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" }, "dateBasis": { "type": "string", "enum": [ "CreatedAt", "FundsLockedAt", "RevenueRecognizedAt" ], "default": "RevenueRecognizedAt" }, "revenueMode": { "type": "string", "enum": [ "Billable", "CashReceived", "RequestedGross" ], "default": "Billable" }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100, "default": "Etc/UTC" }, "fiat": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "usd", "eur", "gbp", "jpy", "chf", "aed" ] }, "mode": { "type": "string", "enum": [ "PeriodAverage", "AccountingDate", "TransactionTime" ], "default": "PeriodAverage" }, "suppliedRates": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 200 }, "rate": { "type": "string", "pattern": "^(?:0|[1-9]\\d*)(?:\\.\\d+)?$" }, "from": { "type": "string", "nullable": true, "format": "date-time" }, "to": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "unit", "rate" ] }, "maxItems": 100 } }, "required": [ "currency" ] } }, "required": [ "paymentSourceId", "from", "to" ] }, { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "Auto", "Day", "Week", "Month" ], "default": "Auto" } } } ], "example": { "paymentSourceId": "payment_source_id", "managedWalletIds": [ "managed_wallet_id" ], "externalAddresses": [ "addr_test1_external" ], "roles": [ "Buyer", "Seller" ], "states": [ "FundsLocked", "Withdrawn" ], "from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00.000Z", "dateBasis": "RevenueRecognizedAt", "revenueMode": "Billable", "timeZone": "Etc/UTC", "bucket": "Auto" } } } } }, "responses": { "200": { "description": "Complete transaction report ZIP archive", "headers": { "Content-Disposition": { "description": "Attachment filename, including an RFC 5987 UTF-8 filename", "schema": { "type": "string" } }, "Content-Length": { "description": "Artifact size in bytes", "schema": { "type": "integer", "format": "int64", "minimum": 0 } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The report filters or cursor are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "404": { "description": "The payment source or requested managed wallet is not accessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "413": { "description": "The report exceeds its row or file size limit; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "429": { "description": "The API key exceeded its report request rate", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "502": { "description": "The exchange rate provider could not price a requested asset", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "503": { "description": "All report processing slots are in use", "headers": { "Retry-After": { "description": "Minimum seconds before another report request", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } }, "504": { "description": "The report calculation timed out; narrow the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "status", "error" ] } } } } } } } } }