Step Execution Overview

We recommend using the SDK over our APIs. The SDK will iterate the steps and return useful callback information.

Step Execution using the API

When executing orders using the API directly, there are often multiple steps, like submitting a deposit transaction to the solver or signing a message. These steps differ based on the desired action and best route to execute the action. To make this simple, you can use the execute endpoints, which return the exact steps that you need to follow, including descriptions that you can display to users.

The flow looks like this:

1. Fetching Steps

   Call the execute API (call api)

2. Iterate Through Steps

   Iterate through the steps and the items within a step, taking the necessary actions. Steps with no items, or an empty array of items, should be skipped. If step item data is missing then polling the api is necessary

3. Executing Steps

   As mentioned above each step contains an array of one or more items. These items need to be iterated and completed depending on the kind of step (signature or transaction)

4. Success!

   Once all the steps are complete you can consider the action complete and notify the user

Signature Step

A message that needs to be signed. Every signature comes with sign data and post data. The first action we need to take is to sign the message, keep in mind the signatureKind and use the appropriate signing method. Refer to your crypto library of choice on how to sign (viem, web3, etc).

Signing EIP191

// Creating an `EIP-191` signature involves signing a message. 
// When you receive a `signatureKind: "eip191"` from the API, you will sign the value associated with the `message` property. 
// In the case below, the message `Sign in to Blur...` will be signed, and later posted to the API.
// The step item also contains a `post` object detailing the endpoint to post the signed message to.
const message = {
    "signatureKind": "eip191",
    "message": "Sign in to Blur\n\nChallenge: e2483db1d9d66d2b77f47a8dfa13a15a0e7df5aee2287ade4bf313d6d4bdd0e0"
}

const eip191Message = "\x19Ethereum Signed Message:\n" + message.message.length + message.message;

//Creating an EIP-721 signature involves signing a structured object composed of a domain, types, and values.
//When receiving a signatureKind: "eip712" from the API, you'll need to structure the signature in eth_signTypedData_v4 format. 
//Below, you'll find an example that illustrates how the domain, types, and values can be structured to create the signature.
const data = {
        "signatureKind": "eip712",
        "domain": {
            "name": "Seaport",
            "version": "1.5",
            "chainId": 137,
            "verifyingContract": "0x00000000000000adc04c56bf30ac9d3c0aaf14dc"
        },
        "types": {
            "OrderComponents": [
                {
                    "name": "offerer",
                    "type": "address"
                },
                {
                    "name": "zone",
                    "type": "address"
                },
                {
                    "name": "offer",
                    "type": "OfferItem[]"
                },
                {
                    "name": "consideration",
                    "type": "ConsiderationItem[]"
                },
                {
                    "name": "orderType",
                    "type": "uint8"
                },
                {
                    "name": "startTime",
                    "type": "uint256"
                },
                {
                    "name": "endTime",
                    "type": "uint256"
                },
                {
                    "name": "zoneHash",
                    "type": "bytes32"
                },
                {
                    "name": "salt",
                    "type": "uint256"
                },
                {
                    "name": "conduitKey",
                    "type": "bytes32"
                },
                {
                    "name": "counter",
                    "type": "uint256"
                }
            ],
            "OfferItem": [
                {
                    "name": "itemType",
                    "type": "uint8"
                },
                {
                    "name": "token",
                    "type": "address"
                },
                {
                    "name": "identifierOrCriteria",
                    "type": "uint256"
                },
                {
                    "name": "startAmount",
                    "type": "uint256"
                },
                {
                    "name": "endAmount",
                    "type": "uint256"
                }
            ],
            "ConsiderationItem": [
                {
                    "name": "itemType",
                    "type": "uint8"
                },
                {
                    "name": "token",
                    "type": "address"
                },
                {
                    "name": "identifierOrCriteria",
                    "type": "uint256"
                },
                {
                    "name": "startAmount",
                    "type": "uint256"
                },
                {
                    "name": "endAmount",
                    "type": "uint256"
                },
                {
                    "name": "recipient",
                    "type": "address"
                }
            ]
        },
        "value": {
            "kind": "single-token",
            "offerer": "0xd6044091d0b41efb3402ca05ba4068f969fdd9e4",
            "zone": "0x0000000000000000000000000000000000000000",
            "offer": [
                {
                    "itemType": 1,
                    "token": "0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270",
                    "identifierOrCriteria": "0",
                    "startAmount": "1000000000000000",
                    "endAmount": "1000000000000000"
                }
            ],
            "consideration": [
                {
                    "itemType": 2,
                    "token": "0x362cc74e031091992cdf0e07be54804c7cce9240",
                    "identifierOrCriteria": "32",
                    "startAmount": "1",
                    "endAmount": "1",
                    "recipient": "0xd6044091d0b41efb3402ca05ba4068f969fdd9e4"
                }
            ],
            "orderType": 0,
            "startTime": 1691165262,
            "endTime": 1691424522,
            "zoneHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
            "salt": "0x07b88f641d4da48b00000000000000001fc57a14aea256b9eb70bf364ce57c64",
            "conduitKey": "0x0000007b02230091a7ed01230072f7006a004d60a8d4e71d599b8104250f0000",
            "counter": "0",
            "signature": "0x0000000000000000000000000000000000000000000000000000000000000000"
        },
        "primaryType": "OrderComponents"
    }

Posting the data

After the message is signed the second action is to submit the post body to the endpoint provided in the post data. You’ll also need to provide the signature that was generated from the sign data as a query parameter. If the request is successful we can mark the step item as complete locally.

The design pattern of this API is completely generic, allowing for automatic support of new types of liquidity without needing to update the app. This data can be fed directly into an Ethereum library such as viem, making it easy to sign and submit the exact data that is needed.

Transaction Step

A transaction that needs to be submitted on-chain. After the transaction is submitted onchain you can poll the step items check endpoint. The endpoint will return a status which when successful will return ‘success’. The step item can then be successfully marked as complete. Note that the transaction step item contains a chainId for which the transaction should be submitted on.

---

SDK Reference

To review the official way the SDK handles execution, please refer to the executeSteps file which implements executing steps detailed above.