{ "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": {}, "parameters": {} }, "paths": { "/health/": { "get": { "tags": [ "health" ], "summary": "Get the status of the API server", "responses": { "200": { "description": "Object with status ok, if the server is running", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "example": { "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": { "type": "object", "properties": { "token": { "type": "string" }, "permission": { "type": "string", "enum": [ "Read", "ReadAndPay", "Admin" ] }, "usageLimited": { "type": "boolean" }, "networkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] } }, "RemainingUsageCredits": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "unit", "amount" ] } }, "status": { "type": "string", "enum": [ "Active", "Revoked" ] } }, "required": [ "token", "permission", "usageLimited", "networkLimit", "RemainingUsageCredits", "status" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "status": "Active", "token": "masumi_payment_api_key_secret", "permission": "Admin", "networkLimit": [ "Preprod" ], "usageLimited": true, "RemainingUsageCredits": [ { "unit": "", "amount": "10000000" } ] } } } } } } } } }, "/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" ], "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": { "type": "object", "properties": { "Secret": { "type": "object", "properties": { "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "mnemonic": { "type": "string" } }, "required": [ "createdAt", "updatedAt", "mnemonic" ] }, "PendingTransaction": { "type": "object", "nullable": true, "properties": { "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hash": { "type": "string", "nullable": true }, "lastCheckedAt": { "type": "string", "nullable": true } }, "required": [ "createdAt", "updatedAt", "hash", "lastCheckedAt" ] }, "note": { "type": "string", "nullable": true }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "PendingTransaction", "note", "walletVkey", "walletAddress" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "walletVkey": "wallet_vkey", "note": "note", "PendingTransaction": null, "walletAddress": "wallet_address", "Secret": { "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "mnemonic": "decoded_secret" } } } } } } } } }, "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": { "walletMnemonic": { "type": "string" }, "walletAddress": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "walletMnemonic", "walletAddress", "walletVkey" ], "example": { "walletMnemonic": "wallet_mnemonic", "walletAddress": "wallet_address", "walletVkey": "wallet_vkey" } } } } } } } }, "/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": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 550, "description": "Used to paginate through the API keys" }, "required": false, "description": "Used to paginate through the API keys", "name": "cursorToken", "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": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "permission": { "type": "string", "enum": [ "Read", "ReadAndPay", "Admin" ] }, "usageLimited": { "type": "boolean" }, "networkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] } }, "RemainingUsageCredits": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "unit", "amount" ] } }, "status": { "type": "string", "enum": [ "Active", "Revoked" ] } }, "required": [ "id", "token", "permission", "usageLimited", "networkLimit", "RemainingUsageCredits", "status" ] } } }, "required": [ "ApiKeys" ] } }, "required": [ "status", "data" ], "example": { "data": { "ApiKeys": [ { "id": "unique_cuid_v2_of_entry", "token": "masumi_payment_api_key_secret", "permission": "Admin", "usageLimited": true, "RemainingUsageCredits": [ { "unit": "", "amount": "10000000" } ], "status": "Active", "networkLimit": [ "Mainnet" ] } ] }, "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", "default": "true", "description": "Whether the API key is usage limited. Meaning only allowed to use the specified credits or can freely spend" }, "UsageCredits": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 150 }, "amount": { "type": "string" } }, "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 networks the API key is allowed to use" }, "permission": { "type": "string", "enum": [ "Read", "ReadAndPay", "Admin" ], "default": "Read", "description": "The permission of the API key" } }, "required": [ "UsageCredits" ], "example": { "usageLimited": "true", "UsageCredits": [ { "unit": "", "amount": "10000000" } ], "permission": "Admin" } } } } }, "responses": { "200": { "description": "API key deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "permission": { "type": "string", "enum": [ "Read", "ReadAndPay", "Admin" ] }, "usageLimited": { "type": "boolean" }, "networkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] } }, "status": { "type": "string", "enum": [ "Active", "Revoked" ] } }, "required": [ "id", "token", "permission", "usageLimited", "networkLimit", "status" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "success", "data": { "id": "unique_cuid_v2_of_entry_to_delete", "token": "masumi_payment_api_key_secret", "permission": "Admin", "usageLimited": true, "networkLimit": [ "Preprod" ], "status": "Active" } } } } } }, "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 }, "amount": { "type": "string" } }, "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", "default": true, "description": "Whether the API key is usage limited" }, "status": { "type": "string", "enum": [ "Active", "Revoked" ], "default": "Active", "description": "The status of the API key" }, "networkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "maxItems": 3, "default": [ "Mainnet", "Preprod" ], "description": "The networks the API key is allowed to use" } }, "required": [ "id" ], "example": { "id": "unique_cuid_v2_of_entry_to_update", "token": "api_key_to_change_to", "UsageCreditsToAddOrRemove": [ { "unit": "", "amount": "10000000" }, { "unit": "usdm_policy_and_asset_id", "amount": "-10000000" } ], "status": "Active" } } } } }, "responses": { "200": { "description": "API key deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "permission": { "type": "string", "enum": [ "Read", "ReadAndPay", "Admin" ] }, "networkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] } }, "usageLimited": { "type": "boolean" }, "status": { "type": "string", "enum": [ "Active", "Revoked" ] } }, "required": [ "id", "token", "permission", "networkLimit", "usageLimited", "status" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "success", "data": { "id": "unique_cuid_v2_of_entry_to_delete", "token": "masumi_payment_api_key_secret", "permission": "Admin", "usageLimited": true, "networkLimit": [ "Preprod", "Mainnet" ], "status": "Active" } } } } } }, "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": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "permission": { "type": "string", "enum": [ "Read", "ReadAndPay", "Admin" ] }, "usageLimited": { "type": "boolean" }, "networkLimit": { "type": "array", "items": { "type": "string", "enum": [ "Preprod", "Mainnet" ] } }, "status": { "type": "string", "enum": [ "Active", "Revoked" ] }, "deletedAt": { "type": "string", "nullable": true } }, "required": [ "id", "token", "permission", "usageLimited", "networkLimit", "status", "deletedAt" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "success", "data": { "id": "unique_cuid_v2_of_entry_to_delete", "token": "masumi_registry_api_key_secret", "status": "Revoked", "permission": "Admin", "usageLimited": true, "networkLimit": [ "Preprod", "Mainnet" ], "deletedAt": "1970-01-20T20:00:36.260Z" } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/payment/": { "get": { "description": "Gets the payment status. It needs to be created first with a POST request.", "summary": "Get information about a payment request. (admin 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" }, "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 payments" }, "required": false, "description": "Whether to include the full transaction and status 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": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "collateralReturnLovelace": { "type": "string", "nullable": true }, "externalDisputeUnlockTime": { "type": "string" }, "requestedById": { "type": "string" }, "resultHash": { "type": "string" }, "inputHash": { "type": "string" }, "cooldownTime": { "type": "number" }, "cooldownTimeOtherParty": { "type": "number" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true }, "resultHash": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "txHash" ] }, "TransactionHistory": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "txHash" ] } }, "RequestedFunds": { "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" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "smartContractAddress", "policyId", "paymentType" ] }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "collateralReturnLovelace", "externalDisputeUnlockTime", "requestedById", "resultHash", "inputHash", "cooldownTime", "cooldownTimeOtherParty", "onChainState", "NextAction", "CurrentTransaction", "TransactionHistory", "RequestedFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "BuyerWallet", "SmartContractWallet", "metadata" ] } } }, "required": [ "Payments" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Payments": [ { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_identifier", "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, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "CurrentTransaction": null, "TransactionHistory": [], "RequestedFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "smartContractAddress": "address", "policyId": "policy_id", "paymentType": "Web3CardanoV1" }, "WithdrawnForSeller": [], "WithdrawnForBuyer": [], "BuyerWallet": null, "SmartContractWallet": null, "metadata": null } ] } } } } } }, "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. (admin access required +PAY)", "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" }, "RequestedFunds": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "maxLength": 25 }, "unit": { "type": "string", "maxLength": 150 } }, "required": [ "amount", "unit" ] }, "maxItems": 7, "description": "The amounts of the payment, should be null for fixed amount" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ], "description": "The type of payment contract used" }, "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" }, "identifierFromPurchaser": { "type": "string", "minLength": 14, "maxLength": 26, "description": "The a unique nonce from the purchaser. Required to be in hex format" } }, "required": [ "inputHash", "network", "agentIdentifier", "paymentType", "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", "paymentType": "Web3CardanoV1", "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" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "payByTime": { "type": "string" }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "requestedById": { "type": "string" }, "inputHash": { "type": "string" }, "resultHash": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ] }, "resultHash": { "type": "string", "nullable": true }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "resultHash", "errorType", "errorNote" ] }, "RequestedFunds": { "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" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "smartContractAddress", "policyId", "paymentType" ] }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "lastCheckedAt", "requestedById", "inputHash", "resultHash", "onChainState", "NextAction", "RequestedFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "BuyerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "example": { "status": "success", "data": { "id": "cuid_v2_auto_generated", "inputHash": "input_hash", "blockchainIdentifier": "blockchain_identifier", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "payByTime": "0", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "RequestedFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "smartContractAddress": "address", "paymentType": "Web3CardanoV1" }, "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } } }, "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. (admin access required +PAY)", "summary": "Completes a payment request. This will collect the funds after the unlock time. (admin access required +PAY)", "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", "maxLength": 250, "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", "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" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "requestedById": { "type": "string" }, "resultHash": { "type": "string" }, "inputHash": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true }, "resultHash": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ] }, "RequestedFunds": { "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" ] }, "policyId": { "type": "string", "nullable": true }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "policyId", "smartContractAddress", "paymentType" ] }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "lastCheckedAt", "requestedById", "resultHash", "inputHash", "onChainState", "NextAction", "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", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "requestedById": "requester_id", "payByTime": null, "resultHash": "result_hash", "onChainState": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "RequestedFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "policyId": "policy_id", "smartContractAddress": "address", "paymentType": "Web3CardanoV1" }, "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "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.", "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. (admin access required +PAY)", "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": "API key deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "requestedById": { "type": "string" }, "resultHash": { "type": "string" }, "inputHash": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true }, "resultHash": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ] }, "RequestedFunds": { "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" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "smartContractAddress", "policyId", "paymentType" ] }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "lastCheckedAt", "requestedById", "resultHash", "inputHash", "onChainState", "NextAction", "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", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "lastCheckedAt": null, "payByTime": null, "requestedById": "requester_id", "resultHash": "result_hash", "onChainState": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "AuthorizeRefundRequested", "errorType": null, "errorNote": null, "resultHash": null }, "RequestedFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "policyId": "policy_id", "smartContractAddress": "address", "paymentType": "Web3CardanoV1" }, "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/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" }, "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 status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "Purchases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "requestedById": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "collateralReturnLovelace": { "type": "string", "nullable": true }, "cooldownTime": { "type": "number" }, "cooldownTimeOtherParty": { "type": "number" }, "inputHash": { "type": "string" }, "resultHash": { "type": "string" }, "NextAction": { "type": "object", "properties": { "inputHash": { "type": "string" }, "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true } }, "required": [ "inputHash", "requestedAction", "errorType", "errorNote" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status" ] }, "TransactionHistory": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status" ] } }, "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" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "smartContractAddress", "policyId", "paymentType" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "requestedById", "onChainState", "collateralReturnLovelace", "cooldownTime", "cooldownTimeOtherParty", "inputHash", "resultHash", "NextAction", "CurrentTransaction", "TransactionHistory", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] } } }, "required": [ "Purchases" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "Purchases": [ { "id": "cuid_v2_auto_generated", "blockchainIdentifier": "blockchain_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, "inputHash": "input_hash" }, "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", "paymentType": "Web3CardanoV1" }, "SellerWallet": null, "SmartContractWallet": null, "CurrentTransaction": null, "TransactionHistory": [], "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } ] } } } } } }, "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" }, "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": 25 }, "unit": { "type": "string", "maxLength": 150 } }, "required": [ "amount", "unit" ] }, "maxItems": 7, "description": "The amounts to be paid for the purchase" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ], "description": "The payment type of smart contract used" }, "unlockTime": { "type": "string", "description": "The time after which the purchase will be unlocked. In unix time (number)" }, "externalDisputeUnlockTime": { "type": "string", "description": "The time after which the purchase will be unlocked for external dispute. In unix time (number)" }, "submitResultTime": { "type": "string", "description": "The time by which the result has to be submitted. In unix time (number)" }, "payByTime": { "type": "string", "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" }, "identifierFromPurchaser": { "type": "string", "minLength": 14, "maxLength": 26, "description": "The nonce of the purchaser of the purchase, needs to be in hex format" } }, "required": [ "blockchainIdentifier", "network", "inputHash", "sellerVkey", "agentIdentifier", "paymentType", "unlockTime", "externalDisputeUnlockTime", "submitResultTime", "payByTime", "identifierFromPurchaser" ], "example": { "identifierFromPurchaser": "aabbaabb11221122aabb", "network": "Preprod", "sellerVkey": "seller_vkey", "paymentType": "Web3CardanoV1", "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" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "requestedById": { "type": "string" }, "resultHash": { "type": "string" }, "inputHash": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "errorType", "errorNote" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status" ] }, "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" ] }, "policyId": { "type": "string", "nullable": true }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "policyId", "smartContractAddress", "paymentType" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "requestedById", "resultHash", "inputHash", "onChainState", "NextAction", "CurrentTransaction", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "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", "lastCheckedAt": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "payByTime": null, "requestedById": "requester_id", "resultHash": "", "onChainState": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "PaidFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "smartContractAddress": "address", "paymentType": "Web3CardanoV1" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } } }, "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" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "requestedById": { "type": "string" }, "resultHash": { "type": "string" }, "inputHash": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "errorType", "errorNote" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status" ] }, "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" ] }, "policyId": { "type": "string", "nullable": true }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "policyId", "smartContractAddress", "paymentType" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "requestedById", "resultHash", "inputHash", "onChainState", "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", "createdAt": "1970-01-20T20:00:36.260Z", "updatedAt": "1970-01-20T20:00:36.260Z", "blockchainIdentifier": "blockchain_identifier", "lastCheckedAt": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "payByTime": null, "requestedById": "requester_id", "resultHash": "", "onChainState": null, "inputHash": "input_hash", "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "PaidFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "smartContractAddress": "address", "paymentType": "Web3CardanoV1" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } }, "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": "API key deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "requestedById": { "type": "string" }, "resultHash": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "errorType", "errorNote" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status" ] }, "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" ] }, "policyId": { "type": "string", "nullable": true }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "policyId", "smartContractAddress", "paymentType" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "requestedById", "resultHash", "onChainState", "NextAction", "CurrentTransaction", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "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", "lastCheckedAt": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "payByTime": null, "requestedById": "requester_id", "resultHash": "", "onChainState": null, "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "PaidFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "smartContractAddress": "address", "paymentType": "Web3CardanoV1" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } } } }, "/purchase/cancel-refund-request": { "post": { "description": "Requests a refund for a completed purchase. This will collect the refund after the refund time.", "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": "API key deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "requestedById": { "type": "string" }, "resultHash": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "errorType", "errorNote" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status" ] }, "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" ] }, "policyId": { "type": "string", "nullable": true }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "policyId", "smartContractAddress", "paymentType" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "requestedById", "resultHash", "onChainState", "NextAction", "CurrentTransaction", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] }, "status": { "type": "string" } }, "required": [ "data", "status" ], "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", "lastCheckedAt": null, "submitResultTime": "0", "unlockTime": "0", "externalDisputeUnlockTime": "0", "payByTime": null, "requestedById": "requester_id", "resultHash": "", "onChainState": null, "NextAction": { "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "PaidFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "policyId": "policy_id", "network": "Preprod", "smartContractAddress": "address", "paymentType": "Web3CardanoV1" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } } }, "400": { "description": "Bad Request (possible parameters missing or invalid)" }, "401": { "description": "Unauthorized" }, "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", "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": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "collateralReturnLovelace": { "type": "string", "nullable": true }, "externalDisputeUnlockTime": { "type": "string" }, "requestedById": { "type": "string" }, "resultHash": { "type": "string" }, "inputHash": { "type": "string" }, "cooldownTime": { "type": "number" }, "cooldownTimeOtherParty": { "type": "number" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "NextAction": { "type": "object", "properties": { "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "SubmitResultRequested", "SubmitResultInitiated", "WithdrawRequested", "WithdrawInitiated", "AuthorizeRefundRequested", "AuthorizeRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true }, "resultHash": { "type": "string", "nullable": true } }, "required": [ "requestedAction", "errorType", "errorNote", "resultHash" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "txHash" ] }, "TransactionHistory": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "txHash" ] } }, "RequestedFunds": { "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" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "smartContractAddress", "policyId", "paymentType" ] }, "BuyerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "collateralReturnLovelace", "externalDisputeUnlockTime", "requestedById", "resultHash", "inputHash", "cooldownTime", "cooldownTimeOtherParty", "onChainState", "NextAction", "CurrentTransaction", "TransactionHistory", "RequestedFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "BuyerWallet", "SmartContractWallet", "metadata" ] } }, "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", "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": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "smartContractAddress": "address", "policyId": "policy_id", "paymentType": "Web3CardanoV1" }, "BuyerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } } }, "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", "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": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "blockchainIdentifier": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "payByTime": { "type": "string", "nullable": true }, "submitResultTime": { "type": "string" }, "unlockTime": { "type": "string" }, "externalDisputeUnlockTime": { "type": "string" }, "requestedById": { "type": "string" }, "onChainState": { "type": "string", "nullable": true, "enum": [ "FundsLocked", "FundsOrDatumInvalid", "ResultSubmitted", "RefundRequested", "Disputed", "Withdrawn", "RefundWithdrawn", "DisputedWithdrawn" ] }, "collateralReturnLovelace": { "type": "string", "nullable": true }, "cooldownTime": { "type": "number" }, "cooldownTimeOtherParty": { "type": "number" }, "inputHash": { "type": "string" }, "resultHash": { "type": "string" }, "NextAction": { "type": "object", "properties": { "inputHash": { "type": "string" }, "requestedAction": { "type": "string", "enum": [ "None", "Ignore", "WaitingForManualAction", "WaitingForExternalAction", "FundsLockingRequested", "FundsLockingInitiated", "SetRefundRequestedRequested", "SetRefundRequestedInitiated", "UnSetRefundRequestedRequested", "UnSetRefundRequestedInitiated", "WithdrawRefundRequested", "WithdrawRefundInitiated" ] }, "errorType": { "type": "string", "nullable": true, "enum": [ "NetworkError", "InsufficientFunds", "Unknown" ] }, "errorNote": { "type": "string", "nullable": true } }, "required": [ "inputHash", "requestedAction", "errorType", "errorNote" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status" ] }, "TransactionHistory": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "id", "createdAt", "updatedAt", "txHash", "status" ] } }, "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" ] }, "smartContractAddress": { "type": "string" }, "policyId": { "type": "string", "nullable": true }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] } }, "required": [ "id", "network", "smartContractAddress", "policyId", "paymentType" ] }, "SellerWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" } }, "required": [ "id", "walletVkey" ] }, "SmartContractWallet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "id", "walletVkey", "walletAddress" ] }, "metadata": { "type": "string", "nullable": true } }, "required": [ "id", "createdAt", "updatedAt", "blockchainIdentifier", "lastCheckedAt", "payByTime", "submitResultTime", "unlockTime", "externalDisputeUnlockTime", "requestedById", "onChainState", "collateralReturnLovelace", "cooldownTime", "cooldownTimeOtherParty", "inputHash", "resultHash", "NextAction", "CurrentTransaction", "TransactionHistory", "PaidFunds", "WithdrawnForSeller", "WithdrawnForBuyer", "PaymentSource", "SellerWallet", "SmartContractWallet", "metadata" ] } }, "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", "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": { "inputHash": "input_hash", "requestedAction": "FundsLockingRequested", "errorType": null, "errorNote": null }, "CurrentTransaction": null, "TransactionHistory": [], "PaidFunds": [ { "amount": "10000000", "unit": "" } ], "PaymentSource": { "id": "payment_source_id", "network": "Preprod", "smartContractAddress": "address", "policyId": "policy_id", "paymentType": "Web3CardanoV1" }, "SellerWallet": null, "SmartContractWallet": null, "metadata": null, "WithdrawnForSeller": [], "WithdrawnForBuyer": [] } } } } } }, "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": { "type": "object", "properties": { "policyId": { "type": "string" }, "assetName": { "type": "string" }, "agentIdentifier": { "type": "string" }, "Metadata": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250 }, "description": { "type": "string", "nullable": true, "maxLength": 250 }, "apiBaseUrl": { "type": "string", "maxLength": 250 }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "mimeType": { "type": "string", "maxLength": 60 }, "url": { "type": "string", "maxLength": 250 } }, "required": [ "name", "mimeType", "url" ] }, "maxItems": 25 }, "Tags": { "type": "array", "items": { "type": "string", "maxLength": 250 } }, "Capability": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "maxLength": 250 }, "version": { "type": "string", "nullable": true, "maxLength": 250 } } }, "Author": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250 }, "contactEmail": { "type": "string", "nullable": true, "maxLength": 250 }, "contactOther": { "type": "string", "nullable": true, "maxLength": 250 }, "organization": { "type": "string", "nullable": true, "maxLength": 250 } }, "required": [ "name" ] }, "Legal": { "type": "object", "nullable": true, "properties": { "privacyPolicy": { "type": "string", "nullable": true, "maxLength": 250 }, "terms": { "type": "string", "nullable": true, "maxLength": 250 }, "other": { "type": "string", "nullable": true, "maxLength": 250 } } }, "AgentPricing": { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ] }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string", "maxLength": 250 } }, "required": [ "amount", "unit" ] }, "minItems": 1 } }, "required": [ "pricingType", "Pricing" ] }, "image": { "type": "string", "maxLength": 250 }, "metadataVersion": { "type": "integer", "minimum": 1, "maximum": 1 } }, "required": [ "name", "apiBaseUrl", "ExampleOutputs", "Tags", "Author", "AgentPricing", "image", "metadataVersion" ] } }, "required": [ "policyId", "assetName", "agentIdentifier", "Metadata" ] } } }, "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": [ { "amount": "1000000", "unit": "unit" } ] }, "metadataVersion": 1 } } ] } } } } } } } } }, "/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": "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" }, "required": false, "description": "The smart contract address of the payment source", "name": "filterSmartContractAddress", "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": { "type": "object", "properties": { "error": { "type": "string", "nullable": true }, "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "apiBaseUrl": { "type": "string" }, "Capability": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true } }, "required": [ "name", "version" ] }, "Author": { "type": "object", "properties": { "name": { "type": "string" }, "contactEmail": { "type": "string", "nullable": true }, "contactOther": { "type": "string", "nullable": true }, "organization": { "type": "string", "nullable": true } }, "required": [ "name", "contactEmail", "contactOther", "organization" ] }, "Legal": { "type": "object", "properties": { "privacyPolicy": { "type": "string", "nullable": true }, "terms": { "type": "string", "nullable": true }, "other": { "type": "string", "nullable": true } }, "required": [ "privacyPolicy", "terms", "other" ] }, "state": { "type": "string", "enum": [ "RegistrationRequested", "RegistrationInitiated", "RegistrationConfirmed", "RegistrationFailed", "DeregistrationRequested", "DeregistrationInitiated", "DeregistrationConfirmed", "DeregistrationFailed" ] }, "Tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lastCheckedAt": { "type": "string", "nullable": true }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "url": { "type": "string", "maxLength": 250 }, "mimeType": { "type": "string", "maxLength": 60 } }, "required": [ "name", "url", "mimeType" ] }, "maxItems": 25 }, "agentIdentifier": { "type": "string", "nullable": true, "minLength": 57, "maxLength": 250 }, "AgentPricing": { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ] }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "unit": { "type": "string", "maxLength": 250 } }, "required": [ "amount", "unit" ] }, "minItems": 1 } }, "required": [ "pricingType", "Pricing" ] }, "SmartContractWallet": { "type": "object", "properties": { "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "walletVkey", "walletAddress" ] }, "CurrentTransaction": { "type": "object", "nullable": true, "properties": { "txHash": { "type": "string" }, "status": { "type": "string", "enum": [ "Pending", "Confirmed", "FailedViaTimeout", "RolledBack" ] } }, "required": [ "txHash", "status" ] } }, "required": [ "error", "id", "name", "description", "apiBaseUrl", "Capability", "Author", "Legal", "state", "Tags", "createdAt", "updatedAt", "lastCheckedAt", "ExampleOutputs", "agentIdentifier", "AgentPricing", "SmartContractWallet", "CurrentTransaction" ] } } }, "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": "unit", "amount": "1000000" } ] }, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "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" }, "sellingWalletVkey": { "type": "string", "maxLength": 250, "description": "The payment key of a specific wallet used for the registration" }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "url": { "type": "string", "maxLength": 250 }, "mimeType": { "type": "string", "maxLength": 60 } }, "required": [ "name", "url", "mimeType" ] }, "maxItems": 25 }, "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, "description": "Base URL of the agent, to request interactions" }, "description": { "type": "string", "maxLength": 250, "description": "Description of the agent" }, "Capability": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250 }, "version": { "type": "string", "maxLength": 250 } }, "required": [ "name", "version" ], "description": "Provide information about the used AI model and version" }, "AgentPricing": { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ] }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string", "maxLength": 250 }, "amount": { "type": "string", "maxLength": 25 } }, "required": [ "unit", "amount" ] }, "minItems": 1, "maxItems": 5, "description": "Price for a default interaction" } }, "required": [ "pricingType", "Pricing" ] }, "Legal": { "type": "object", "properties": { "privacyPolicy": { "type": "string", "maxLength": 250 }, "terms": { "type": "string", "maxLength": 250 }, "other": { "type": "string", "maxLength": 250 } }, "description": "Legal information about the agent" }, "Author": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 250 }, "contactEmail": { "type": "string", "maxLength": 250 }, "contactOther": { "type": "string", "maxLength": 250 }, "organization": { "type": "string", "maxLength": 250 } }, "required": [ "name" ], "description": "Author information about the agent" } }, "required": [ "network", "sellingWalletVkey", "ExampleOutputs", "Tags", "name", "apiBaseUrl", "description", "Capability", "AgentPricing", "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", "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": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "Capability": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true } }, "required": [ "name", "version" ] }, "Legal": { "type": "object", "properties": { "privacyPolicy": { "type": "string", "nullable": true }, "terms": { "type": "string", "nullable": true }, "other": { "type": "string", "nullable": true } }, "required": [ "privacyPolicy", "terms", "other" ] }, "Author": { "type": "object", "properties": { "name": { "type": "string" }, "contactEmail": { "type": "string", "nullable": true }, "contactOther": { "type": "string", "nullable": true }, "organization": { "type": "string", "nullable": true } }, "required": [ "name", "contactEmail", "contactOther", "organization" ] }, "description": { "type": "string", "nullable": true }, "Tags": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "RegistrationRequested", "RegistrationInitiated", "RegistrationConfirmed", "RegistrationFailed", "DeregistrationRequested", "DeregistrationInitiated", "DeregistrationConfirmed", "DeregistrationFailed" ] }, "SmartContractWallet": { "type": "object", "properties": { "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "walletVkey", "walletAddress" ] }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "url": { "type": "string", "maxLength": 250 }, "mimeType": { "type": "string", "maxLength": 60 } }, "required": [ "name", "url", "mimeType" ] }, "maxItems": 25 }, "AgentPricing": { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ] }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "unit", "amount" ] } } }, "required": [ "pricingType", "Pricing" ] } }, "required": [ "id", "name", "apiBaseUrl", "Capability", "Legal", "Author", "description", "Tags", "state", "SmartContractWallet", "ExampleOutputs", "AgentPricing" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid2", "apiBaseUrl": "api_url", "Tags": [ "tag1", "tag2" ], "Capability": { "name": "capability_name", "version": "capability_version" }, "Legal": { "privacyPolicy": "privacy_policy", "terms": "terms", "other": "other" }, "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "ExampleOutputs": [], "Author": { "name": "author_name", "organization": "author_organization", "contactEmail": "author_contact_email", "contactOther": "author_contact_other" }, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "state": "RegistrationRequested", "description": "description", "name": "name" } } } } } } } }, "delete": { "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. (admin access required +PAY)", "tags": [ "registry" ], "security": [ { "API-Key": [] } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentIdentifier": { "type": "string", "minLength": 57, "maxLength": 250, "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", "maxLength": 250, "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": "Payment source deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "Capability": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true } }, "required": [ "name", "version" ] }, "Author": { "type": "object", "properties": { "name": { "type": "string" }, "contactEmail": { "type": "string", "nullable": true }, "contactOther": { "type": "string", "nullable": true }, "organization": { "type": "string", "nullable": true } }, "required": [ "name", "contactEmail", "contactOther", "organization" ] }, "Legal": { "type": "object", "properties": { "privacyPolicy": { "type": "string", "nullable": true }, "terms": { "type": "string", "nullable": true }, "other": { "type": "string", "nullable": true } }, "required": [ "privacyPolicy", "terms", "other" ] }, "description": { "type": "string", "nullable": true }, "Tags": { "type": "array", "items": { "type": "string" } }, "SmartContractWallet": { "type": "object", "properties": { "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" } }, "required": [ "walletVkey", "walletAddress" ] }, "state": { "type": "string", "enum": [ "RegistrationRequested", "RegistrationInitiated", "RegistrationConfirmed", "RegistrationFailed", "DeregistrationRequested", "DeregistrationInitiated", "DeregistrationConfirmed", "DeregistrationFailed" ] }, "ExampleOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "url": { "type": "string", "maxLength": 250 }, "mimeType": { "type": "string", "maxLength": 60 } }, "required": [ "name", "url", "mimeType" ] }, "maxItems": 25 }, "AgentPricing": { "type": "object", "properties": { "pricingType": { "type": "string", "enum": [ "Fixed" ] }, "Pricing": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "unit", "amount" ] } } }, "required": [ "pricingType", "Pricing" ] } }, "required": [ "id", "name", "apiBaseUrl", "Capability", "Author", "Legal", "description", "Tags", "SmartContractWallet", "state", "ExampleOutputs", "AgentPricing" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "cuid2", "apiBaseUrl": "api_url", "Tags": [ "tag1", "tag2" ], "Capability": { "name": "capability_name", "version": "capability_version" }, "ExampleOutputs": [ { "name": "example_output_name", "url": "https://example.com/example_output", "mimeType": "application/json" } ], "Author": { "name": "author_name", "organization": "author_organization", "contactEmail": "author_contact_email", "contactOther": "author_contact_other" }, "Legal": { "privacyPolicy": "privacy_policy", "terms": "terms", "other": "other" }, "AgentPricing": { "pricingType": "Fixed", "Pricing": [ { "unit": "", "amount": "10000000" } ] }, "SmartContractWallet": { "walletVkey": "wallet_vkey", "walletAddress": "wallet_address" }, "state": "RegistrationRequested", "description": "description", "name": "name" } } } } } } } } }, "/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": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "policyId": { "type": "string", "nullable": true }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] }, "lastIdentifierChecked": { "type": "string", "nullable": true }, "lastCheckedAt": { "type": "string", "nullable": true }, "AdminWallets": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "order": { "type": "number" } }, "required": [ "walletAddress", "order" ] } }, "PurchasingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "collectionAddress", "note" ] } }, "SellingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "collectionAddress", "note" ] } }, "FeeReceiverNetworkWallet": { "type": "object", "properties": { "walletAddress": { "type": "string" } }, "required": [ "walletAddress" ] }, "feeRatePermille": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "id", "createdAt", "updatedAt", "network", "policyId", "smartContractAddress", "paymentType", "lastIdentifierChecked", "lastCheckedAt", "AdminWallets", "PurchasingWallets", "SellingWallets", "FeeReceiverNetworkWallet", "feeRatePermille" ] } } }, "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", "paymentType": "Web3CardanoV1", "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", "PurchasingWallets": [ { "collectionAddress": null, "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" }, { "collectionAddress": "send_refunds_to_this_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" } ], "SellingWallets": [ { "collectionAddress": "null_will_use_selling_wallet_as_revenue_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" }, { "collectionAddress": "send_revenue_to_this_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" } ] } ] } } } } } } } } }, "/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. (admin 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": { "ExtendedPaymentSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "policyId": { "type": "string", "nullable": true }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] }, "PaymentSourceConfig": { "type": "object", "properties": { "rpcProviderApiKey": { "type": "string" }, "rpcProvider": { "type": "string", "enum": [ "Blockfrost" ] } }, "required": [ "rpcProviderApiKey", "rpcProvider" ] }, "lastIdentifierChecked": { "type": "string", "nullable": true }, "syncInProgress": { "type": "boolean" }, "lastCheckedAt": { "type": "string", "nullable": true }, "AdminWallets": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "order": { "type": "number" } }, "required": [ "walletAddress", "order" ] } }, "PurchasingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "collectionAddress", "note" ] } }, "SellingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "collectionAddress", "note" ] } }, "FeeReceiverNetworkWallet": { "type": "object", "properties": { "walletAddress": { "type": "string" } }, "required": [ "walletAddress" ] }, "feeRatePermille": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "id", "createdAt", "updatedAt", "network", "policyId", "smartContractAddress", "paymentType", "PaymentSourceConfig", "lastIdentifierChecked", "syncInProgress", "lastCheckedAt", "AdminWallets", "PurchasingWallets", "SellingWallets", "FeeReceiverNetworkWallet", "feeRatePermille" ] } } }, "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", "paymentType": "Web3CardanoV1", "feeRatePermille": 50, "syncInProgress": true, "policyId": "policy_id", "smartContractAddress": "address_of_the_smart_contract", "AdminWallets": [ { "walletAddress": "wallet_address", "order": 0 }, { "walletAddress": "wallet_address", "order": 1 }, { "walletAddress": "wallet_address", "order": 2 } ], "FeeReceiverNetworkWallet": { "walletAddress": "wallet_address" }, "lastCheckedAt": "1970-01-20T20:00:36.260Z", "lastIdentifierChecked": "identifier", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key_blockfrost", "rpcProvider": "Blockfrost" }, "PurchasingWallets": [ { "collectionAddress": null, "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" }, { "collectionAddress": "send_refunds_to_this_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" } ], "SellingWallets": [ { "collectionAddress": "null_will_use_selling_wallet_as_revenue_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" }, { "collectionAddress": "send_revenue_to_this_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" } ] } ] } } } } } } } }, "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" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ], "description": "The type of payment source used" }, "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 } }, "required": [ "walletAddress" ] }, "minItems": 3, "maxItems": 3, "description": "The wallet addresses of the admin wallets (exactly 3)" }, "FeeReceiverNetworkWallet": { "type": "object", "properties": { "walletAddress": { "type": "string", "maxLength": 250 } }, "required": [ "walletAddress" ], "description": "The wallet address of the network fee receiver wallet" }, "PurchasingWallets": { "type": "array", "items": { "type": "object", "properties": { "walletMnemonic": { "type": "string", "maxLength": 1500 }, "collectionAddress": { "type": "string", "nullable": true, "maxLength": 250, "description": "The collection address of the purchasing wallet" }, "note": { "type": "string", "maxLength": 250 } }, "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 }, "collectionAddress": { "type": "string", "nullable": true, "maxLength": 250, "description": "The collection address of the selling wallet" }, "note": { "type": "string", "maxLength": 250 } }, "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", "paymentType", "PaymentSourceConfig", "feeRatePermille", "AdminWallets", "FeeReceiverNetworkWallet", "PurchasingWallets", "SellingWallets" ], "example": { "network": "Preprod", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key", "rpcProvider": "Blockfrost" }, "paymentType": "Web3CardanoV1", "AdminWallets": [ { "walletAddress": "wallet_address_1" }, { "walletAddress": "wallet_address_2" }, { "walletAddress": "wallet_address_3" } ], "FeeReceiverNetworkWallet": { "walletAddress": "wallet_address" }, "feeRatePermille": 50, "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": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] }, "PaymentSourceConfig": { "type": "object", "properties": { "rpcProviderApiKey": { "type": "string" }, "rpcProvider": { "type": "string", "enum": [ "Blockfrost" ] } }, "required": [ "rpcProviderApiKey", "rpcProvider" ] }, "lastIdentifierChecked": { "type": "string", "nullable": true }, "syncInProgress": { "type": "boolean" }, "lastCheckedAt": { "type": "string", "nullable": true }, "AdminWallets": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "order": { "type": "number" } }, "required": [ "walletAddress", "order" ] } }, "PurchasingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "collectionAddress", "note" ] } }, "SellingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "collectionAddress", "note" ] } }, "FeeReceiverNetworkWallet": { "type": "object", "properties": { "walletAddress": { "type": "string" } }, "required": [ "walletAddress" ] }, "feeRatePermille": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "id", "createdAt", "updatedAt", "network", "smartContractAddress", "paymentType", "PaymentSourceConfig", "lastIdentifierChecked", "syncInProgress", "lastCheckedAt", "AdminWallets", "PurchasingWallets", "SellingWallets", "FeeReceiverNetworkWallet", "feeRatePermille" ] } }, "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", "paymentType": "Web3CardanoV1", "syncInProgress": true, "smartContractAddress": "address_of_the_smart_contract", "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", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key_blockfrost", "rpcProvider": "Blockfrost" }, "PurchasingWallets": [ { "collectionAddress": null, "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" }, { "collectionAddress": "send_refunds_to_this_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" } ], "SellingWallets": [ { "collectionAddress": "null_will_use_the_selling_wallet_as_revenue_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" }, { "collectionAddress": "send_revenue_to_this_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" } ] } } } } } } } }, "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 }, "note": { "type": "string", "maxLength": 250 }, "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 }, "note": { "type": "string", "maxLength": 250 }, "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" } }, "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" } }, "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": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] }, "smartContractAddress": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "Web3CardanoV1" ] }, "PaymentSourceConfig": { "type": "object", "properties": { "rpcProviderApiKey": { "type": "string" }, "rpcProvider": { "type": "string", "enum": [ "Blockfrost" ] } }, "required": [ "rpcProviderApiKey", "rpcProvider" ] }, "lastIdentifierChecked": { "type": "string", "nullable": true }, "syncInProgress": { "type": "boolean" }, "lastCheckedAt": { "type": "string", "nullable": true }, "AdminWallets": { "type": "array", "items": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "order": { "type": "number" } }, "required": [ "walletAddress", "order" ] } }, "PurchasingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "collectionAddress", "note" ] } }, "SellingWallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "walletVkey": { "type": "string" }, "walletAddress": { "type": "string" }, "collectionAddress": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "required": [ "id", "walletVkey", "walletAddress", "collectionAddress", "note" ] } }, "FeeReceiverNetworkWallet": { "type": "object", "properties": { "walletAddress": { "type": "string" } }, "required": [ "walletAddress" ] }, "feeRatePermille": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "id", "createdAt", "updatedAt", "network", "smartContractAddress", "paymentType", "PaymentSourceConfig", "lastIdentifierChecked", "syncInProgress", "lastCheckedAt", "AdminWallets", "PurchasingWallets", "SellingWallets", "FeeReceiverNetworkWallet", "feeRatePermille" ] } }, "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", "paymentType": "Web3CardanoV1", "syncInProgress": true, "smartContractAddress": "address_of_the_smart_contract", "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", "PaymentSourceConfig": { "rpcProviderApiKey": "rpc_provider_api_key_blockfrost", "rpcProvider": "Blockfrost" }, "PurchasingWallets": [ { "collectionAddress": null, "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" }, { "collectionAddress": "send_refunds_to_this_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" } ], "SellingWallets": [ { "collectionAddress": "null_will_use_selling_wallet_as_revenue_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" }, { "collectionAddress": "send_revenue_to_this_address", "note": "note", "walletVkey": "wallet_vkey", "walletAddress": "wallet_address", "id": "unique_cuid_v2_auto_generated" } ] } } } } } } } }, "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": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "status", "data" ], "example": { "status": "success", "data": { "id": "unique_cuid_v2_auto_generated" } } } } } } } } }, "/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" ] }, "required": true, "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": { "type": "object", "properties": { "txHash": { "type": "string" }, "address": { "type": "string" }, "Amounts": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "quantity": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100000000000000 } }, "required": [ "unit", "quantity" ] } }, "dataHash": { "type": "string", "nullable": true }, "inlineDatum": { "type": "string", "nullable": true }, "referenceScriptHash": { "type": "string", "nullable": true }, "outputIndex": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 1000000000 }, "block": { "type": "string" } }, "required": [ "txHash", "address", "Amounts", "dataHash", "inlineDatum", "referenceScriptHash", "outputIndex", "block" ] } } }, "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" } ] } } } } } } } } }, "/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": { "RpcProviderKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rpcProviderApiKey": { "type": "string" }, "rpcProvider": { "type": "string", "enum": [ "Blockfrost" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "network": { "type": "string", "enum": [ "Preprod", "Mainnet" ] } }, "required": [ "id", "rpcProviderApiKey", "rpcProvider", "createdAt", "updatedAt", "network" ] } } }, "required": [ "RpcProviderKeys" ], "example": { "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" } ] } } } } } } } } } }