Test your StableFX integration as a maker

This tutorial walks you through the steps to test your StableFX integration as a maker, covering successful trade creation, signature registration, and funding. For failure scenarios, see Magic numbers for testing StableFX.

Prerequisites

Before you begin, ensure that you have:

Generated a StableFX API key. See Generate a StableFX API key.
Enabled your sandbox account as a registered maker by contacting Circle Support
Obtained testnet USDC and EURC in a supported wallet on Arc
Installed cURL on your development machine

This guide provides API requests in cURL format, along with example responses. In all examples, replace ${YOUR_API_KEY} with your actual API key and any other placeholder values with the appropriate data for your test.

Part 1: Create a test trade

In sandbox, you create test trades by submitting a taker trade request using your API key. This gives you a trade to sign and fund in the subsequent parts of this tutorial.

1.1. Request a tradable quote

Request a quote for a trade from USDC to EURC using the create a quote endpoint. Set type to tradable to receive an executable quote. Include a recipientAddress for the wallet that receives EURC after the trade settles:

curl --request POST \
  --url https://api-sandbox.circle.com/v1/exchange/stablefx/quotes \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "currency": "USDC",
    "amount": "10"
  },
  "to": {
    "currency": "EURC"
  },
  "tenor": "instant",
  "type": "tradable",
  "recipientAddress": "0xYOUR_WALLET_ADDRESS"
}
'

Response The response includes the quote details and a typedData object containing the Permit2 EIP-712 typed data you must sign before creating the trade.

{
  "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "rate": 0.915,
  "from": {
    "currency": "USDC",
    "amount": "10"
  },
  "to": {
    "currency": "EURC",
    "amount": "9.15"
  },
  "createdAt": "2025-01-01T12:04:05Z",
  "expiresAt": "2025-01-01T12:04:35Z",
  "fee": {
    "currency": "USDC",
    "amount": "0.01"
  },
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 5042002,
      "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0x3600000000000000000000000000000000000000",
        "amount": 429000000
      },
      "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
      "nonce": 309585810,
      "deadline": 1770302983,
      "witness": {
        "consideration": {
          "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
          "base": "0x3600000000000000000000000000000000000000",
          "quote": "0x4200000000000000000000000000000000000000",
          "baseAmount": "10",
          "quoteAmount": "9.15",
          "maturity": 1716153600
        },
        "recipient": "0xYOUR_WALLET_ADDRESS",
        "fee": 80000
      }
    }
  }
}

1.2. Sign the typed data

Using a Permit2 compliant, EIP-712 compatible wallet or signing library, sign the typedData object returned in the quote response. Use the domain, types, primaryType, and message fields to construct the EIP-712 signature. After signing, you have a hex-encoded signature string (for example, 0x1234...).

1.3. Create the trade

Submit the quote acceptance using the create a trade endpoint. Provide the quote ID, your wallet address, the message from typedData.message, the signature from the previous step, and a randomly generated idempotency key in UUIDv4 format:

curl --request POST \
  --url https://api-sandbox.circle.com/v1/exchange/stablefx/trades \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "idempotencyKey": "${YOUR_IDEMPOTENCY_KEY}",
  "address": "0xYOUR_WALLET_ADDRESS",
  "message": {
    "permitted": {
      "token": "0x3600000000000000000000000000000000000000",
      "amount": 429000000
    },
    "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
    "nonce": 309585810,
    "deadline": 1770302983,
    "witness": {
      "consideration": {
        "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
        "base": "0x3600000000000000000000000000000000000000",
        "quote": "0x4200000000000000000000000000000000000000",
        "baseAmount": "10",
        "quoteAmount": "9.15",
        "maturity": 1716153600
      },
      "recipient": "0xYOUR_WALLET_ADDRESS",
      "fee": 80000
    }
  },
  "signature": "0xYOUR_SIGNATURE"
}
'

After the trade is submitted and confirmed, it appears in the maker trade list with the confirmed status.

Part 2: Query for trades

After the trade you created in Part 1 is confirmed, query for maker trades with the confirmed status using the get all trades endpoint. The following is an example request:

curl --request GET \
  --url https://api-sandbox.circle.com/v1/exchange/stablefx/trades?type=maker&status=confirmed \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \

Response

{
  "data": [
    {
      "id": "c2558cd1-98b5-4ccd-90b8-96891512af20",
      "contractTradeId": 42,
      "status": "confirmed",
      "rate": 0.915,
      "from": {
        "currency": "USDC",
        "amount": "10"
      },
      "to": {
        "currency": "EURC",
        "amount": "9.15"
      },
      "createDate": "2023-01-01T12:04:05Z",
      "updateDate": "2023-01-01T12:04:05Z",
      "quoteId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
    }
  ],
  "pagination": {
    "next": "",
    "previous": ""
  }
}

Part 3: Register your signature

Decide which trades to take from the maker side, and register your signature for those trades.

3.1. Get the typed data for the trade

Using the id field from the response in the previous step, get the typed data for the trade using the generate trade presign data endpoint. Include the required recipientAddress query parameter, which is the address of the recipient of the settlement tokens. The following is an example request:

curl --request GET \
  --url 'https://api-sandbox.circle.com/v1/exchange/stablefx/signatures/presign/c2558cd1-98b5-4ccd-90b8-96891512af20?recipientAddress=0xYOUR_RECIPIENT_ADDRESS' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

Response

{
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 5042002,
      "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
    },
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "TokenPermissions": [
        { "name": "token", "type": "address" },
        { "name": "amount", "type": "uint256" }
      ],
      "Consideration": [
        { "name": "quoteId", "type": "bytes32" },
        { "name": "base", "type": "address" },
        { "name": "quote", "type": "address" },
        { "name": "baseAmount", "type": "uint256" },
        { "name": "quoteAmount", "type": "uint256" },
        { "name": "maturity", "type": "uint256" }
      ],
      "TraderDetails": [
        { "name": "consideration", "type": "Consideration" },
        { "name": "fee", "type": "uint256" },
        { "name": "authorizer", "type": "address" }
      ],
      "PermitWitnessTransferFrom": [
        { "name": "permitted", "type": "TokenPermissions" },
        { "name": "spender", "type": "address" },
        { "name": "nonce", "type": "uint256" },
        { "name": "deadline", "type": "uint256" },
        { "name": "witness", "type": "TraderDetails" }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0x3600000000000000000000000000000000000000",
        "amount": 429000000
      },
      "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
      "nonce": 309585810,
      "deadline": 1770302983,
      "witness": {
        "consideration": {
          "quoteId": "0x00000000000000000000000000000000c4d1da72111e4d52bdbf2e74a2d803d5",
          "base": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
          "quote": "0x3600000000000000000000000000000000000000",
          "baseAmount": "915000000",
          "quoteAmount": "1000000000",
          "maturity": 1752148800
        },
        "fee": 80000,
        "authorizer": "0x0000000000000000000000000000000000000000"
      }
    }
  }
}

3.2. Sign the typed data

Using your wallet, sign the typed data returned from the previous step.

3.3. Submit the signed data

Submit the signed data to the submit a trade signature endpoint. The following example submits the signed data from the previous step:

curl --request POST \
  --url https://api-sandbox.circle.com/v1/exchange/stablefx/signatures \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tradeId": "c2558cd1-98b5-4ccd-90b8-96891512af20",
  "address": "0xYOUR_WALLET_ADDRESS",
  "details": {
    "permitted": {
      "token": "0x3600000000000000000000000000000000000000",
      "amount": 429000000
    },
    "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
    "nonce": 309585810,
    "deadline": 1770302983,
    "witness": {
      "consideration": {
        "quoteId": "0x00000000000000000000000000000000c4d1da72111e4d52bdbf2e74a2d803d5",
        "base": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
        "quote": "0x3600000000000000000000000000000000000000",
        "baseAmount": "915000000",
        "quoteAmount": "1000000000",
        "maturity": 1752148800
      },
      "fee": 80000,
      "authorizer": "0x0000000000000000000000000000000000000000"
    }
  },
  "signature": "0xsignature"
}
'

Part 4: Fund the taker side

Because you created the trade in Part 1 using your own API key, you are also the taker. You must fund the taker side of the trade before you can fund the maker side in Part 5.

4.1. Get the taker funding signature data

Call the generate funding presign data endpoint with "type": "taker" and the contractTradeId from the Part 2 response:

curl --request POST \
  --url https://api-sandbox.circle.com/v1/exchange/stablefx/signatures/funding/presign \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contractTradeIds": ["${stablefx_contract_trade_id}"],
  "type": "taker"
}
'

4.2. Sign the taker funding data

Using a Permit2 compliant, EIP-712 compatible wallet or signing library, sign the typedData object from the response.

4.3. Submit the taker funding

Submit the signed data to the fund trades endpoint with "type": "taker":

curl --request POST \
  --url https://api-sandbox.circle.com/v1/exchange/stablefx/fund \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "taker",
  "signature": "0xYOUR_SIGNATURE",
  "permit2": {
    "permitted": {
      "token": "0xTOKEN",
      "amount": "10"
    },
    "spender": "0xSPENDER",
    "nonce": 123456,
    "deadline": 1752149700,
    "witness": {
      "id": "${stablefx_contract_trade_id}"
    }
  }
}
'

If the signed data is accepted, the API returns a blank 200 response and the trade moves to the taker_funded status.

Part 5: Fund the maker side

Use the following steps to fund the maker side of the trade onchain.

5.1. Get trades that are ready for funding

Before you send funds onchain, you should confirm that the trade is ready for funding. To do this, call the get all trades endpoint. You should filter the response by the taker_funded status.

5.2. Get the funding signature data

To use the StableFX API to deliver the funds onchain, you must first sign the funding typed data with an EIP-712 signature. To get the data to sign, call the generate funding presign data endpoint. Your request must include the contract ID of the trade and the side of the trade that you are taking ("type": "maker"). The following is an example request:

curl --request POST \
  --url https://api-sandbox.circle.com/v1/exchange/stablefx/signatures/funding/presign \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
  {
  "contractTradeIds": ["${stablefx_contract_trade_id}"],
  "type": "maker"
}
'

Response

{
  "typedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 11155111,
      "verifyingContract": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE"
    },
    "types": {
      "EIP712Domain": [
        {
          "name": "name",
          "type": "string"
        },

        {
          "name": "chainId",
          "type": "uint256"
        },

        {
          "name": "verifyingContract",
          "type": "address"
        }
      ],
      "TokenPermissions": [
        {
          "name": "token",
          "type": "address"
        },

        {
          "name": "amount",
          "type": "uint256"
        }
      ],
      "SingleTradeWitness": [
        {
          "name": "id",
          "type": "uint256"
        }
      ],
      "PermitWitnessTransferFrom": [
        {
          "name": "permitted",
          "type": "TokenPermissions"
        },

        {
          "name": "spender",
          "type": "address"
        },

        {
          "name": "nonce",
          "type": "uint256"
        },

        {
          "name": "deadline",
          "type": "uint256"
        },

        {
          "name": "witness",
          "type": "SingleTradeWitness"
        }
      ]
    },
    "primaryType": "PermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0xTOKEN",
        "amount": "1000"
      },
      "spender": "0xffd21ca8F0876DaFAD7de09404E0c1f868bbf1AE",
      "nonce": "42",
      "deadline": "1735689600",
      "witness": {
        "id": "10"
      }
    }
  },
  "deliverables": [
    {
      "currency": "EURC",
      "amount": "915.00"
    }
  ],
  "receivables": [
    {
      "currency": "USDC",
      "amount": "1000.00"
    }
  ]
}

5.3. Fund the trade with the StableFX API

The StableFX API can handle the onchain transaction for you through the fund trades endpoint. You must submit the maker-specific funding data along with your signature.

curl --request POST \
  --url https://api-sandbox.circle.com/v1/exchange/stablefx/fund \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "maker",
  "signature": "0xsignature",
  "permit2": {
    "permitted": {
      "token": "0xTOKEN1",
      "amount": "9.15"
    },
    "spender": "0xTOKEN1",
    "nonce": "123456",
    "deadline": 1752149700,
    "witness": {
      "id": "123456"
    }
  }
}
'

If the signed data is accepted, the API returns a blank 200 response.

It’s not required to submit the funding transaction through the StableFX API. You can submit the transaction onchain using your own web3 provider or wallet by calling the appropriate maker contract methods directly.

Testing trade batches

Note that the query for trades endpoint returns multiple trades. This can be useful for testing a batch integration. If you are testing batching, you need to get the contractTradeId for each trade that you’d like to fund. You should complete part 3 for each trade that you’d like to fund. Once you have the array of IDs, and your signature is submitted for each trade, you can use the same fund trades endpoint to fund multiple trades by submitting the permit2 data for each trade along with the appropriate signatures.

Mint

StableFX

Digital Asset Accounts

End User Onboarding

Test your StableFX integration as a maker

Prerequisites

Part 1: Create a test trade

1.1. Request a tradable quote

1.2. Sign the typed data

1.3. Create the trade

Part 2: Query for trades

Part 3: Register your signature

3.1. Get the typed data for the trade

3.2. Sign the typed data

3.3. Submit the signed data

Part 4: Fund the taker side

4.1. Get the taker funding signature data

4.2. Sign the taker funding data

4.3. Submit the taker funding

Part 5: Fund the maker side

5.1. Get trades that are ready for funding

5.2. Get the funding signature data

5.3. Fund the trade with the StableFX API

Testing trade batches

​Prerequisites

​Part 1: Create a test trade

​1.1. Request a tradable quote

​1.2. Sign the typed data

​1.3. Create the trade

​Part 2: Query for trades

​Part 3: Register your signature

​3.1. Get the typed data for the trade

​3.2. Sign the typed data

​3.3. Submit the signed data

​Part 4: Fund the taker side

​4.1. Get the taker funding signature data

​4.2. Sign the taker funding data

​4.3. Submit the taker funding

​Part 5: Fund the maker side

​5.1. Get trades that are ready for funding

​5.2. Get the funding signature data

​5.3. Fund the trade with the StableFX API

​Testing trade batches

Prerequisites

Part 1: Create a test trade

1.1. Request a tradable quote

1.2. Sign the typed data

1.3. Create the trade

Part 2: Query for trades

Part 3: Register your signature

3.1. Get the typed data for the trade

3.2. Sign the typed data

3.3. Submit the signed data

Part 4: Fund the taker side

4.1. Get the taker funding signature data

4.2. Sign the taker funding data

4.3. Submit the taker funding

Part 5: Fund the maker side

5.1. Get trades that are ready for funding

5.2. Get the funding signature data

5.3. Fund the trade with the StableFX API

Testing trade batches