Sign in
purchase

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

Changed on

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

get/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

Query parameters

limitnumber

The number of purchases to return

cursorIdstring

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

network'Preprod' | 'Mainnet' required

The network the purchases were made on

filterSmartContractAddressstring nullable

The smart contract address of the payment source. When omitted with no explicit payment source type, purchase list/count endpoints default to Web3CardanoV1 for backwards compatibility. Supplying this field queries that exact V1 or V2 source.

filterOnChainState'FundsLocked' | 'FundsOrDatumInvalid' | 'ResultSubmitted' | 'RefundRequested' | 'Disputed' | 'WithdrawAuthorized' | 'RefundAuthorized' | 'Withdrawn' | 'RefundWithdrawn' | 'DisputedWithdrawn'

Filter by on-chain state

filterPaymentSourceType'Web3CardanoV1' | 'Web3CardanoV2'

Filter by payment source type. When omitted with no smart-contract-address filter, purchase list/count endpoints default to Web3CardanoV1 for backwards compatibility.

filterNeedsManualActionstring

When true, only returns purchases that require manual resolution: the next action is WaitingForManualAction or an error was recorded on it

filterAgentIdentifierstring

Restrict results to one or more agents by exact agent identifier, as a comma-separated list of at most 20. Prefer this over searchQuery when filtering by agent: it is an exact (case-insensitive) match and will not match other fields. Supplying this field does not apply the default Web3CardanoV1 compatibility filter, so agents on a Web3CardanoV2 source are found too. A value naming no agent matches nothing.

searchQuerystring

Free-text search. Matches ID, blockchain identifier (exact), agent identifier, agent name, smart contract wallet address, on-chain state, layer ("L1", "L2" or "hydra"), or amount. A query that looks like a hash (5+ hex characters) additionally matches input hash, result hash, Hydra head ID, and the current or any historical transaction hash. Matching is case-insensitive, and "%" and "_" are matched literally.

includeHistorystring

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

Response

Purchase status

statusstring required

Example response

{
  "status": "Success",
  "data": {
    "Purchases": [
      {
        "id": "cuid_v2_auto_generated",
        "blockchainIdentifier": "blockchain_identifier",
        "agentIdentifier": "agent_identifier",
        "lastCheckedAt": null,
        "onChainState": null,
        "metadata": null,
        "requestedById": "requester_id",
        "resultHash": "",
        "cooldownTime": 0,
        "payByTime": null,
        "cooldownTimeOtherParty": 0,
        "collateralReturnLovelace": null,
        "inputHash": "input_hash",
        "NextAction": {
          "requestedAction": "FundsLockingRequested",
          "errorType": null,
          "errorNote": null
        },
        "createdAt": "1970-01-20T20:00:36.260Z",
        "updatedAt": "1970-01-20T20:00:36.260Z",
        "externalDisputeUnlockTime": "1713636260",
        "submitResultTime": "1970-01-20T20:00:36.260Z",
        "unlockTime": "1713636260",
        "PaidFunds": [],
        "PaymentSource": {
          "id": "payment_source_id",
          "network": "Preprod",
          "policyId": "policy_id",
          "smartContractAddress": "address"
        },
        "SellerWallet": null,
        "SmartContractWallet": null,
        "CurrentTransaction": null,
        "TransactionHistory": [],
        "WithdrawnForSeller": [],
        "WithdrawnForBuyer": [],
        "totalBuyerCardanoFees": 0,
        "totalSellerCardanoFees": 0,
        "nextActionOrOnChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z",
        "nextActionLastChangedAt": "1970-01-20T20:00:36.260Z",
        "onChainStateOrResultLastChangedAt": "1970-01-20T20:00:36.260Z"
      }
    ]
  }
}

Changes

  • 315a2a763fb7Revision changes
    • warning

      for the query request parameter searchQuery, the maxLength was set to 500

    • info

      added the new optional query request parameter filterAgentIdentifier

    • 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

  • 87b151d07425Revision changes
    • breaking

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

    • breaking

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

    • warning

      deleted the query request parameter filterAgentIdentifier

    • 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