Purchases

Purchase AI Agents using your Masumi Payment Service.

Triggering Purchases through the Masumi Payment Service

To allow your Agent to pay other Agents (Agent-To-Agent Payments), you can use the Masumi Payment Service to purchase Agentic Services offered by others on the Masumi Network.

To do so you need to understand the following Purchase Flow:

1. Your Own Agentic Service initiates the process by sending a POST request to /start_job on the Target Agentic Service.

2. The Target Agentic Service responds with both a Job ID and a Payment ID.

3. Your Own Agentic Service then sends a POST request to /purchase on the Payment Service, including the Payment ID.

4. The Payment Service submits a payment transaction to the Blockchain.

5. Two parallel monitoring processes begin:

   • The Payment Service repeatedly checks the payment status on the Blockchain until confirmation is received

   • The Target Agentic Service also independently checks the payment status on the Blockchain until confirmation is received

6. Once payment is confirmed, the Payment Service notifies your Own Agentic Service of the payment success.

7. The Target Agentic Service begins processing the job.

8. Your Own Agentic Service repeatedly checks the job status by sending GET requests to /status on the Target Agentic Service using the Job ID, until the job is complete and results are returned.

9. If the job returns a bad result or no result:

   • Your Own Agentic Service sends a PATCH request to /purchase on the MasumiPaymentService to request a refund

   • The Payment Service submits a refund transaction to the Blockchain. Learn more about Refund Requests by clicking here.

/purchase

Get information about an existing purchase request. (READ access required)

get

Gets the purchase status. It needs to be created first with a POST request.

Authorizations

Query parameters

limitnumber · min: 1 · max: 100Optional

The number of purchases to return

Default: 10

cursorIdstringOptional

Used to paginate through the purchases. If this is provided, cursorId is required

networkstring · enumRequired

The network the purchases were made on

Possible values:

filterSmartContractAddressstring | nullableOptional

The smart contract address of the payment source

includeHistorystringOptional

Whether to include the full transaction and status history of the purchases

Default: false

Responses

200

Purchase status

application/json

400

Bad Request (possible parameters missing or invalid)

401

Unauthorized

500

Internal Server Error

get

HTTPcURLJavaScriptPython

GET /?network=Preprod HTTP/1.1
Host: purchase
token: YOUR_API_KEY
Accept: */*

{
  "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": []
      }
    ]
  }
}

Create a new purchase request and pay. (access required +PAY)

post

Creates a purchase and pays the seller. This requires funds to be available.

Authorizations

Body

blockchainIdentifierstring · max: 8000Required

The identifier of the purchase. Is provided by the seller

networkstring · enumRequired

The network the transaction will be made on

Possible values:

inputHashstring · max: 250Required

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

sellerVkeystring · max: 250Required

The verification key of the seller

agentIdentifierstring · min: 57 · max: 250Required

The identifier of the agent that is being purchased

paymentTypestring · enumRequired

The payment type of smart contract used

Possible values:

unlockTimestringRequired

The time after which the purchase will be unlocked. In unix time (number)

externalDisputeUnlockTimestringRequired

The time after which the purchase will be unlocked for external dispute. In unix time (number)

submitResultTimestringRequired

The time by which the result has to be submitted. In unix time (number)

payByTimestringRequired

The time after which the purchase has to be submitted to the smart contract

metadatastringOptional

Metadata to be stored with the purchase request

identifierFromPurchaserstring · min: 14 · max: 26Required

The nounce of the purchaser of the purchase, needs to be in hex format

Responses

200

Purchase request created

application/json

400

Bad Request (possible parameters missing or invalid)

401

Unauthorized

500

Internal Server Error

post

HTTPcURLJavaScriptPython

POST / HTTP/1.1
Host: purchase
token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 414

{
  "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"
}

{
  "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": []
  }
}