purchase

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

Changed on

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

post/purchase

Request

  • Base URL: ./../api/v1/ (relative, and the document was published on a file host, not at the API’s origin)
  • URL: ./../api/v1/purchase
  • Auth: API key in header token

Request body

blockchainIdentifierstring required

The identifier of the purchase. Is provided by the seller

network'Preprod' | 'Mainnet' required

The network the transaction will be made on

paymentSourceType'Web3CardanoV1' | 'Web3CardanoV2'

Optional payment source type hint for this purchase. When omitted, the type is inferred from the blockchainIdentifier shape.

smartContractAddressstring

Optional V2 payment contract address. When omitted, the address is inferred from the signed blockchainIdentifier; when provided, it must match that identifier.

supportedPaymentSourceIndexinteger

The V2 Cardano source index selected when the seller created the payment. The seller signature covers this value. Omit only for legacy V2 identifiers created before source-owned pricing.

inputHashstring required

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 required

The verification key of the seller

agentIdentifierstring required

The identifier of the agent that is being purchased

unlockTimestring required

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

externalDisputeUnlockTimestring required

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

submitResultTimestring required

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

payByTimestring required

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

metadatastring

Metadata to be stored with the purchase request

buyerReturnAddressstring

Optional buyer return address. Defaults to the purchasing hot wallet collection address when available.

sellerReturnAddressstring

Optional seller return address when using a signed V2 identifier from the seller.

identifierFromPurchaserstring required

The nonce of the purchaser. It must be in hex format

forceLayer'L1' | 'Hydra'

Optional buyer layer override. "L1" forces L1; "Hydra" requires an open head and is supported only for V2. It must not conflict with the signed paymentForceLayer. Omit for automatic routing.

paymentForceLayer'L1' | 'Hydra' | 'null' nullable

Seller layer override copied from the payment response. For V2, a non-null value is part of the signed payment terms and cannot be changed or omitted without invalidating the identifier. V1 accepts only the redundant "L1" value for response round-tripping. Omit or pass null when the seller selected automatic routing.

Example request

{
  "identifierFromPurchaser": "aabbaabb11221122aabb",
  "network": "Preprod",
  "sellerVkey": "seller_vkey",
  "blockchainIdentifier": "blockchain_identifier",
  "payByTime": "1713626260",
  "submitResultTime": "1713636260",
  "unlockTime": "1713636260",
  "externalDisputeUnlockTime": "1713636260",
  "agentIdentifier": "agent_identifier",
  "inputHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}

Response

Purchase request created

statusstring required

Example response

{
  "status": "Success",
  "data": {
    "id": "cuid_v2_auto_generated",
    "blockchainIdentifier": "blockchain_identifier",
    "agentIdentifier": "agent_identifier",
    "agentName": "Example Agent",
    "pricingType": "Fixed",
    "createdAt": "1970-01-20T20:00:36.260Z",
    "updatedAt": "1970-01-20T20:00:36.260Z",
    "lastCheckedAt": null,
    "payByTime": null,
    "submitResultTime": "0",
    "unlockTime": "0",
    "externalDisputeUnlockTime": "0",
    "requestedById": "requester_id",
    "onChainState": null,
    "forceLayer": null,
    "paymentForceLayer": null,
    "collateralReturnLovelace": null,
    "buyerReturnAddress": null,
    "sellerReturnAddress": null,
    "cooldownTime": 0,
    "cooldownTimeOtherParty": 0,
    "inputHash": "input_hash",
    "resultHash": null,
    "NextAction": {
      "requestedAction": "FundsLockingRequested",
      "errorType": null,
      "errorNote": null
    },
    "CurrentTransaction": null,
    "PaidFunds": [
      {
        "unit": "",
        "amount": "10000000"
      }
    ],
    "PaymentSource": {
      "id": "payment_source_id",
      "policyId": "policy_id",
      "network": "Preprod",
      "paymentSourceType": "Web3CardanoV1",
      "smartContractAddress": "address"
    },
    "SellerWallet": null,
    "SmartContractWallet": null,
    "metadata": null,
    "WithdrawnForSeller": [],
    "WithdrawnForBuyer": [],
    "totalBuyerCardanoFees": 0,
    "totalSellerCardanoFees": 0,
    "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z",
    "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z",
    "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z"
  }
}

Changes

  • 315a2a763fb7Revision changes
    • breaking

      the // request property's maxLength was decreased to 19

    • breaking

      added the pattern ^\d+$ to the request property //

    • breaking

      added the pattern ^\d+$ to the request property

    • breaking

      added the pattern ^\d+$ to the request property

    • breaking

      added the pattern ^\d+$ to the request property

    • breaking

      added the pattern ^\d+$ to the request property

    • warning

      the request property's maxLength was set to 19

    • warning

      the request property's maxLength was set to 19

    • warning

      the request property's maxLength was set to 19

    • warning

      the request property's maxLength was set to 19

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

  • 87b151d07425Revision changes
    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • info

      the // request property's maxLength was increased from 19 to 25

    • info

      removed the pattern ^\d+$ from the request property //

    • info

      removed the pattern ^\d+$ from the request property

    • info

      removed the pattern ^\d+$ from the request property

    • info

      removed the pattern ^\d+$ from the request property

    • info

      removed the pattern ^\d+$ from the request property