Guides

Buying Guide

Suggest Edits
  1. /* One of several possible responses -- all responses follow this basic structure */
{
  "data": {
    "buy": {
      "label": "Confirm transaction in your wallet",
      "description": "To purchase this item you must confirm the transaction and pay the gas fee",
      "type": "transaction",
      "name": "sale",
      "item": {
        "data": "{\"from\":\"0x1611036b9fd2091741f320d45f4b2ec7785de274\",\"to\":\"0x00000000000000adc04c56bf30ac9d3c0aaf14dc\",\"data\":\"0x0000000000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000581a8f21c8f000000000000000000000000000622a5b6c4e544a4c085745c4b147d995bb235bbe000000000000000000000000004c00500000ad104d7dbd00e3ae0a5c00560c000000000000000000000000006e4c6d9b0930073e958abd2aba516b885260b8ff00000000000000000000000000000000000000000000000000000000000203c7000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000064dc162d0000000000000000000000000000000000000000000000000000000064dc243d000000000000000000000000000000000000000000000000000000000000000072db8c0b0000000000000000000000000000000000000000305f52bd170fdee70000007b02230091a7ed01230072f7006a004d60a8d4e71d599b8104250f00000000007b02230091a7ed01230072f7006a004d60a8d4e71d599b8104250f000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000240000000000000000000000000000000000000000000000000000000000000026000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000040b56064a4d0e695d7a289df8d7df9550c411b14a57f966ce41f490688b6a1a14f23018aac61fabe2e94fe213e8295bfd2505e2efa717a42a83deee954b79ecce01d4da48b4bf8877e\",\"value\":\"0x581a8f21c8f000\"}",
        "tx_hash": null,
        "order_data": "{}",
        "order_indexes": null
      },
      "steps_summary": [
        {
          "description": "To purchase this item you must confirm the transaction and pay the gas fee",
          "label": "Confirm transaction in your wallet",
          "name": "sale",
          "status": "incomplete"
        }
      ]
    }
  }
}
  • The same endpoint is used from start to finish.
    • The response contains the step that needs to be performed.
    • Some steps will require more parameters to be passed in (e.g. signature or txHash)
  • steps_summary shows the steps that are left to complete the transaction
    • status indicates if this is already done or not.
  • The type property determines what needs to be done on the frontend
    • For transaction, the item.data needs to be called in sendTransaction in the data field
      • Because transactions take some time to settle, you can call the endpoint again with the txHash passed in to get the status of the transaction.
      • It is recommended that you don't keep spamming the endpoint as you will get rate limited.
      • {
    "query": "\n  query Buy(\n    $chainId: Int!\n    $listingId: Int!\n    $takerAddress: String!\n    $signature: String\n    $skipNetworkCheck: Boolean\n    $txHash: String\n  ) {\n    buy(\n      chain_id: $chainId\n      listing_id: $listingId\n      taker_address: $takerAddress\n      signature: $signature\n      skip_network_check: $skipNetworkCheck\n      tx_hash: $txHash\n    ) {\n      label\n      description\n      type\n      name\n      item {\n        data\n        tx_hash\n        order_data\n        order_indexes\n      }\n      steps_summary {\n        description\n        label\n        name\n        status\n      }\n    }\n  }\n",
    "variables": {
        "chainId": 1,
        "listingId": 6762667,
        "takerAddress": "0x1611036b9Fd2091741F320d45f4B2Ec7785DE274",
        "signature": "",
        "skipNetworkCheck": true,
        "txHash": "0x2b6d45b9e7d266b773d0b0378bae4dda81fe2abc92fcf4366482518750d0a45e"
    }
}
      • If the transaction is still settling you will get:
      • {
  "data": {
    "buy": {
      "label": "Scanning the blockchain",
      "description": "We are waiting for the blockchain confirmation",
      "type": "confirmation",
      "name": "status-pending",
      "item": null,
      "steps_summary": null
    }
  }
}
      • Once the transaction is settled, you will get:
      • {
  "data": {
    "buy": {
      "label": "Buy was successful",
      "description": "Congrats! You successfully bought the item.",
      "type": "confirmation",
      "name": "buy-success",
      "item": null,
      "steps_summary": null
    }
  }
}
    • For signature, the item.data needs to be passed in the signature call.
      • If the item.data.kind is eip191, the signing function should be signMessage
      • Otherwise, signTypeData should be called with an object with the following keys: domain, types, message, primaryType.
      • After the signature step is performed on the client side, the endpoint should be called again with the same parameters along with the signature generated from the wallet.
    • For all endpoints, you can show the user a success UI when you get a response back with the name that includes success in its value.