# Guides
You will find some practical examples of how to integrate with the API and the pool contracts.
# How to use clipper RFQ API?
Clipper's Formula Market Maker (FMM) is implemented similar to a typical Request For Quotes (RFQ) system. In an [RFQ architecture](/disclaimers-and-technical/integrating-with-clipper-rfq/introduction#supported-networks), you first ask our offchain server to quote a transaction price, specifying the buy and sell tokens and either a target input or output amount. You then have a short amount of time to accept that quote, and receive back a signed certificate from our offchain server. Then, you must pass that transaction and signed certificate to our onchain smart contracts to execute the swap.
Clipper supports a “send, then swap" modality and is designed to be as simple as possible to chain within a larger set of transactions, or to automate trading with bots.
{% hint style="warning" %}
It's essential to obtain the credentials in order to proceed with the guide for API usage. Please reach out to us to acquire the necessary credentials for API access, please refer to the [Authorization](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/overview) section to know details.
{% endhint %}
{% hint style="info" %}
You can see the supported networks [here](/disclaimers-and-technical/integrating-with-clipper-rfq/introduction#supported-networks)
{% endhint %}
1. Get exchange address and asset information.
```javascript
const fetch = require('node-fetch');
const chainId = 137; // You can use a different network. Look for our supported networks
const fieldset = 'offchain-data';
const authorizationHeader = 'YXBpLXVzZXI6dXNlci1wYXNz'; // This is a placeholder
const requestOptions = {
method: 'GET',
headers: {
'x-api-key': authorizationHeader,
'Content-Type': 'application/json'
}
};
const response = await fetch(`https://blade-api.sushi.com/rfq/v2/pool/${chainId}?fieldset=${fieldset}`, requestOptions);
const data = await response.json();
console.log(data);
```
The API response will look like the following (some fields omitted):
```javascript
{
"pool_type": "offchain",
"pools": [
{
"pool": {
"chain_id": 1,
"address": "0x655eDCE464CC797526600a462A8154650EEe4B77",
"num_assets": 4,
"k": 0.06,
"time_in_seconds": 60,
"default_time_in_seconds": 60,
"swaps_enabled": true
},
"assets": [
{
"name": "ETH",
"address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"price_in_usd": 2076.799,
"listing_weight": 79
},
{
"name": "USDC",
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"price_in_usd": 1,
"listing_weight": 188
},
{
"name": "USDT",
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"price_in_usd": 1,
"listing_weight": 305
},
{
"name": "DAI",
"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"price_in_usd": 1,
"listing_weight": 250
}
],
"pairs": [
{
"assets": [
"ETH",
"USDC"
],
"fee_in_basis_points": 9
},
{
"assets": [
"ETH",
"USDT"
],
"fee_in_basis_points": 9
},
{
"assets": [
"ETH",
"DAI"
],
"fee_in_basis_points": 8
},
{
"assets": [
"USDC",
"USDT"
],
"fee_in_basis_points": 5
},
{
"assets": [
"USDC",
"DAI"
],
"fee_in_basis_points": 5
},
{
"assets": [
"USDT",
"DAI"
],
"fee_in_basis_points": 5
}
]
}
]
}
```
> 💡 You can include the query param `time_in_seconds` to the GET call if you intend to get quotes for values other than the default\_time\_in\_seconds for a chain. As you lower the time you will see lower fees (and therefore better prices).
>
> 💡 You can include the `pool_address` query parameter; if it’s not provided, multiple pools can be returned per chain.
>
> 💡 To obtain more details about the endpoint, its parameters, and the response, please refer to the API Reference in the [pool](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/pool-v2) section.
{% hint style="warning" %}
You should estimate clipper prices using the offchain state information for better performance. Review the section [Estimate Clipper Prices](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/estimate-clipper-prices) to know more about it.
{% endhint %}
2. Request a quote
```javascript
const fetch = require('node-fetch');
const params = {
pool_address: '0x655eDCE464CC797526600a462A8154650EEe4B77', // Should be set to the appropriate pool address
output_asset_symbol: 'USDC',
input_asset_symbol: 'DAI',
input_amount: '2000000000000000000', // XOR: output_amount: '2000000000000000000'
time_in_seconds: 30. // A good suggestion for Polygon is 30 seconds. As this value increases, the quote will get worse for the user.
};
const queryString = new URLSearchParams(params).toString();
const authorizationHeader = 'YXBpLXVzZXI6dXNlci1wYXNz'; // This is a placeholder
const requestOptions = {
method: 'GET',
headers: {
'x-api-key': authorizationHeader,
'Content-Type': 'application/json'
},
};
const response = await fetch('https://blade-api.sushi.com/rfq/v2/quote/{CHAIN_ID}?${queryString}');
const data = await response.json();
console.log(data);
```
{% hint style="warning" %} `input_asset_symbol` and `output_asset_symbol` should correspond to the asset name returned from the `/rfq/v2/pool` call in the step 1.
{% endhint %}
The API response will look like the following (some fields omitted):
```json
{
"id": "320d255f-5864-4245-927c-fa4951121ee8",
"must_accept_by": "2023-09-01 18:10:36.629117+00:00",
"good_until": 1693591896,
"chain_id": 137,
"input_amount": "2000000000000000000",
"output_amount": "2000000",
"input_value_in_usd": 2.0,
"output_value_in_usd": 2.0,
"rate": 1.0,
"input_asset_address": "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
"output_asset_address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
}
```
{% hint style="warning" %}
For assets like `ETH` and `MATIC` Clipper exchange uses the wrapped version of these assets, a distinction made clear and unambiguous by the inclusion of the contract addresses in the response.
{% endhint %}
> 💡 To obtain more details about the endpoint, its parameters, and the response, please refer to the API Reference in the [quote](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/quote-v2) section.
3. Sign the quote
{% hint style="warning" %}
Only members of the Clipper Community and DEX aggregator partners can get their quotes signed. If you're building a DEX aggregator, please reach out to the team on [Discord](https://discord.gg/FYwjZBmQ) for access (MNDA required).
{% endhint %}
{% hint style="warning" %}
Our quotes are firm. If a signed order make it onchain by the `good_until` time it will generally be honored as explicitly written. Note that, on some chains, if other orders frontrun the signed quote it may be rejected - this is a security precaution to prevent sybil attacks.
{% endhint %}
```javascript
const fetch = require('node-fetch');
const params = {
quote_id: "590d7956-c7cc-45da-83ed-23f6901f74e9", // id we get get in first step
destination_address: "0x5901920A7b8cb1Bba39220FAC138Ffb3800dD212", // it will receive the output token
sender_address: "0x5901920A7b8cb1Bba39220FAC138Ffb3800dD212". // Optional: it is for DEX aggregator partners that are using their own smart contract
};
const authorizationHeader = 'YXBpLXVzZXI6dXNlci1wYXNz'; // This is a placeholder
const requestOptions = {
method: 'POST',
headers: {
'x-api-key': authorizationHeader,
'Content-Type': 'application/json'
},
body: JSON.stringify(params)
};
const response = await fetch('https://blade-api.sushi.com/rfq/sign', requestOptions);
const data = await response.json();
console.log(data);
```
The API response will look like the following:
```json
{
"chain_id": 137,
"input_asset_address": "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
"output_asset_address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
"input_amount": "2000000000000000000",
"output_amount": "2000000",
"good_until": "627710173538668076417607179014705162363943960351250641945575434764",
"destination_address": "0xab83Af831dfb4028EBFd3fFA74A828a4d5DCaAC5",
"signature": {
"v": 28,
"r": "0x8a866d67003c32bf9b4bd40f6abf1fe939a288ad2199f967c108d4e73ecb6916",
"s": "0x4c9b1219a35139c5f7ce58452fb3d3c8fdff27c7dd3af055fbbdfd30ef0a0a20"
},
"clipper_exchange_address": "0x6Bfce69d1Df30FD2B2C8e478EDEC9dAa643Ae3B8"
}
```
{% hint style="info" %}
If you want to get the bytes representation of the swap to be sent directly to the pool contract you can review our [calldata swap feature](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/sign#with-calldata)
{% endhint %}
> 💡 To obtain more details about the endpoint, its parameters, and the response, please refer to the API Reference in the [sign](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/sign) section
4. Send the transaction
**Using ether.js**
{% file src="/files/aQLi0qsgSmlfob5AeYIa" %}
```javascript
import ethers from "ethers";
import exchangeAbi from "./exchangeAbi.json";
async function executeSwap(signResponse) {
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
const exchangeContract = new ethers.Contract(
signResponse.clipper_exchange_address,
exchangeAbi,
provider
);
// Any 32 bytes identifier
const auxData = "0x00000000000000000000000000000000000000000000000000";
const result = await exchangeContract.swap(
signResponse.input_asset_address,
signResponse.output_asset_address,
signResponse.input_amount,
signResponse.outputAmount,
signRespose.good_until,
signResponse.destination_address,
[signResponse.signature.v, signResponse.signature.r, signResponse.signature.s],
auxData
)
```
> 💡 You can review the guide [Interacting with the Clipper Exchange](/disclaimers-and-technical/integrating-with-clipper-rfq) to know more ways of interact with Clipper. You can also review code examples in the section [Integration Examples](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples)
{% hint style="info" %}
You can find a complete swap flow example [here](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/complete-swap-flow)
{% endhint %}
# Estimate Clipper Prices
In order to assist in integrating Clipper with DEX Aggregators & Resolvers, offchain state information that is used to calculate Clipper prices is made available in a read-only endpoint that can be queried frequently. This state information can then be used to accurately estimate Clipper price quotes when combined with onchain state information (pulled and maintained by the aggregators themselves).
{% hint style="success" %}
You can view code to see how to implement it, in our section [Complete Swap Flow](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/complete-swap-flow)
{% endhint %}
## 1. Get pool data
Make a GET call to `https://blade-api.sushi.com/rfq/v2/pool/{CHAIN_ID}?fieldset=offchain-data`
This endpoint returns a JSON blob that holds Clipper's offchain state information. Note that this response is modified from the standard response to the endpoint by removing *any* calls to the onchain contracts for response speed.
The API response will look like the following:
```json
{
"pool_type": "offchain",
"pools": [
{
"pool": {
"chain_id": 1,
"address": "0x655eDCE464CC797526600a462A8154650EEe4B77",
"num_assets": 4,
"k": 0.06,
"time_in_seconds": 60,
"default_time_in_seconds": 60,
"swaps_enabled": true
},
"assets": [
{
"name": "ETH",
"address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"price_in_usd": 2076.799,
"listing_weight": 79
},
{
"name": "USDC",
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"price_in_usd": 1,
"listing_weight": 188
},
{
"name": "USDT",
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"price_in_usd": 1,
"listing_weight": 305
},
{
"name": "DAI",
"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"price_in_usd": 1,
"listing_weight": 250
}
],
"pairs": [
{
"assets": [
"ETH",
"USDC"
],
"fee_in_basis_points": 9
},
{
"assets": [
"ETH",
"USDT"
],
"fee_in_basis_points": 9
},
{
"assets": [
"ETH",
"DAI"
],
"fee_in_basis_points": 8
},
{
"assets": [
"USDC",
"USDT"
],
"fee_in_basis_points": 5
},
{
"assets": [
"USDC",
"DAI"
],
"fee_in_basis_points": 5
},
{
"assets": [
"USDT",
"DAI"
],
"fee_in_basis_points": 5
}
]
}
]
}
```
> 💡 To obtain more details about the endpoint, its parameters, and the response, please refer to the API Reference in the [pool](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/pool-v2) section.
## 2. Estimate Clipper Prices using On- and Off- chain Data
1. Convert (using `decimals`) the onchain balances of the Clipper Pool - the quantity vector `q` - into human-readable terms (i.e., a balance of 100 ETH instead of 1e20 ETH.
2. Calculate the fee-adjustment multiplier for the swapping pair `M = (10000-fee_in_basis_points)/10000` (10,000 = number of basis points in 100%).
3. Solve for a swap from asset X to asset Y through root-finding or a closed form solution. Let `pX`, `qX`, `wX`, and `inX` represent the current price, quantity, listing weight, and swap input of asset X, and similarly `pY`, `qY`, `wY`, and `outY` represent the current price, quantity, listing weight, and swap output of asset Y. Exactly one of `inX` or `outY` should be unknown. That unknown quantity is then found by solving an indifference pricing equation relating current utility from the assets X and Y to the utility from those assets after the swap:
$$
\frac{(pX \cdot {qX})^{1-k}}{{wX}^k} + \frac{(pY \cdot {qY})^{1-k}}{{wY}^k} \ = \ \frac{(pX \cdot ({qX + M\cdot{inX}}))^{1-k}}{{wX}^k} + \frac{(pY \cdot ({qY}-{outY}))^{1-k}}{{wY}^k}
$$
Checks should be done to ensure an intermediate solution to this equation before attempting to solve:
* If `outY` is specified:
* `outY` should be no larger than `qY`.
* The LHS of the formula (current utility) should be larger than the RHS (utility after swap) evaluated at `inX=0`
* The LHS of the formula should be smaller than the RHS when evaluated at very large `inX`
* If `inX` is specified:
* The LHS of the formula (current utility) should not be smaller than the RHS (utility after swap) evaluated at `outY=qY`
* The LHS of the formula should be smaller than the RHS when evaluated at `outY=0`
### Closed Formed Solution
{% hint style="info" %}
In practice, this is the preferred way to solve the equation because it tends to be faster and more consistent. It is more numerically unstable in the worst case since it requires 1/(1-k) exponentiation, but in practice Clipper’s k tends to be small, making 1/(1-k) ≈ 1
{% endhint %}
* If `inX` is specified, then:
$$
{outY} = {qY}-\frac{\left\[\left(\frac{(pX \cdot {qX})^{1-k}}{{wX}^k} + \frac{(pY \cdot {qY})^{1-k}}{{wY}^k} - \frac{(pX \cdot ({qX + M\cdot{inX}}))^{1-k}}{{wX}^k} \right)\cdot wY^k\right]^{\frac{1}{1-k}}}{pY}
$$
* If `outY` is specified, then:
$$
{inX} = \frac{1}{M}\cdot\left\[\frac{\left\[\left(\frac{(pX \cdot {qX})^{1-k}}{{wX}^k} + \frac{(pY \cdot {qY})^{1-k}}{{wY}^k} - \frac{(pY \cdot ({qY}-{outY}))^{1-k}}{{wY}^k}\right)\cdot {wX}^k\right]^{\frac{1}{1-k}}}{pX}-{qX}\right]
$$
### Root Finding
A good initial guess (for a Newton method solver) for `inX` or `outY` is the FMV of the other value.
* If `inX` is specified, then try:
$$
outY \approx M \cdot inX \cdot pX/pY
$$
* If `outY` is specified, try:
$$
inX \approx (outY \cdot pY) / (M\*pX)
$$
In practice, the actual Clipper price quote will also depend on the amount of time the quote is alive for, as well as the most recent price update. These should result in only small changes from the estimated quotes produced by this process.
### Final Check: Output Value No Larger than Input Value
Finally, we enforce that **the FMV (according to *****our*** **`price_in_usd`**** values) of the contributed input is at least the FMV of the output.** This constraint will typically only bind when the Clipper pool is very far off target allocations, since in general fees plus slippage will be sufficient to ensure the condition.
If `inX` was specified and `outY` has been calculated to solve the formula, then as a final check:
$$
outY \equiv \min\left\[outY, (inX \cdot pX) / {pY} \right]
$$
If `outY` is specified and `inX` has been calculated to solve the formula, then as a final check:
$$
inX \equiv \max\left\[inX, (outY \cdot pY) / {pX} \right]
$$
{% hint style="warning" %}
Note that these tests are done *without regard to fees*.
{% endhint %}
# Interacting with the Clipper Exchange contracts
There are several different external functions for interacting with the Clipper exchange onchain, depending on your use case. In all of these functions, Signature is a struct defined by:
```solidity
struct Signature {
uint8 v;
bytes32 r;
bytes32 s;
}
```
### **Avoiding Transaction Errors with the Clipper API**
Clipper is designed to be used sequentially, so that it trades only one active and outstanding signed quote at a time. Once you execute a swap with Clipper all of your existing quotes from before that swap are "dirty" and may no longer be honored onchain.
If you try to sign multiple quotes, or use the same signed quote multiple times, the transactions are highly likely to revert on the blockchain, costing you gas. To avoid this, always call for fresh quotes after you transact with Clipper.
### **Swapping Tokens for Tokens**
`function swap(address inputToken, address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;`
`function transmitAndSwap(address inputToken, address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;`
Observe that the signed quote has all of these values to use, except for `auxiliaryData` which can be set to any string and is used for identification purposes in the event logs.
The difference between `swap` and `transmitAndSwap` is that `transmitAndSwap` starts by transferring `inputAmount` of the `inputToken` from `msg.sender` to the exchange, while `swap` assumes that the appropriate amount of the input token has already been transmitted. Which function you should use depends on if and how you are connecting the Clipper swap to other operations.
{% hint style="info" %}
See the complete example [here](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples#complete-swap-flow)
{% endhint %}
### Handling Native Currency
On each chain a native currency has special privileges and abilities and is often not **ERC20** compatible. For instance, **MATIC** is the native currency on Polygon. Unlike the Clipper implementation on Ethereum mainnet, Clipper's RFQ architecture only uses **ERC20** tokens, meaning that these native currencies must be wrapped before exchange with Clipper, and that Clipper can only return the wrapped version of these assets from the exchange.
However, for convenience, we provide two sets of functions for handling native currency in a direct fashion. For these swaps, you must get a signature for a transaction to or from the wrapped version of the native currency, as this is what will actually be exchanged.
For swaps of tokens to native currency (example: **DAI** to **MATIC** on **Polygon**), use:
`function sellTokenForEth(address inputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;`
`function transmitAndSellTokenForEth(address inputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;`
As with token-to-token swaps, the difference between these functions is that the first assumes that at least `inputAmount` of `inputToken` has already been sent, while the second pulls that input token directly from `msg.sender`. Observe further that:
The `outputToken` argument is not present (since it will be native currency)
These functions refer to the native currency as Eth regardless of chain
For swaps of native currency to tokens (example: **MATIC** to **USDC** on **Polygon**), use:
`function sellEthForToken(address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external payable;`
This function can operate either by attaching the native currency to the call as msg.value or by transferring that native currency to the exchange contract prior to the function call.
{% hint style="info" %}
See the an example [here](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/swap-native-token-shorttail) and [here](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/swap-shorttail-native-token)
{% endhint %}
### **Reduced calldata API**
On L2s like Optimism, Clipper's exchange contracts include two special functions that operate with reduced calldata in order to lower transaction costs. These functions are:
`function packedTransmitAndSwap(uint256 packedInput, uint256 packedOutput, uint256 packedGoodUntil, bytes32 auxData, bytes32 r, bytes32 vs) external payable;`
`function packedSwap(uint256 packedInput, uint256 packedOutput, uint256 packedGoodUntil, bytes32 auxData, bytes32 r, bytes32 vs) external payable;`
Similar to the other Clipper functions, use `packedTransmitAndSwap` to transmit the token from `msg.sender` and use `packedSwap` if tokens have already been transmitted.
### Handling Native Currency in the L2 API
Indicate native currency (e.g., ETH on Optimism) should be the input or output by setting the contract address to address(0).
#### *Packed Format Values*
The *packed* format is a way of compressing an integer amount and a contract address into a single `uint256` value. The packed format puts the address as the (first, lowest order) 160 bits (= 40 hex values = 20 bytes) and the amount as the (second, highest order) 96 bits (= 24 hex values = 12 bytes). To created a *packed* value, leftshift the integer amount by 160 bits and add it to the binary representation of the contract address. The four packed arguments into this function, and the values they encode, are:
`packedInput`: input amount and contract address
`auxData` - this is a `bytes32` value that is a packed representation of an identifying string, and the `destination_address` (lowest order bytes). The identifying string is emitted as part of `Swapped` event and allows us to attribute trade sourced correctly.
`packedOutput`: output amount and contract address
`packedGoodUntil`: Simply use the `good_until` value received from the server - it is already a packed representation of state.
#### *Short Signatures*
These functions use [the EIP 2098 "short signature" representation](https://eips.ethereum.org/EIPS/eip-2098) for the signature returned from the Clipper Exchange server. Source code to convert from the *v, r, s* signature value to the *r, vs* short signature is available on the EIP.
### Intermediate Contract Whitelisting
Clipper limits the number of signed quotes per day for each `destination_address`. If you make use of an intermediate or routing contract, please let us know the address you intend to use for that and we can whitelist the address to remove its daily signing limits.
# Integration Examples
## Complete swap flow
If you want to see a complete flow to make a swap you can review this [code](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/complete-swap-flow). In this example you can see the different steps.
1. Get pool data
2. Estimate Clipper Prices
3. Create a quote
4. Sign a quote
5. Execute a transaction
## Swaps
There are three kinds of assets:
1. **Shorttail**: Assets on Clipper Pool
2. **Longtail**: Assets not on Clipper Pool but can be traded through coves.
3. **ClipperLP:** Underlying token representing fraction of clipper pool.
Given those three assets, there may be the following Swap combinations:
#### Core pool Swaps
[Native token → Shorttail](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/swap-native-token-shorttail)
[Shorttail → Native token](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/swap-shorttail-native-token)
[Shorttail → Shorttail](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/swap-shorttail-shorttail)
# Swap Native token → Shorttail
E.g: 0.01 ETH → USDC on Ethereum mainnet (Chain 1), specifying selling amount.
{% file src="/files/aQLi0qsgSmlfob5AeYIa" %}
ABI used in the example
{% endfile %}
```javascript
const fetch = require('node-fetch');
import ethers from "ethers";
import exchangeAbi from "./exchangeAbi.json";
// Get a quote
async function getQuote() {
const quotePayload = {
"pool_address": "0x655eDCE464CC797526600a462A8154650EEe4B77"
"output_asset_symbol": "USDC",
"input_asset_symbol": "ETH",
"time_in_seconds": 60,
"input_amount": "10000000000000000"
};
const queryString = new URLSearchParams(quotePayload).toString();
const requestOptions = {
method: 'GET',
headers: {
'x-api-key': 'YXBpLXVzZXI6dXNlci1wYXNz', // This is a placeholder
'Content-Type': 'application/json'
}
};
const response = await fetch(`https://blade-api.sushi.com/rfq/v2/quote/1?${queryString}`, requestOptions);
const quote = await response.json();
return quote;
}
// Sign the quote
async function signQuote(quoteId) {
const signPayload = {
"quote_id": quoteId,
"destination_address": "0x0000000000000000000000000000000000000000"
};
const requestOptions = {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(signPayload)
};
const response = await fetch('https://blade-api.sushi.com/rfq/sign', requestOptions);
const signResponse = await response.json();
return signResponse;
}
// Execute transaction
async function executeSwap(signResponse) {
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
const exchangeContract = new ethers.Contract(
signResponse.clipper_exchange_address,
exchangeAbi,
provider
);
const auxData = "0x00000000000000000000000000000000000000000000000000";
const result = await exchangeContract.sellEthForToken(
signResponse.output_asset_address,
signResponse.input_amount,
signResponse.output_amount,
signResponse.good_until,
signResponse.destination_address,
[
signResponse.signature.v,
signResponse.signature.r,
signResponse.signature.s,
],
auxData,
{
value: signResponse.input_amount,
}
);
}
async function main() {
// 1. Get a quote
const quote = await getQuote();
console.log("Quote:", quote);
// 2. Sign a quote
const signResponse = await signQuote(quote.id);
console.log("Sign Response:", signResponse);
// 3. Execute transaction
await executeSwap(signResponse);
console.log("Swap executed successfully.");
}
```
# Swap Shorttail → Native token
E.g: OP → 0.01 ETH on Optimism (Chain 10)
{% file src="/files/II7qG5dv1PQnCMROInAV" %}
ABI used in the example
{% endfile %}
{% hint style="info" %}
Since this is a L2 (optimism) example, we use `packed` form values, as explained [here](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/interacting-with-the-clipper-exchange-contracts#packed-format-values). In this case, we need to call the `packedTransmitAndSwap` method from clipper’s smart contract which has the following interface:
`function packedTransmitAndSwap(uint256 packedInput, uint256 packedOutput, uint256 packedGoodUntil, bytes32 auxData, bytes32 r, bytes32 vs)`
{% endhint %}
```javascript
const fetch = require('node-fetch');
import ethers from "ethers";
import packedExchangeAbi from "./packedExchangeAbi.json";
import { hexZeroPad } from 'ethers/lib/utils';
// Get a quote
async function getQuote() {
const quotePayload = {
"pool_address": "0x663fA8731045765067e2B5b6acB19BE2ce974C7f",
"output_asset_symbol": "ETH",
"input_asset_symbol": "OP",
"time_in_seconds": 60,
"output_amount": "10000000000000000"
};
const queryString = new URLSearchParams(quotePayload).toString();
const requestOptions = {
method: 'GET',
headers: {
'x-api-key': 'YXBpLXVzZXI6dXNlci1wYXNz', // This is a placeholderer,
'Content-Type': 'application/json'
}
};
const response = await fetch(`https://blade-api.sushi.com/rfq/v2/quote/10?${queryString}`);
const quote = await response.json();
return quote;
}
// Sign the quote
async function signQuote(quoteId) {
const signPayload = {
"quote_id": quoteId,
"destination_address": "0xab83Af831dfb4028EBFd3fFA74A828a4d5DCaAC5"
};
const requestOptions = {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(signPayload)
};
const response = await fetch('https://blade-api.sushi.com/rfq/sign', requestOptions);
const signResponse = await response.json();
return signResponse;
}
// Execute transaction
async function executeSwap(signResponse) {
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
const clipperPackedContract = new ethers.Contract(
signResponse.clipper_exchange_address,
packedExchangeAbi,
provider
);
const auxData = "0x00000000000000000000000000000000000000000000000000";
const packedInput = packAddressAndAmount(signResponse.input_amount, signResponse.input_asset_address);
const packedOutput = packAddressAndAmount(signResponse.output_amount, signResponse.output_asset_address);
const packedGoodUntil = signResponse.good_until;
const packedData = packAddressAndAmount(auxData, signResponse.destination_address);
const r = byte32(signResponse.signature.r);
const vs = byte32(shortenSignature(signResponse.signature.s, signResponse.signature.v));
const result = await clipperPackedContract.packedTransmitAndSwap(
packedInput, packedOutput, packedGoodUntil, auxData, r, vs
);
}
// In order to calculate the packed values, we can use the following methods
function packAddressAndAmount(amount, address) {
const addressBn = BigInt(address);
const amountBn = BigInt(amount);
return (amountBn << 160n) + addressBn;
}
// Converts the value to 32 bytes and fills the rest with leading zeroes.
function byte32(value) {
return hexZeroPad(value.toString(16), 32);
}
function shortenSignature(s, v) {
const parity = BigInt(v - 27);
const shiftedParity = parity << 255n;
return s + shiftedParity.toString(16);
}
// Main function
async function main() {
// 1. Get a quotey
const quote = await getQuote();
console.log("Quote:", quote);
// 2. Sign a quote
const signResponse = await signQuote(quote.id);
console.log("Sign Response:", signResponse);
// 3. Execute transaction
await executeSwap(signResponse);
console.log("Swap executed successfully.");
}
```
# Swap Shorttail → Shorttail
E.g: 2 DAI -> USDC on Polygon (Chain 137)
{% file src="/files/aQLi0qsgSmlfob5AeYIa" %}
ABI used in the example
{% endfile %}
```javascript
const fetch = require('node-fetch');
import ethers from "ethers";
import exchangeAbi from "./exchangeAbi.json";
async function getQuote() {
const quotePayload = {
"pool_address": "0x6Bfce69d1Df30FD2B2C8e478EDEC9dAa643Ae3B8",
"output_asset_symbol": "USDC",
"input_asset_symbol": "DAI",
"time_in_seconds": 60,
"input_amount": "2000000000000000000"
};
const queryString = new URLSearchParams(quotePayload).toString();
const requestOptions = {
method: 'GET',
headers: {
'x-api-key': 'YXBpLXVzZXI6dXNlci1wYXNz', // This is a placeholder
'Content-Type': 'application/json'
}
};
const response = await fetch(`https://blade-api.sushi.com/rfq/v2/quote/137?${queryString}`);
const quote = await response.json();
return quote;
}
async function signQuote(quote) {
const signPayload = {
"quote_id": quote.id,
"destination_address": "0xab83Af831dfb4028EBFd3fFA74A828a4d5DCaAC5"
};
const requestOptions = {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(signPayload)
};
const response = await fetch('https://blade-api.sushi.com/rfq/sign', requestOptions);
const signResponse = await response.json();
return signResponse;
}
async function executeSwap(signResponse) {
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
const exchangeContract = new ethers.Contract(
signResponse.clipper_exchange_address,
exchangeAbi,
provider
);
const auxData = "0x00000000000000000000000000000000000000000000000000";
const result = await exchangeContract.transmitAndSwap(
signResponse.input_asset_address,
signResponse.output_asset_address,
signResponse.input_amount,
signResponse.output_amount,
signResponse.good_until,
signResponse.destination_address,
[signResponse.signature.v, signResponse.signature.r, signResponse.signature.s],
auxData
);
}
async function main() {
// 1. Get quote
const quote = await getQuote();
console.log("Quote:", quote);
// 2. Sign the quote
const signResponse = await signQuote(quote);
console.log("Sign Response:", signResponse);
// 3. Execute transaction
await executeSwap(signResponse);
console.log("Swap executed successfully.");
}
```
# Complete Swap Flow
We’ve created some demonstration integration code in NodeJS to show how you can replicate Clipper quotes locally and send the transaction using Clipper RFQ API. The code has demonstration solvers for both the closed form and root finding modalities.
Add `package.json` file with this code:
```json
{
"name": "clipper",
"version": "1.0.0",
"main": "main.js",
"license": "MIT",
"dependencies": {
"bignumber.js": "^9.0.2",
"node-fetch": "^3.2.0",
"root-finding": "^1.0.2",
"web3": "^1.7.0"
},
"type": "module"
}
```
Add `main.js` file with this code
```javascript
import fetch from 'node-fetch'
import BN from 'bignumber.js'
import nr from 'root-finding'
import Web3 from 'web3'
import fs from 'fs'
import ethers from "ethers";
import exchangeAbi from "./exchangeAbi.json";
const nodeUrl = process.env.NODE_URL
const rawdata = fs.readFileSync('ERC20.abi.json');
const ERC20ABI = JSON.parse(rawdata);
const authorizationHeader = 'YXBpLXVzZXI6dXNlci1wYXNz'; // This is a placeholder
const web3 = new Web3(nodeUrl)
async function main() {
// 1. GET POOL INFO AND ESTIMATE CLIPPER PRICES
const poolAddress = '0x6Bfce69d1Df30FD2B2C8e478EDEC9dAa643Ae3B8'
const data = await fetch(`https://blade-api.sushi.com/rfq/v2/pool/137?fieldset=offchain-data&pool_address=${pool_address}`, {
method: 'GET',
headers: {'x-api-key': authorizationHeader}
}).then((x) => x.json());
const prices = data.pools[0]
const asset_one = 'MATIC'
const asset_two = 'USDC'
const decimalsX = 18
const decimalsY = 6
const humanInX = 10000
let fee_in_basis_points = 0
for (const pair of prices.pairs) {
if(((pair.assets[0] === asset_one) && (pair.assets[1] === asset_two)) ||
((pair.assets[1] === asset_one) && (pair.assets[0] === asset_two))){
fee_in_basis_points = pair.fee_in_basis_points
break
}
}
const assetOneObj = prices.assets.find((x) => x.name === asset_one)
const assetTwoObj = prices.assets.find((x) => x.name === asset_two)
const assetOneContract = new web3.eth.Contract(ERC20ABI, assetOneObj.address)
const assetTwoContract = new web3.eth.Contract(ERC20ABI, assetTwoObj.address)
const assetOneBalance = await assetOneContract.methods.balanceOf(poolAddress).call()
const assetTwoBalance = await assetTwoContract.methods.balanceOf(poolAddress).call()
const M = (10000-fee_in_basis_points)/10000
const scaledDecimalsX = new BN(10).exponentiatedBy(decimalsX)
const scaledDecimalsY = new BN(10).exponentiatedBy(decimalsY)
const adjustedInX = humanInX*M
const inX = new BN(humanInX).multipliedBy(scaledDecimalsX)
// Pull in additional onchain state. This is from a snapshot of USDC and USDT, respectively.
const qX = new BN(assetOneBalance).dividedBy(scaledDecimalsX).toNumber()
const qY = new BN(assetTwoBalance).dividedBy(scaledDecimalsY).toNumber()
// Pull additional offchain state
const k = prices.pool.k
// format variables according to formula
const pX = assetOneObj.price_in_usd
const wX = assetOneObj.listing_weight
const pY = assetTwoObj.price_in_usd
const wY = assetTwoObj.listing_weight
const initialGuess = (adjustedInX*pX)/pY
const initialUtility = Math.pow(pX*qX, 1-k)/Math.pow(wX, k) + Math.pow(pY*qY, 1-k)/Math.pow(wY, k)
const newXUtility = Math.pow(pX*(qX+adjustedInX), 1-k)/Math.pow(wX, k)
let outY;
// CLOSED FORM SOLUTION
const outYClosedForm = qY-Math.pow((initialUtility - newXUtility)*Math.pow(wY,k), (1/(1-k)))/pY
// ROOT FINDING SOLUTION
function newYUtility(outY) {
return Math.pow(pY*(qY-outY), 1-k)/Math.pow(wY, k)
}
function zeroMe(outY) {
return initialUtility - newXUtility - newYUtility(outY)
}
// nr.newtonRaphson(guess, increment, iteration, eps, f);
// These increment, iteration, and eps values may need to be changed
const outYRootFinding = nr.newtonRaphson(initialGuess, 1e-6, 50, 1e-8, zeroMe)
console.log('Closed Form: ', outYClosedForm);
console.log('Root Finding: ', outYRootFinding);
outY = outYClosedForm;
// Adjust for FMV restriction, input >= output (without respect to fees!)
outY = Math.min(outY, (humanInX*pX)/pY).toFixed(decimalsY)
// 2. CREATE A QUOTE
const quotePayload = {
"input_asset_symbol": asset_one,
"output_asset_symbol": asset_two,
"pool_address": "0x6Bfce69d1Df30FD2B2C8e478EDEC9dAa643Ae3B8",
"input_amount": inX.toFixed(),
"time_in_seconds": prices.pool.default_time_in_seconds
}
const queryString = new URLSearchParams(quotePayload).toString();
const quote = await fetch(`https://blade-api.sushi.com/rfq/v2/quote/137?${queryString}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json',
'x-api-key': authorizationHeader
}
})
.then((x) => x.json())
console.log({
fromFormula: outY,
fromQuote: new BN(quote.output_amount).dividedBy(scaledDecimalsY).toFixed(decimalsY)
})
// 3. SIGN THE QUOTE
const sign = await fetch('https://blade-api.sushi.com/rfq/sign', {
method: 'POST',
body: JSON.stringify({
quote_id: quote.id, // Use the quote_id from the previous /quote call
destination_address: "0x5901920A7b8cb1Bba39220FAC138Ffb3800dD212",
sender_address: "0x5901920A7b8cb1Bba39220FAC138Ffb3800dD212", // Optional: it is for DEX aggregator partners that are using their own smart contract
}),
headers: {
'Content-Type': 'application/json',
'x-api-key': authorizationHeader
}
}).then((x) => x.json());
// 4. SEND THE TRANSACTION
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
const exchangeContract = new ethers.Contract(
sign.clipper_exchange_address,
exchangeAbi,
provider
);
// Any 32 bytes identifier
const auxData = "0x00000000000000000000000000000000000000000000000000";
const result = await exchangeContract.swap(
sign.input_asset_address,
sign.output_asset_address,
sign.input_amount,
sign.output_amount,
sign.good_until,
sign.destination_address,
[sign.signature.v, sign.signature.r, sign.signature.s],
auxData
);
console.log("Swap Result:", result);
}
main()
```
Add `ERC20.abi.json`
{% file src="/files/JKitp2vpnhjSQ44EjmrN" %}
Add `exchangeAbi.json`
{% file src="/files/aQLi0qsgSmlfob5AeYIa" %}
Install packages
```bash
npm install
```
Run the code
```bash
NODE_URL="https://polygon-rpc.com/" node main.js
```
### Extra notes of the code
The code compares the output from a root-finding implementation in our code (”fromFormula”) to the output from the Clipper servers (”fromQuote”) on Polygon. Note that sometimes these values may diverge slightly because of Polygon block updates.
You can change the tokens and amounts by changing these values in `main.js`
```javascript
const asset_one = 'USDT'
const asset_two = 'USDC'
const decimalsX = 6
const decimalsY = 6
const humanInX = 100
```
The asset\_ values are token names, `decimals` values should be the `decimals` for the first and second tokens, respectively, and `humanInX` should be the sold amount of `asset_one` in human terms (i.e., 1000 USDC ≈ $1,000 rather than “1000000000” USDC).
# Blade Pool LP withdraw process
### unlockDeposit() → returns (uint256 poolTokens)
Unlocks LP tokens after the vesting period ends.
**Process Overview:**
* Verify if the caller has a vested deposit.
* Ensure the lock period has ended.
* Transfer the LP tokens to the caller.
* Remove the vesting record.
{% hint style="info" %}
Does not withdraw assets. Only gives access to LP tokens. LP tokens must have been created using a vesting deposit.
{% endhint %}
{% hint style="danger" %}
**Revert Conditions:**
No active vesting deposit exists.
Vesting period has not passed.
{% endhint %}
### burnToWithdraw(uint256 amount)
Burns the caller’s LP tokens and withdraws their proportional share of all pool assets.
**Process Overview:**
* Calculates the fraction of the pool being burned.
* Burns LP tokens from the caller.
* Transfers a proportional amount of each asset in the pool.
* Emits a Withdrawn event.
{% hint style="info" %}
No vesting needed. Useful for instant withdrawals. Only works if the caller already holds LP tokens.
{% endhint %}
{% hint style="danger" %}
**Revert conditions:**
Caller doesn’t have enough LP tokens.
Asset transfer fails.
{% endhint %}
# API Reference
# API v2
# Overview
## Endpoints
Learn more about the different endpoints of Swap V2 API:
* [GET /rfq/pool/v2/{CHAIN\_ID}](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/pool-v2) - Get information about a blockchain network supported by clipper.
* [GET /rfq/quote/v2/{CHAIN\_ID} ](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/quote-v2)- Generate potential asset swap quotes. Obtain pricing and essential details for informed decision-making **:**
**New Domain**
`https://blade-api.sushi.com`
### Authorization
In order to prevent abuse on the API we implement rate limits on the requests, to overcome these limits as an aggregator get in contact with the support team to get API credentials (user and password) [here](mailto:aggregators@shipyardsoftware.org).
{% hint style="warning" %}
For API v2 the api key auth is required.
{% endhint %}
The API uses the API KEY authentication method. You have to include the credentials in the header `x-api-key`.
Example: If your api key is TzuiYrpRgN2
```bash
curl --location 'https://blade-api.sushi.com/rfq/v2/pool/1?fieldset=offchain-data&pool_address=0x655eDCE464CC797526600a462A8154650EEe4B77' \
--header 'x-api-key: TzuiYrpRgN2' \
--data ''
```
### Errors
#### Common Error Codes
| Code | Reason |
|---|
| 400 | Bad Request - Invalid data in the request |
| 401 | Unauthorized |
| 403 | Forbidden Error |
| 500 | Internal Server Error |
| 503 | External Service Error |
#### Error Format
```json
{
"errorMessage": "Description of the error",
"errorType": "Type of the error",
"errorCode": 422, // it is returned only when we have a clipper code for the error
"data": [] // is is returned only when the input data is invalid
}
```
{% hint style="warning" %} `error_code` and `data` are not always present
{% endhint %}
*Examples*
1. If we make a request to [quote](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/quote-v2) endpoint and the body does not have the field `chain_id` (required param), the API response will look like similar to this:
```json
{
"errorMessage": "Invalid input data",
"errorType": "BadData",
"errorCode": 422,
"data": [
{
"type": "missing",
"loc": [
"chain_id"
],
"msg": "Field required",
"input": {
"input_amount": "18000",
"input_asset_symbol": "ETH",
"output_asset_symbol": "WBTC",
"time_in_seconds": 60
},
"url": "https://errors.pydantic.dev/2.1/v/missing"
}
]
}
```
2. If we make a request to [quote](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/quote-v2) endpoint and we send an `input_asset_symbol` that clipper does not support, the API response will look like similar to this
```json
{
"errorMessage": "input_asset_symbol: INVALIDASSET is not supported",
"errorType": "BadData"
}
```
3. If we make a request to [quote](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) endpoint and we send invalid credentials
```json
{
"errorMessage": "Auth: Access is forbidden",
"errorType": "Forbidden"
}
```
#### Clipper Error Codes
These codes appear in the field `errorCode`
| Code | Reason |
|---|
| 422 | Invalid input data |
| 409 | Quote problems |
# Pool v2
This endpoint provides comprehensive information about all the pools on the selected chain, including details about its assets, the contract address of its liquidity pool, and other relevant data. This information is crucial for making off-chain calculations and predicting quotes.
### URL
```url
https://blade-api.sushi.com/rfq/v2/pool/{CHAIN_ID}
```
## Request
| Path Param | Description | Example |
| ---------- | -------------------------------------------- | ------------- |
| chain | Integer - Required
ID of the chain
| chain\_id=137 |
| Query Param | Description | Example |
|---|
| pool_address | str - Optional
The address of the pool. If not provided, all pools on the selected chain will be returned. | pool_address=0x655eDCE464CC797526600a462A8154650EEe4B77 |
| time_in_seconds | Integer - Optional The time duration for which a quote will be available. This value is used to calculate the fees; as you decrease the time, you will see lower fees. By default, the system sets a predefined value. Note: For on-chain data, this field is not considered. | time_in_seconds=30 |
| fieldset | String - Optional
Determines whether the API should make calls to the blockchain to return on-chain data. Accepted Value: offchain-data If the parameter is not provided, it will default to handling on-chain data. | fieldset=offchain-data |
## Response
#### On-chain object
#### Pool Data on-chain object
#### Pool on-chain object
| Field | Description |
|---|
| chain_id | Integer - ID of the chain |
| address | String(ETH address) - Clipper contract address of the pool, is the address used when executing a transaction |
| num_assets | Integer - The total of assets available in the chain |
| value_in_usd | Float - Value of the pool in USD (***REVIEW TEMO) |
| swaps_enabled | Bool - Represents if the swaps are available for the chain |
#### Asset on-chain object
| Field | Description |
|---|
| name | String - The name of the asset, this value should be used when making a quote |
| address | String(ETH address) - The contract address of the asset |
| price_in_usd | Float - Current price in dollars for the asset |
| value_in_usd | Float - Value of the pool in USD |
| target_value_in_usd | Float - USD target value for this asset in the pool |
#### Off-chain object
#### Pool Data off-chain object
#### Pool off-chain object
| Field | Description |
|---|
| chain_id | Integer - ID of the chain |
| address | String(ETH address) - Clipper contract address of the pool, is the address used when executing a transaction |
| num_assets | Integer - The total of assets available in the chain |
| k | Float - K factor |
| time_in_seconds | Integer - Number of seconds were used to calculate the fees of a swap, this number indicates the number of seconds that quotes are live |
| default_time_in_seconds | Integer - Default number of seconds that quotes are live, is value used to calculate fees when don't send the query param time_in_seconds |
| swaps_enabled | Bool - Represents if the swaps are available for the chain |
#### Asset off-chain object
| Field | Description |
|---|
| name | String - The name of the asset, this value should be used when making a quote |
| address | String(ETH address) - The contract address of the asset |
| price_in_usd | Float - Current price in dollars for the asset |
| listing_weight | Integer - asset weight within the pool |
#### Pair object
| Field | Description |
|---|
| assets | List[str] - Pair of assets available to make a swap - e.g: ["ETH", "MATIC"] |
| fee_in_basis_points | Float - Fee for make a swap between the pair |
## Examples
1.Get the offchain data for Polygon chain (chain\_id=137)
***Request***
curl -X GET "https://blade-api.sushi.com/rfq/v2/pool/1?fieldset=offchain-data" -H "x-api-key: mQzA8Uy6nZ8Vy"
***Response***
```json
{
"pool_type": "offchain",
"pools": [
{
"pool": {
"chain_id": 1,
"address": "0x655eDCE464CC797526600a462A8154650EEe4B77",
"num_assets": 4,
"k": 0.06,
"time_in_seconds": 60,
"default_time_in_seconds": 60,
"swaps_enabled": true
},
"assets": [
{
"name": "ETH",
"address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"price_in_usd": 2076.799,
"listing_weight": 79
},
{
"name": "USDC",
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"price_in_usd": 1,
"listing_weight": 188
},
{
"name": "USDT",
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"price_in_usd": 1,
"listing_weight": 305
},
{
"name": "DAI",
"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"price_in_usd": 1,
"listing_weight": 250
}
],
"pairs": [
{
"assets": [
"ETH",
"USDC"
],
"fee_in_basis_points": 9
},
{
"assets": [
"ETH",
"USDT"
],
"fee_in_basis_points": 9
},
{
"assets": [
"ETH",
"DAI"
],
"fee_in_basis_points": 8
},
{
"assets": [
"USDC",
"USDT"
],
"fee_in_basis_points": 5
},
{
"assets": [
"USDC",
"DAI"
],
"fee_in_basis_points": 5
},
{
"assets": [
"USDT",
"DAI"
],
"fee_in_basis_points": 5
}
]
}
]
}
```
2. Get the on-chain data for mainnet chain (chain\_id=1)
***Request***
{% code overflow="wrap" %}
```bash
curl -X GET "https://blade-api.sushi.com/rfq/v2/pool/1?pool_address=0x655eDCE464CC797526600a462A8154650EEe4B77" -H "x-api-key: mQzA8Uy6nZ8Vy"
```
{% endcode %}
***Response***
```json
{
"pool_type": "onchain",
"pools": [
{
"pool": {
"chain_id": 1,
"address": "0x655eDCE464CC797526600a462A8154650EEe4B77",
"num_assets": 4,
"pool_tokens": 1.3792871898369242e+24,
"value_in_usd": 1978682.496424432,
"swaps_enabled": true
},
"assets": [
{
"name": "USDC",
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"balance": "417751254142",
"price_in_usd": 1,
"value_in_usd": 417751.254142,
"target_value_in_usd": 416727.89356391726
},
{
"name": "USDT",
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"balance": "259059412007",
"price_in_usd": 1,
"value_in_usd": 259059.412007,
"target_value_in_usd": 256868.3409508736
},
{
"name": "DAI",
"address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
"balance": "309714519494182375269440",
"price_in_usd": 1,
"value_in_usd": 309714.5194941824,
"target_value_in_usd": 313379.3759600658
},
{
"name": "ETH",
"address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"balance": "476877882758190421102",
"price_in_usd": 2080.527,
"value_in_usd": 992157.3107812497,
"target_value_in_usd": 991706.8859495752
}
]
}
]
}
```
# Quote v2
This endpoint facilitates the creation of a potential quote for executing a swap between two assets. It allows users to obtain pricing information and other essential details necessary to initiate asset swaps within the system. Use this endpoint to explore the potential cost and feasibility of asset exchanges before finalizing transactions.
### URL
```url
https://blade-api.sushi.com/rfq/v2/quote/{CHAIN_ID}
```
## Request
| Path Param | Description | Example |
| ---------- | -------------------------------------------- | ------------- |
| chain | Integer - Required
ID of the chain
| chain\_id=137 |
| Query Param | Description | Example |
|---|
| pool_address | str - Optional
Address of the pool. If not present, the best pool will be calculated | pool_address=0x655eDCE464CC797526600a462A8154650EEe4B77 |
| time_in_seconds | Integer - Optional
Amount of time between accepting a quote and receiving the quote on the blockchain. As this value increases, the quote will get worse for the user. | time_in_seconds=30 |
| output_amount | Integer/String - Optional
Desired quantity of assets to receive as part of the swap
This field is mutually exclusive with input_amount | output_amount=18000 |
| input_amount | Integer/String - Optional
Desired quantity of assets you are willing to exchange
This field is mutually exclusive with output_amount |
input_amount=18000 |
| input_asset_symbol | String - Required
Identifier of the asset you want to provide for the swap
Should correspond to the asset name returned from the pool call | input_asset_symbol=ETH |
| output_asset_symbol | String - Required
Identifier of the asset you want to receive in the swap
Should correspond to the asset name returned from the pool call | output_asset_symbol=DAI |
## Response
Quote object
| Field | Description |
|---|
| id | String(UUID) - Id of the quote, use this value when signing a quote |
| must_accept_by | String - Human-readable UTC timestamp by which you must accept the quote and should be expected to be a short duration. If this time has passed already, request a new quote - the server will not sign a quote after must_accept_by has passed |
| good_until | Integer - number of seconds that quotes live |
| chain_id | Integer - Represents the ID of the chain |
| input_asset_address | String - Contract address of the asset you want to provide for the swap |
| input_amount | String - Amount of assets to be exchanged |
| output_asset_address | String - Contract address of the asset you want to receive in the swap |
| output_amount | String - Amount of assets you will receive in the exchange |
| input_value_in_usd | Float - Amount in dollars to be exchanged |
| output_value_in_usd | Float - Amount in dollars you will receive in the exchange |
| created_at | Integer - Unix Timestamp indicating the date and time when the quote was created |
| rate | Float - swap rate |
## Examples
If you want to create a quote to make a swap from ETH to USDC in Ethereum Mainnet (chain\_id=1)
***Request***
```bash
curl -X GET "https://blade-api.sushi.com/rfq/v2/quote/1?pool_address=0x655eDCE464CC797526600a462A8154650EEe4B77&time_in_seconds=60&output_asset_symbol=USDC&input_asset_symbol=ETH&input_amount=10000000000000000000" \
-H "x-api-key: mQzA8Uy6nZ8Vyh" \
-H "Content-Type: application/json"
```
***Response***
```json
{
"id": "05a51aa6-41b5-4c61-a452-f1b95d0d43e4",
"must_accept_by": "2023-10-13 22:24:20.932560+00:00",
"good_until": 1697235920,
"chain_id": 1,
"input_amount": "10000000000000000000",
"output_amount": "5661947917",
"input_value_in_usd": 15595.15,
"output_value_in_usd": 5668.12,
"created_at": 1697235848,
"rate": 566.1947917,
"input_asset_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"output_asset_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
```
# Deposit v2
This endpoint allows users to deposit assets into a liquidity pool by submitting the required details, such as the pool contract address and the amount of assets to be deposited. This process is crucial for users who want to increase the liquidity of the pool and potentially earn rewards or fees. Use this endpoint to securely and efficiently add assets to the pool, contributing to the stability and performance of the ecosystem.
## Request
| Body Param | Description | Example |
|---|
| sender | String - Required
The address of the user initiating the deposit transaction. | "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9" |
| pool_address | String - Required
The address of the pool | "0x989E8F547FbCa65f4FB0af41e50e4058e6c68166" |
| days_to_lock | Integer
Number of days to lock the deposit in the liquidity pool.
Note: Required for all pools except Katana, which uses lock_time instead. | 5 |
| lock_time | Integer
Number of minutes to lock the deposit in the liquidity pool.
Note: Only suported by the Katana pool. For other pools, use days_to_lock. | 5 |
| deposit | Object
An object containing the asset address and the amount to deposit as a string. The amount should be in its machine-readable form.
This parameter is required only if single asset is false. | {
"0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599": "400000000",
"0x6B175474E89094C44Da98b954EedeAC495271d0F": "2000000000000000000",
"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": "1000000000000000000",
"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": "2000000"
}
|
| chain_id | Integer - Required The unique identifier of the blockchain network where the deposit will be made. | 1 |
| output_pool_tokens | Integer - Optional
The total number of pool tokens the user wants to receive. It is only valid for single-asset deposits. | 10000 |
| single_asset | Bool - Optional
A boolean that indicates whether only one asset is being deposited.
Default = False | true |
| single_token | String Required only when single_asset is true. This represents the address of the single asset being deposited. | 0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599 |
## Response
Deposit object
| Field | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| sender | String - The address of the user who initiated the deposit transaction. |
| n\_days | Integer - The number of days the assets will be locked in the pool, matching the days\_to\_lock from the request.
Note: Supported for all pools except Katana. For katana, returns lock\_time.
|
| lock\_time | Integer - The number of minutes the assets will be locked in the pool, matching the lock\_time from the request.
Note: Only supported by the Katana pool. For other pools, returns n\_days.
|
| good\_until | The timestamp indicating how long the deposit details, including the signature, are valid. |
| pool\_tokens | String - The total number of pool tokens that will be given to the user as a result of the deposit. |
| signature | Object - A [EIP 2098 "short signature" representation](https://eips.ethereum.org/EIPS/eip-2098) for the signature from the Clipper Exchange server |
| clipper\_exchange\_address | The address of the Clipper exchange contract where the deposit is being made. |
| deposit\_amounts | List - A list of the amounts to be deposited for each asset. If an asset was not provided in the request, the amount returned will be 0. For example, if 3 assets were provided in a 4-asset pool, the response will include an amount of 0 for the missing asset.
For single asset deposit this field is not present
|
| amount | String - (Single-asset deposits only) The total amount of the single asset that is being deposited into the pool. |
| token | String - (Single-asset deposits only) The address of the token that is being deposited into the pool. |
| extra\_data | Encode LP token price and prices list into ABI-compatible bytes.
Note: Only supported by the Katana pool.
|
## Examples
#### Deposit Multiple Assets
If you want to deposit multiples assets.
***Request***
```bash
curl -X POST "https://blade-api.sushi.com/rfq/v2/deposit" \
-H "Content-Type: application/json" \
-d '{
"deposit": {
"0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1": "2000000000000000000"
},
"sender": "0x54298A80a06068587E13b9dC1AC090259A98D5cD",
"days_to_lock": 10,
"chain_id": 10,
"single_asset": false,
"pool_address": "0x5130f6cE257B8F9bF7fac0A0b519Bd588120ed40"
}'
```
***Response***
```json
{
"sender": "0x54298A80a06068587E13b9dC1AC090259A98D5cD",
"n_days": 10,
"pool_tokens": "29438108002416884",
"good_until": 1729657240,
"signature": {
"v": 28,
"r": "0x7c37b52021ea25ed38cbaf4def111eb9b5e6f0c1dc6c34ded53b9824c40febbf",
"s": "0x66ce09126a23cadf277877e556f2d6c5bc3ad1e7080368a13bb0349208d30396"
},
"clipper_exchange_address": "0x5130f6cE257B8F9bF7fac0A0b519Bd588120ed40",
"deposit_amounts": [
"0",
"0",
"0",
"0",
"2000000000000000000",
"0",
"0"
]
}
```
**Katana Example:**
***Request***
```bash
curl -X POST "https://blade-api.sushi.com/rfq/v2/deposit" \
-H "Content-Type: application/json" \
-d '{
"deposit": {
"0x0913DA6Da4b42f538B445599b46Bb4622342Cf52": "2000000000000000000"
},
"sender": "0x54298A80a06068587E13b9dC1AC090259A98D5cD",
"lock_time":720,
"chain_id": 747474,
"single_asset": false,
"pool_address": "0x989E8F547FbCa65f4FB0af41e50e4058e6c68166"
}'
```
***Response***
```json
{
"sender": "0x54298A80a06068587E13b9dC1AC090259A98D5cD",
"pool_tokens": "1911697202535426211354545867456512",
"good_until": 1754952442,
"signature": {
"v": 27,
"r": "0xa4be6ab4120b2d55e383f9489e317c05911097cf38b92f8dffe393fed23c07ec",
"s": "0x66d48deb50124d9e4d20c5f6ce570fd930f6bb8a1cd67bae68daef5fbf89112c"
},
"clipper_exchange_address": "0x989E8F547FbCa65f4FB0af41e50e4058e6c68166",
"extra_data": "0x000000000000000000000000000000000000000098b593221fc2d138f0a669c5000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000e475704f93603000000000000000000000000000000000000000000000000019257a485f5ec7000000",
"deposit_amounts": [
"0",
"2000000000000000000"
],
"lock_time": 720
}
```
#### Deposit With Specific output pool token
If you want to deposit and specify how many pool tokens receive.
***Request***
```bash
curl -X POST "https://blade-api.sushi.com/rfq/v2/deposit" \
-H "Content-Type: application/json" \
-d '{
"sender": "0x54298A80a06068587E13b9dC1AC090259A98D5cD",
"days_to_lock": 10,
"chain_id": 10,
"single_asset": true,
"output_pool_tokens": 29438108002416884,
"single_token": "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1"
"pool_address": "0x5130f6cE257B8F9bF7fac0A0b519Bd588120ed40"
}'
```
***Response***
```json
{
"sender": "0x54298A80a06068587E13b9dC1AC090259A98D5cD",
"n_days": 10,
"pool_tokens": "29438108002416884",
"good_until": 1729657750,
"signature": {
"v": 28,
"r": "0x8abcd885e7c151158e21288124b6cac461088ecd9ac07938752667277de2f581",
"s": "0x4716077b4ee2eaf0668d0c219c507581efa61c287e1bdfe32597fb5d19609641"
},
"clipper_exchange_address": "0x5130f6cE257B8F9bF7fac0A0b519Bd588120ed40",
"amount": "1998512049104122112",
"token": "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1"
}
```
# API v1
# Overview
## Endpoints
Learn more about the different endpoints of the Swap API:
* [GET /rfq/pool](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/pool) - Get information about a blockchain network supported by Clipper.
* [POST /rfq/quote](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) - Generate potential asset swap quotes. Obtain pricing and essential details for informed decision-making.
* [POST /rfq/sign](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/sign) - Facilitates blockchain transaction preparation and security by returning the required signature and data. Use it for efficient and secure asset swaps.
## Authorization
To prevent abuse of the API, we implement rate limits on requests. If you need to bypass these limits as an aggregator, please contact our support team to get API credentials (username and password) [here](mailto:aggregators@shipyardsoftware.org).
These credentials are used to authorize requests made to the following endpoints: `/rfq/pool` , `/rfq/quote` and `/rfq/sign`
#### Basic Authentication
{% hint style="danger" %}
DEPRECATED: If you are using Basic Authentication, please contact us to receive an API key.
{% endhint %}
The API uses the Basic authentication method, where you must include the credentials (`username:password`) in the headers in `Base64` format.
**Example:**
If your username is "`clipper`" and your password is "`clipperdocs`", the Base64 encoded string for `clipper:clipperdocs` is `Y2xpcHBlcjpjbGlwcGVyZG9jcw==`.
```bash
curl --location 'https://api.clipper.exchange/rfq/quote' \
--header 'Authorization: Basic Y2xpcHBlcjpjbGlwcGVyZG9jcw==' \
--header 'Content-Type: application/json' \
--data '{
"input_amount": "780000000000000",
"input_asset_symbol": "ETH",
"output_asset_symbol": "DAI",
"time_in_seconds": 60,
"chain_id": 1
}
'
```
#### Api Key Authentication
The API uses the API KEY authentication method. You have to include the credentials in the header `x-api-key`.
Example: If your api key is TzuiYrpRgN2
```bash
curl --location 'https://api.clipper.exchange/rfq/quote' \
--header 'x-api-key: TzuiYrpRgN2' \
--header 'Content-Type: application/json' \
--data '{
"input_amount": "780000000000000",
"input_asset_symbol": "ETH",
"output_asset_symbol": "DAI",
"time_in_seconds": 60,
"chain_id": 1
}
'
```
{% hint style="danger" %}
The API v1 currently supports both API Key and Basic Authentication. However, Basic Authentication will be deprecated in the future. \
\
**Note**: The Pool endpoint currently only supports Basic Authentication. To use API Key authentication, use the [Pool V2](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/pool-v2) endpoint.
{% endhint %}
### Errors
#### Common Error Codes
| Code | Reason |
|---|
| 400 | Bad Request - Invalid data in the request |
| 401 | Unauthorized |
| 403 | Forbidden Error |
| 500 | Internal Server Error |
| 503 | External Service Error |
#### Error Format
```json
{
"errorMessage": "Description of the error",
"errorType": "Type of the error",
"errorCode": 422, // it is returned only when we have a clipper code for the error
"data": [] // is is returned only when the input data is invalid
}
```
{% hint style="warning" %} `error_code` and `data` are not always present
{% endhint %}
*Examples*
1. If we make a request to [quote](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) endpoint and the body does not have the field `chain_id` (required param), the API response will look like similar to this:
```json
{
"errorMessage": "Invalid input data",
"errorType": "BadData",
"errorCode": 422,
"data": [
{
"type": "missing",
"loc": [
"chain_id"
],
"msg": "Field required",
"input": {
"input_amount": "18000",
"input_asset_symbol": "ETH",
"output_asset_symbol": "WBTC",
"time_in_seconds": 60
},
"url": "https://errors.pydantic.dev/2.1/v/missing"
}
]
}
```
2. If we make a request to [quote](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) endpoint and we send an `input_asset_symbol` that clipper does not support, the API response will look like similar to this
```json
{
"errorMessage": "input_asset_symbol: INVALIDASSET is not supported",
"errorType": "BadData"
}
```
3. If we make a request to [quote](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v1/quote) endpoint and we send invalid credentials
```json
{
"errorMessage": "Auth: Access is forbidden",
"errorType": "Forbidden"
}
```
#### Clipper Error Codes
These codes appear in the field `errorCode`
| Code | Reason |
|---|
| 422 | Invalid input data |
| 409 | Quote problems |
# Pool
{% hint style="warning" %}
If you already have an API key for authentication, we recommend using [Pool v2](/disclaimers-and-technical/integrating-with-clipper-rfq/api-reference/api-v2/pool-v2) instead as it does not support API key authentication.
{% endhint %}
This endpoint provides comprehensive information about a clipper pool, including details on its assets, the contract address of its liquidity pool, and other pertinent data. This information is crucial for making off-chain calculations and predicting quotes.
## Request
| Query Param | Description | Example |
|---|
| chain_id | Integer - Required
ID of the chain. | chain_id=137 - Polygon
chain_id=1 - Ethereum mainnet |
| time_in_seconds | Integer - Optional The time duration for which a quote will be available. This value is used to calculate the fees; as you decrease the time, you will see lower fees. By default, the system sets a predefined value. Note: For on-chain data, this field is not considered. | time_in_seconds=30 |
| fieldset | String - Optional
Determines whether the API should make calls to the blockchain to return on-chain data. Accepted Value: offchain-data If the parameter is not provided, it will default to handling on-chain data. | fieldset=offchain-data |
## Response
#### Offchain object
#### Pool object
| Field | Description |
|---|
| chain_id | Integer - ID of the chain |
| address | String(ETH address) - Clipper contract address of the pool, is the address used when executing a transaction |
| num_assets | Integer - The total of assets available in the chain |
| k | Float - K factor |
| time_in_seconds | Integer - Number of seconds were used to calculate the fees of a swap, this number indicates the number of seconds that quotes are live |
| default_time_in_seconds | Integer - Default number of seconds that quotes are live, is value used to calculate fees when don't send the query param time_in_seconds |
| swaps_enabled | Bool - Represents if the swaps are available for the chain |
#### Asset object
| Field | Description |
|---|
| name | String - The name of the asset, this value should be used when making a quote |
| address | String(ETH address) - The contract address of the asset |
| price_in_usd | Float - Current price in dollars for the asset |
| listing_weight | Integer - asset weight within the pool |
#### Pair object
| Field | Description |
|---|
| assets | List[str] - Pair of assets available to make a swap - e.g: ["ETH", "MATIC"] |
| fee_in_basis_points | Float - Fee for make a swap between the pair |
## Examples
Get the offchain data for Polygon chain (chain\_id=137)
***Request***
{% code overflow="wrap" %}
```bash
curl -X GET "https://api.clipper.exchange/rfq/pool?chain_id=137&fieldset=offchain-data" -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA=="
```
{% endcode %}
***Response***
```json
{
"pool": {
"chain_id": 137,
"address": "0x6Bfce69d1Df30FD2B2C8e478EDEC9dAa643Ae3B8",
"num_assets": 6,
"k": 0.115,
"time_in_seconds": 60,
"default_time_in_seconds": 60,
"swaps_enabled": true
},
"assets": [
{
"name": "ETH",
"address": "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
"price_in_usd": 1656.9150000000002,
"listing_weight": 125
},
{
"name": "MATIC",
"address": "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270",
"price_in_usd": 0.56802,
"listing_weight": 100
},
{
"name": "WBTC",
"address": "0x1BFD67037B42Cf73acF2047067bd4F2C47D9BfD6",
"price_in_usd": 27405.915,
"listing_weight": 178
},
{
"name": "USDC",
"address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
"price_in_usd": 1.0,
"listing_weight": 178
},
{
"name": "DAI",
"address": "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
"price_in_usd": 1.0,
"listing_weight": 250
},
{
"name": "USDT",
"address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
"price_in_usd": 1.0,
"listing_weight": 305
}
],
"pairs": [
{
"assets": [
"ETH",
"MATIC"
],
"fee_in_basis_points": 12.0
},
{
"assets": [
"ETH",
"WBTC"
],
"fee_in_basis_points": 6.0
},
{
"assets": [
"ETH",
"USDC"
],
"fee_in_basis_points": 8.0
},
{
"assets": [
"ETH",
"DAI"
],
"fee_in_basis_points": 8.0
},
{
"assets": [
"ETH",
"USDT"
],
"fee_in_basis_points": 8.0
},
{
"assets": [
"MATIC",
"WBTC"
],
"fee_in_basis_points": 12.0
},
{
"assets": [
"MATIC",
"USDC"
],
"fee_in_basis_points": 12.0
},
{
"assets": [
"MATIC",
"DAI"
],
"fee_in_basis_points": 12.0
},
{
"assets": [
"MATIC",
"USDT"
],
"fee_in_basis_points": 12.0
},
{
"assets": [
"WBTC",
"USDC"
],
"fee_in_basis_points": 8.0
},
{
"assets": [
"WBTC",
"DAI"
],
"fee_in_basis_points": 8.0
},
{
"assets": [
"WBTC",
"USDT"
],
"fee_in_basis_points": 8.0
},
{
"assets": [
"USDC",
"DAI"
],
"fee_in_basis_points": 5.0
},
{
"assets": [
"USDC",
"USDT"
],
"fee_in_basis_points": 5.0
},
{
"assets": [
"DAI",
"USDT"
],
"fee_in_basis_points": 5.0
}
],
"pool_type": "offchain"
}
```
# Quote
This endpoint facilitates the creation of a potential quote for executing a swap between two assets. It allows users to obtain pricing information and other essential details necessary to initiate asset swaps within the system. Use this endpoint to explore the potential cost and feasibility of asset exchanges before finalizing transactions.
## Request
| Body Param | Description | Example |
|---|
| chain_id | Integer - Required
ID of the chain | "chain_id": 137 |
| time_in_seconds | Integer - Optional
Amount of time between accepting a quote and receiving the quote on the blockchain. As this value increases, the quote will get worse for the user. | "time_in_seconds": 30 |
| output_amount | Integer/String - Optional
Desired quantity of assets to receive as part of the swap
This field is mutually exclusive with input_amount | "output_amount": "18000"
output_amount: 18000 |
| input_amount | Integer/String - Optional
Desired quantity of assets you are willing to exchange
This field is mutually exclusive with output_amount | "input_amount": "18000"
input_amount: 18000 |
| input_asset_symbol | String - Required
Identifier of the asset you want to provide for the swap
Should correspond to the asset name returned from the pool call | "input_asset_symbol": "ETH" |
| output_asset_symbol | String - Required
Identifier of the asset you want to receive in the swap
Should correspond to the asset name returned from the pool call | "output_asset_symbol": "DAI" |
## Response
Quote object
| Field | Description |
|---|
| id | String(UUID) - Id of the quote, use this value when signing a quote |
| must_accept_by | String - Human-readable UTC timestamp by which you must accept the quote and should be expected to be a short duration. If this time has passed already, request a new quote - the server will not sign a quote after must_accept_by has passed |
| good_until | Integer - number of seconds that quotes live |
| chain_id | Integer - Represents the ID of the chain |
| input_asset_address | String - Contract address of the asset you want to provide for the swap |
| input_amount | String - Amount of assets to be exchanged |
| output_asset_address | String - Contract address of the asset you want to receive in the swap |
| output_amount | String - Amount of assets you will receive in the exchange |
| input_value_in_usd | Float - Amount in dollars to be exchanged |
| output_value_in_usd | Float - Amount in dollars you will receive in the exchange |
| created_at | Integer - Unix Timestamp indicating the date and time when the quote was created |
| rate | Float - swap rate |
## Examples
If you want to create a quote to make a swap from ETH to USDC in Ethereum Mainnet (chain\_id=1)
***Request***
```bash
curl -X POST "https://api.clipper.exchange/rfq/quote" \
-H "x-api-key: TzuY788jU6lOoj" \
-H "Content-Type: application/json" \
-d '{
"input_amount": "10000000000000000000",
"input_asset_symbol": "ETH",
"output_asset_symbol": "USDC",
"time_in_seconds": 60,
"chain_id": 1
}'
```
***Response***
```json
{
"id": "05a51aa6-41b5-4c61-a452-f1b95d0d43e4",
"must_accept_by": "2023-10-13 22:24:20.932560+00:00",
"good_until": 1697235920,
"chain_id": 1,
"input_amount": "10000000000000000000",
"output_amount": "5661947917",
"input_value_in_usd": 15595.15,
"output_value_in_usd": 5668.12,
"created_at": 1697235848,
"rate": 566.1947917,
"input_asset_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"output_asset_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
```
# Sign
The endpoint plays a pivotal role in the preparation and execution of secure asset swaps on the blockchain. By providing a Quote ID and a destination address, users can initiate the signing process, resulting in the generation of the essential signature and transaction data. This signature and data package, in turn, is integral for ensuring the validity and security of asset transfers within the blockchain network.
## Request
| Body Param | Description | Example |
|---|
| quote_id | String(UUID) - Required
The id of the quote returned in quote endpoint | "4c707e45-7019-4b81-b875-c5eb6fe061d6" |
| destination_address | String - Required
It will receive the output token | "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9" |
| sender_address | String - Optional
it is for DEX aggregator partners that are using their own smart contract to mediate the interaction between users and Clipper. Aggregators should use the address of the account that they will pull tokens from (i.e., the EOA user address) as opposed to the address of their deployed contract. This is an optional value on signing requests - by default, destination_address will be used. | "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9" |
| aux_data | String(bit32) - Optional
It is for use the calldata swap feature, it can be set to any string and is used for identification purposes in the event logs. By default is 0x436c697070657200000000000000000000000000000000000000000000000000 that is the representation of Clipper | "0x31494e4348000000000000000000000000000000000000000000000000000000" |
| calldata | Bool - Optional
Send this as true if we want to get the bytes representation of the swap in the response. Client can use this to be sent directly to the pool contract for execution.
Default is false | true |
| native_input | Bool - Optional
If the input token is native (e.g. raw ETH), this value must be true. This will use the sellEthForToken contract function and will take the msg.value for the input. e.g ETH -> USDC
Default is false
This field is mutually exclusive with native_output | true |
| native_output | Bool - Optional
If the output token is native (i.e. raw ETH), this value must be true. This will use the sellTokenForEth contract function. e.g USDC -> ETH
Default is false
This field is mutually exclusive with native_input | true |
{% hint style="info" %}
In case that you want to deal with raw ETH or MATIC for input or output on the swap you should use `native_input` and `native_output` params. More details about Native Tokens can be found [here](/disclaimers-and-technical/integrating-with-clipper-rfq/guides/interacting-with-the-clipper-exchange-contracts#handling-native-currency).
{% endhint %}
## Response
Sign object
| Field | Description |
|---|
| chain_id | Integer - Represents the ID of the chain |
| input_asset_address | String - Contract address of the asset you want to provide for the swap |
| output_asset_address | String - Contract address of the asset you want to receive in the swap |
| input_amount | String - Amount of assets to be exchanged |
| output_amount | String - Amount of assets you will receive in the exchange |
| good_until | String - Number of seconds that quotes live. It can also contained a packed representation of the state |
| destination_address | String - Address will receive the output token |
| signature | Object - A EIP 2098 "short signature" representation for the signature from the Clipper Exchange server |
| clipper_exchange_address | String - Clipper contract address of the pool, is the address used when executing a transaction |
| calldata | String - Bytes representation of the swap function and parameters to be sent directly to the clipper_exchange_address for execution |
## Examples
#### Without calldata
If you want to sign a quote and manually use the values in the response to create the transaction.
***Request***
```bash
curl -X POST "https://api.clipper.exchange/rfq/sign" \
-H "x-api-key: TzuY788jU6lOoj" \
-H "Content-Type: application/json" \
-d '{
"destination_address": "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9",
"quote_id": ""
}'
```
***Response***
```json
{
"chain_id": 1,
"input_asset_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"output_asset_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"input_amount": "10000000000000000000",
"output_amount": "5661947917",
"good_until": "364238673390486983853316167090878487969884185392043445686993915855904",
"destination_address": "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9",
"signature": {
"v": 28,
"r": "0xfb8599e4ef2c89b03e1ebc3067f0ba38ecea64517bafa932e5c642318ec923d9",
"s": "0x1d3c7e38951b23bc459ac91ad668dede2a681bc4c98b915116983f4ae1dcdaa7"
},
"clipper_exchange_address": "0xE7b0CE0526fbE3969035a145C9e9691d4d9D216c"
}
```
#### With Calldata
1. If you want to sign a quote and get the bytes representation of the swap to be sent directly to the pool contract for execution.
***Request***
```bash
curl -X POST "https://api.clipper.exchange/rfq/sign" \
-H "x-api-key: TzuY788jU6lOoj" \
-H "Content-Type: application/json" \
-d '{
"destination_address": "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9",
"quote_id": "",
"calldata": true,
"aux_data": "0x31494e4348000000000000000000000000000000000000000000000000000000",
}'
```
***Response***
```json
{
"chain_id": 1,
"input_asset_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"output_asset_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"input_amount": "10000000000000000000",
"output_amount": "5661947917",
"good_until": "364266596581665814407146313234570973398742125152679878859837657433201",
"destination_address": "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9",
"signature": {
"v": 28,
"r": "0x762ad0475b3a7c42735686d7911f117a2ff6fca1bc3c5c75f4ee43df8da2a61b",
"s": "0x1eceffea0a50d12566e9fa6b4d9ed826106143d321389654c3c327c648f6f3f6"
},
"clipper_exchange_address": "0xE7b0CE0526fbE3969035a145C9e9691d4d9D216c",
"calldata": "0x2b651a6c000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb480000000000000000000000000000000000000000000000008ac7230489e8000000000000000000000000000000000000000000000000000000000001517a780d0000000d82eb0b930000000005f7906e00b1a2bc2ec50000006400bc6529c471000000000000000000000000960376b3f62f41e7e66809a05d1c5afdfd60a0e9000000000000000000000000000000000000000000000000000000000000001c762ad0475b3a7c42735686d7911f117a2ff6fca1bc3c5c75f4ee43df8da2a61b1eceffea0a50d12566e9fa6b4d9ed826106143d321389654c3c327c648f6f3f60000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000002031494e4348000000000000000000000000000000000000000000000000000000"
}
```
2. If you want to sign a quote (using native input token) and get the bytes representation of the swap to be sent directly to the pool contract.
***Request***
```bash
curl -X POST "https://api.clipper.exchange/rfq/sign" \
-H "x-api-key: TzuY788jU6lOoj" \
-H "Content-Type: application/json" \
-d '{
"destination_address": "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9",
"quote_id": "",
"calldata": true,
"aux_data": "0x31494e4348000000000000000000000000000000000000000000000000000000",
"native_input": true
}'
```
***Response***
```json
{
"chain_id": 1,
"input_asset_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"output_asset_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"input_amount": "10000000000000000000",
"output_amount": "5661947917",
"good_until": "364126526759930684504042968316937832960196094624343681678885719229598",
"destination_address": "0x960376b3F62f41E7e66809a05D1C5afdFD60A0E9",
"signature": {
"v": 28,
"r": "0x1a8fc0856ff121e3ba5a244ee0837cef3d6c6ea96c593decc1b9d074c74c0139",
"s": "0x60bd1d8700fca625b58cbc4fe84c61b29bf46c9855146eda18da557ab0e079d5"
},
"clipper_exchange_address": "0xE7b0CE0526fbE3969035a145C9e9691d4d9D216c",
"calldata": "0x27a9b424000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb480000000000000000000000000000000000000000000000008ac7230489e8000000000000000000000000000000000000000000000000000000000001517a780d0000000d81968de90000000005f7911f00b1a2bc2ec50000006400bc6529c49e000000000000000000000000960376b3f62f41e7e66809a05d1c5afdfd60a0e9000000000000000000000000000000000000000000000000000000000000001c1a8fc0856ff121e3ba5a244ee0837cef3d6c6ea96c593decc1b9d074c74c013960bd1d8700fca625b58cbc4fe84c61b29bf46c9855146eda18da557ab0e079d50000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000002031494e4348000000000000000000000000000000000000000000000000000000"
}
```
# Troubleshooting & FAQs
### **403 Error with message “Unknown sender\_address” in sign API**
* The **sender\_address** is detected as unsafe (possibly bot).
* If the client is using a contract as router for the quote we need to whitelist the contract address in order to bypass the bot check.
# Terms of Service
Adopted: June 15, 2020
Welcome to the Clipper app ([www.clipper.exchange](http://www.clipper.exchange)), a website-hosted user interface (the “Interface”) made available by Shipyard Software Inc. (“we”, “our”, or “us”). The Interface provides access to a decentralized protocol on the Ethereum blockchain that allows users to trade cryptocurrencies on a peer-to-peer basis (the “Protocol”). Additionally, you can access the Protocol through third-party web or mobile interfaces. You are responsible for doing your own diligence on those interfaces to understand the fees and risks they present. These Terms of Use and any terms and conditions incorporated herein by reference (collectively, the “Terms”) govern your access and use of the Interface. You must read the Terms carefully. By accessing, browsing or otherwise using the Interface, or by acknowledging agreement to the Terms on the Interface, you agree that you have read, understood and accepted all of the Terms and our Privacy Policy (the “Privacy Policy”), which is incorporated by reference into the Terms. THE TERMS CONTAIN IMPORTANT INFORMATION, INCLUDING A BINDING ARBITRATION PROVISION AND A CLASS ACTION WAIVER, BOTH OF WHICH IMPACT YOUR RIGHTS AS TO HOW DISPUTES ARE RESOLVED. We may change, amend, or revise the Terms from time to time and at any time, in our sole discretion. When we make changes, we will make the updated Terms available on the Interface and update the “Last Updated” date at the beginning of the Terms accordingly. Please check the Terms periodically for changes. Any changes to the Terms will apply on the date that they are made, and your continued access or use of the Interface after the Terms have been updated will constitute your binding acceptance of the updates. If you do not agree to the revised Terms, then you should not continue to access or use the Interface.
## 1. Eligibility
In order to use the Interface, you must satisfy the following eligibility requirements:
1\. you are of legal age in the jurisdiction in which you reside and you have legal capacity to enter into the Terms and be bound by them;
2\. if you accept the Terms on behalf of a legal entity, you must have the legal authority to accept the Terms on that entity’s behalf, in which case “you” (except as used in this paragraph) will mean that entity;
3\. you are not a resident, national or agent of Antigua and Barbuda, Algeria, Bangladesh, Bolivia, Belarus, Burundi, Myanmar (Burma), Cote D'Ivoire (Ivory Coast), Crimea and Sevastopol, Cuba, Democratic Republic of Congo, Ecuador, Iran, Iraq, Libya, Mali, Morocco, Liberia, Nepal, North Korea, Somalia, Sudan, Syria, Venezuela, Zimbabwe or any other country to which the United States, the United Kingdom or the European Union embargoes goods or imposes similar sanctions (collectively, “Restricted Territories”); (ii) you are not a member of any sanctions list or equivalent maintained by the United States government, the United Kingdom government, by the European Union or the United Nations (collectively, “Sanctions Lists Persons”); or (iii) you do not intend to transact with any Restricted Territories or Sanctions List Persons;
4\. you are not a Restricted Person;
5\. you are not a resident of, reside in, a citizen of, incorporated in, or have a registered office the Republic of China; and
6\. your use of the Interface is not prohibited by and does not otherwise violate, assist you in the violation of any applicable laws or regulations, or contribute to or facilitate any illegal activity.
## 2. Access to the Interface
We reserve the right to disable access to the Interface at any time in the event of any breach of the Terms, including without limitation, if we reasonably believe that you, at any time, fail to satisfy the eligibility requirements set forth in the Terms. Further, we reserve the right to limit or restrict access to the Interface by any person or entity, or within any geographic area or legal jurisdiction, at any time and in our sole discretion. We will not be liable to you for any losses or damages you may suffer as a result of or in connection with the Interface being inaccessible to you at any time or for any reason.
## 3. Proprietary Rights
1\. We own all intellectual property and other rights in the Interface and its contents, including, but not limited to, software, text, images, trademarks, service marks, copyrights, patents, and designs. Unless expressly authorized by us, you may not copy, modify, adapt, rent, license, sell, publish, distribute, or otherwise permit any third party to access or use the Interface or any of its contents. Accessing or using the Interface does not constitute a grant to you of any proprietary intellectual property or other rights in the Interface or its contents.
2\. You will retain ownership of all intellectual property and other rights in any information and materials you submit through the Interface. However, by uploading such information or materials, you grant us a worldwide, royalty-free, irrevocable license to use, copy, distribute, publish and send this data in any manner in accordance with applicable laws and regulations.
3\. You may choose to submit comments, bug reports, ideas or other feedback about the Interface, including, without limitation, about how to improve the Interface (collectively, “Feedback”). By submitting any Feedback, you agree that we are free to use such Feedback at our discretion and without additional compensation to you, and to disclose such Feedback to third parties (whether on a non-confidential basis, or otherwise). If necessary under applicable law, then you hereby grant us a perpetual, irrevocable, non-exclusive, transferable, worldwide license under all rights necessary for us to incorporate and use your Feedback for any purpose.
4\. If you satisfy all of the eligibility requirements in the Terms and that your access to and use of the Interface complies with the Terms, you hereby are granted a single, personal, limited license to access and use the Interface. This license is non- exclusive, non-transferable, and freely revocable by us at any time without notice or cause. Use of the Interface for any purpose not expressly permitted by the Terms is strictly prohibited.
## 4. Prohibited Activity
You agree not to engage in, or attempt to engage in, any of the following categories of prohibited activity in relation to your access or use of the Interface:
1\. Activity that breaches the Terms;
2\. Activity that infringes on or violates any copyright, trademark, service mark, patent, right of publicity, right of privacy, or other proprietary or intellectual property rights under the law.
3\. Activity that seeks to interfere with or compromise the integrity, security, or proper functioning of any computer, server, network, personal device, or other information technology system, including, but not limited to, the deployment of viruses and denial of service attacks.
4\. Activity that seeks to defraud us or any other person or entity, including, but not limited to, providing any false, inaccurate, or misleading information in order to unlawfully obtain the property of another.
5\. Activity that violates any applicable law, rule, or regulation concerning the integrity of trading markets, including, but not limited to, the manipulative tactics commonly known as spoofing and wash trading.
6\. Activity that violates any applicable law, rule, or regulation of the United States or another relevant jurisdiction, including, but not limited to, the restrictions and regulatory requirements imposed by U.S. law.
7\. Activity that disguises or interferes in any way with the IP address of the computer you are using to access or use the Interface or that otherwise prevents us from correctly identifying the IP address of the computer you are using to access the Interface.
8\. Activity that transmits, exchanges, or is otherwise supported by the direct or indirect proceeds of criminal or fraudulent activity.
## 5. No Professional Advice or Fiduciary Duties
1\. All information provided in connection with your access and use of the Interface is for informational purposes only and should not be construed as professional advice. You should not take, or refrain from taking, any action based on any information contained in the Interface or any other information that we make available at any time, including, without limitation, blog posts, articles, links to third-party content, news feeds, tutorials, tweets and videos. Before you make any financial, legal, or other decisions involving the Interface, you should seek independent professional advice from an individual who is licensed and qualified in the area for which such advice would be appropriate.
2\. The Terms are not intended to, and do not, create or impose any fiduciary duties on us. To the fullest extent permitted by law, you acknowledge and agree that we owe no fiduciary duties or liabilities to you or any other party, and that to the extent any such duties or liabilities may exist at law or in equity, those duties and liabilities are hereby irrevocably disclaimed, waived, and eliminated. You further agree that the only duties and obligations that we owe you are those set out expressly in the Terms.
## 6. No Warranties
The Interface is provided on an “AS IS” and “AS AVAILABLE” basis. To the fullest extent permitted by law, we disclaim any representations and warranties of any kind, whether express, implied, or statutory, including, but not limited to, the warranties of merchantability and fitness for a particular purpose. You acknowledge and agree that your access and use of the Interface is at your own risk. We do not represent or warrant that access to the Interface will be continuous, uninterrupted, timely, or secure; that the information contained in the Interface will be accurate, reliable, complete, or current; or that the Interface will be free from errors, defects, viruses, or other harmful elements. No advice, information, or statement that we make should be treated as creating any warranty concerning the Interface. We do not endorse, guarantee, or assume responsibility for any advertisements, offers, or statements made by third parties concerning the Interface.
## 7. Compliance Obligations
The Interface may not be available or appropriate for use in all jurisdictions. By accessing or using the Interface, you agree that you are solely and entirely responsible for compliance with all laws and regulations that may apply to you. You further agree that we have no obligation to inform you of any potential liabilities or violations of law or regulation that may arise in connection with your access and use of the Interface and that we are not liable in any respect for any failure by you to comply with any applicable laws or regulations.
## 8. Assumption of Risk
By accessing and using the Interface, you represent that you understand (a) the inherent risks associated with products made available through the Protocol, and (b) the inherent risks associated with using cryptographic and blockchain-based systems. You further represent that you have a working knowledge of the usage and intricacies of blockchain-based digital assets, including, without limitation, ERC-20 token standard available on the Ethereum blockchain. You further understand that the markets for these blockchain-based digital assets are highly volatile due to factors that include, but are not limited to, adoption, speculation, technology, security, and regulation. You acknowledge that the cost and speed of transacting with blockchain-based systems, such as Ethereum, are variable and may increase or decrease, respectively, drastically at any time. You hereby acknowledge and agree that we are not responsible for any of these variables or risks associated with the Protocol and cannot be held liable for any resulting losses that you experience while accessing or using the Interface. Accordingly, you understand and agree to assume full responsibility for all of the risks of accessing and using the Interface to interact with the Protocol.
## 9. Third-Party Resources and Promotions
The Interface may contain references or links to third-party resources, including, but not limited to, information, materials, products, or services, that we do not own or control. In addition, third parties may offer promotions related to your access and use of the Interface. We do not endorse or assume any responsibility for any such resources or promotions. If you access any such resources or participate in any such promotions, you do so at your own risk, and you understand that the Terms do not apply to your dealings or relationships with any third parties. You expressly relieve us of any and all liability arising from your use of any such resources or participation in any such promotions.
## 10. Release of Claims
You expressly agree that you assume all risks in connection with your access and use of the Interface. You further expressly waive and release us from any and all liability, claims, causes of action, or damages arising from or in any way relating to your access and use of the Interface.
## 11. Indemnity
You agree to hold harmless, release, defend, and indemnify us and our officers, directors, employees, contractors, agents, affiliates, and subsidiaries from and against all claims, damages, obligations, losses, liabilities, costs, and expenses arising from: (a) your access and use of the Interface; (b) your violation of the Terms, the rights of any third party, or any other applicable law, rule, or regulation; and (c) any other party’s access and use of the Interface with your assistance or using any device or account that you own or control.
## 12. Limitation of Liability
Under no circumstances shall we or any of our officers, directors, employees, contractors, agents, affiliates, or subsidiaries be liable to you for any indirect, punitive, incidental, special, consequential, or exemplary damages, including (but not limited to) damages for loss of profits, goodwill, use, data, or other intangible property, arising out of or relating to any access or use of the Interface, nor will we be responsible for any damage, loss, or injury resulting from hacking, tampering, or other unauthorized access or use of the Interface or the information contained within it. We assume no liability or responsibility for any: (a) errors, mistakes, or inaccuracies of content; (b) personal injury or property damage, of any nature whatsoever, resulting from any access or use of the Interface; (c) unauthorized access or use of any secure server or database in our control, or the use of any information or data stored therein; (d) interruption or cessation of function related to the Interface; (e) bugs, viruses, trojan horses, or the like that may be transmitted to or through the Interface; (f) errors or omissions in, or loss or damage incurred as a result of the use of, any content made available through the Interface; and (g) the defamatory, offensive, or illegal conduct of any third party. Under no circumstances shall we or any of our officers, directors, employees, contractors, agents, affiliates, or subsidiaries be liable to you for any claims, proceedings, liabilities, obligations, damages, losses, or costs in an amount exceeding the amount you paid to us in exchange for access to and use of the Interface, or $100.00, whichever is lesser. This limitation of liability applies regardless of whether the alleged liability is based on contract, tort, negligence, strict liability, or any other basis, and even if we have been advised of the possibility of such liability. Some jurisdictions do not allow the exclusion of certain warranties or the limitation or exclusion of certain liabilities and damages. Accordingly, some of the disclaimers and limitations set forth in the Terms may not apply to you. This limitation of liability shall apply to the fullest extent permitted by law.
## 13. Dispute Resolution
We will use our best efforts to resolve any potential disputes through informal, good faith negotiations. If a potential dispute arises, you must contact us by sending an email to so that we can attempt to resolve it without resorting to formal dispute resolution. If we are not able to reach an informal resolution within sixty days of your email, then you and we both agree to resolve the potential dispute according to the process set forth below. Any claim or controversy arising out of or relating to the Interface, the Terms, or any other acts or omissions for which you may contend that we are liable, including (but not limited to) any claim or controversy as to arbitrability (“Dispute”), shall be decided solely and exclusively by binding arbitration in the State of Delaware., administered by JAMS. Such arbitration shall be conducted in accordance with the then prevailing JAMS Streamlined Arbitration Rules & Procedures, with the following exceptions to such rules if in conflict: (a) one arbitrator shall be chosen by JAMS; (b) each party to the arbitration will pay an equal share of the expenses and fees of the arbitrator, together with other expenses of the arbitration incurred or approved by the arbitrator; and (c) arbitration may proceed in the absence of any party if written notice (pursuant to JAMS’ rules and regulations) of the proceedings has been given to such party. The parties agree to abide by all decisions and awards rendered in such proceedings. Such decisions and awards rendered by the arbitrator shall be final and conclusive. All such controversies, claims or disputes shall be decided in this manner in lieu of any action at law or equity. IF FOR ANY REASON THIS ARBITRATION CLAUSE BECOMES NOT APPLICABLE, THEN EACH PARTY (A) TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, HEREBY IRREVOCABLY WAIVES ALL RIGHT TO TRIAL BY JURY AS TO ANY ISSUE RELATING HERETO IN ANY ACTION, PROCEEDING OR COUNTERCLAIM ARISING OUT OF OR RELATING TO THIS SAFE OR ANY OTHER MATTERS INVOLVING THE PARTIES AND (B) SUBMITS TO THE EXCLUSIVE JURISDICTION AND VENUE OF THE FEDERAL OR DISTRICT COURTS LOCATED IN THE STATE OF DELAWARE., AND EACH PARTY AGREES NOT TO INSTITUTE ANY SUCH ACTION OR PROCEEDING IN ANY OTHER COURT IN ANY OTHER JURISDICTION. Each party irrevocably and unconditionally waives any objection that it may now or hereafter have to the laying of venue of any action or proceeding arising out of or relating to this Safe in the courts referred to in this Section 13.
## 14. Class Action and Jury Trial Waiver
You must bring any and all Disputes against us in your individual capacity and not as a plaintiff in or member of any purported class action, collective action, private attorney general action, or other representative proceeding. This provision applies to class arbitration. You and we both agree to waive the right to demand a trial by jury.
## 15. Governing Law
You agree that the laws of the state of Delaware, without regard to principles of conflict of laws, govern the Terms and any Dispute between you and us.
## 16. Force Majeure
We shall not be liable for delays, failure in performance or interruption of service which result directly or indirectly from any cause or condition beyond our reasonable control, including but not limited to, significant market volatility, any delay or failure due to any act of God, act of civil or military authorities, act of terrorists, civil disturbance, war, strike or other labor dispute, fire, interruption in telecommunications or Internet services or network provider services, failure of equipment and/or software, other catastrophe or any other occurrence which is beyond our reasonable control and shall not affect the validity and enforceability of any remaining provisions.
## 17. Entire Agreement
The Terms, including the Privacy Policy, constitute the entire agreement between you and us with respect to the subject matter hereof, including the Interface. The Terms, including the Privacy Policy, supersede any and all prior or contemporaneous written and oral agreements, communications and other understandings relating to the subject matter of the Terms.
## 18. Privacy Policy
The Privacy Policy describes the ways we collect, use, store and disclose your personal information. You agree to the collection, use, storage, and disclosure of your data in accordance with the Privacy Policy.
# Privacy Policy
Last updated July 23, 2021
This Privacy Policy (“Policy”) describes how Shipyard Software Inc. (“Shipyard,” “we,” “us” or “our”) may collect, use and disclose information, and your choices regarding this information. Please read this Policy carefully before using the Clipper automated market maker protocol (“Clipper”) and contact us with questions at [support@shipyardsoftware.org](mailto:privacy@shipyardsoftware.org).
**APPLICABILITY OF THIS POLICY**
This Policy applies to our services, which include the services we provide on or any other websites, pages, features, mobile applications, or content we own or operate (collectively, the “Sites”) or when you use any Clipper API or third party applications relying on such an API, and related services (collectively, the “Services”). If you do not agree with the terms of this Policy, do not access or use the Services, Sites, or any other aspect of our business.
**WHAT WE COLLECT**
When you interact with our Services, we may collect:
* Financial Information, such as your Ethereum wallet address and information, transaction history, and associated fees paid.
* Transaction Information, such as information about the transactions you make on our Services, such as the type of transaction, transaction amount, and timestamp.
* Correspondence, such as your feedback, questionnaire and other survey responses, and information you provide to our support teams, including via our help chat.
* Online Identifiers, such as geo location/tracking details, browser fingerprint, operating system, browser name and version, and/or personal IP addresses.
* Usage Data, such as user preferences and other data collected via cookies and similar technologies.
* Information from cookies and other tracking technologies. We, and third parties we authorize, may Sites and mobile apps, and collect information about the use of the Services, as well as about our interactions with you. This information may include internet protocol (IP) addresses, browser type, internet service provider (ISP), referring/exit pages, operating system, date/time stamp, and clickstream data, and information about your interactions with the communications we send to you. We may combine this automatically collected log information with other information we collect about you. You may choose to set your web browser to refuse cookies, or to alert you when cookies are being sent. If you do so, please note that some parts of our Services may not function properly.
**HOW WE USE INFORMATION**
We use your information in accordance with your instructions, including any applicable terms in the Terms of Use, and as required by applicable law. We may also use the information we collect for:
**Providing Services and Features**
We may use the information we collect to provide, personalize, maintain, and improve our products and Services, including as we described in the Terms of Use. This includes using information to:
* operate, maintain, customize, measure, and improve our Services, and manage our business;
* process transactions;
* send information, including confirmations, notices, updates, security alerts, and support and administrative messages; and
* to create de-identified or aggregated data.
**Safety and Security**
We may use your information to help maintain the safety, security, and integrity of you and our Services, including to:
* protect, investigate, and deter against fraudulent, unauthorized, or illegal activity;
* monitor and verify identity or service access, combat spam, malware or security risks;
* perform internal operations necessary to provide our Services, including to troubleshoot software bugs and operational problems;
* enforce our agreements with third parties, and address violations of our Terms of Use or agreements for other Services; and
* comply with applicable security laws and regulations.
**User Support**
We may use information we collect to provide support, including to:
* direct questions to the appropriate support person;
* investigate and address user concerns; and
* monitor and improve our customer support responses and processes.
**Research and Development**
We may use the information we collect for testing, research, analysis, and product development to improve your experience. This helps us to improve and enhance the safety and security of our Services, improve our ability to prevent the use of our Services for illegal or improper purposes and develop new features and products relating to our Services.
**Legal and Regulatory Compliance**
We may verify your identity by comparing the personal information you provide against third-party databases and public records. We may use the information we collect to investigate or address claims or disputes relating to use of our Services, or as otherwise allowed by applicable law, or as requested by regulators, government entities, and official inquiries.
**Direct Marketing**
We may use the information we collect to market our Services to you. This may include sending you communications about our Services, features, promotions, surveys, news, updates, and events, and managing your participation in these promotions and events. If you do not want us to send you marketing communications, please opt out by selecting “unsubscribe” to any marketing email sent by us or by contacting us at .
**HOW WE SHARE & DISCLOSE INFORMATION**
We may share your information in the following circumstances:
* With Your Consent. For example, you may let us share personal information with others for their own marketing uses. Those uses will be subject to their privacy policies.
* To Comply with Our Legal Obligations. We may share your information: (A) to cooperate with government investigations; (B) when we are compelled to do so by a subpoena, court order, or similar legal procedure; (C) when we believe in good faith that the disclosure of personal information is necessary to prevent harm to another person; (D) to report suspected illegal activity; or (E) to investigate violations of our User Agreement or any other applicable policies.
* With Service Providers. We may share your information with service providers who help facilitate business and compliance operations such as marketing and technology services. Our contracts require these service providers to only use your information in connection with the services they perform for us.
* During a Change to Our Business. If we engage in a merger, acquisition, bankruptcy, dissolution, reorganization, sale of some or all of our assets or stock, financing, public offering of securities, acquisition of all or a portion of our business, a similar transaction or proceeding, or steps in contemplation of such activities, some or all of your information may be shared or transferred, subject to standard confidentiality arrangements.
* Aggregated or De-identified Data. We may share aggregated and/or anonymized data with others for their own uses.
**DATA RETENTION**
To view or update your information, contact us at . We store your information throughout the life of your use of the Clipper and retain your information for a minimum of five years to comply with our legal obligations or to resolve disputes. If you cease using Clipper, we will neither use your information for any further purposes, nor sell or share your information with third parties, except as necessary to prevent fraud and assist law enforcement, as required by law, or in accordance with this Policy.
**SECURITY**
We maintain administrative, technical, and physical safeguards designed to protect the personal information we maintain against unauthorized access or disclosure. No system can be completely secure. Therefore, although we take steps to secure your information, we cannot guarantee that your information, searches, or other communication will always remain secure. You are responsible for all activity on Clipper relating to any of your Ethereum network addresses and/or cryptocurrency wallets.
**AGE LIMITATIONS**
To the extent prohibited by applicable law, we do not allow use of our Services and Sites by anyone younger than the legal age in the jurisdiction in which the user resides. If you learn that anyone younger than the legal age has unlawfully provided us with personal data, please contact us at and we will take steps to delete such information, close any such accounts, and, to the extent possible, prevent the user from continuing to use our Services.
**CHANGES TO THIS POLICY**
If we make any changes, we will change the Last Updated date above. We encourage you to review this Policy to stay informed. If we make material changes, we will provide additional notice, such as via the email specified in your account or through the Services or Sites.
**ONLINE TRACKING OPT-OUT GUIDE**
Like many companies online, we use services provided by Google and other companies that use tracking technology. These services rely on tracking technologies—such as cookies and web beacons—to collect directly from your device information about your browsing activities, your interactions with websites, and the device you are using to connect to the Internet. There are a number of ways to opt out of having your online activity and device data collected through these services, which we have summarized below:
* Blocking cookies in your browser. Most browsers let you remove or reject cookies, including cookies used for interest-based advertising. To do this, follow the instructions in your browser settings. Many browsers accept cookies by default until you change your settings. For more information about cookies, including how to see what cookies have been set on your device and how to manage and delete them, visit [www.allaboutcookies.org](http://www.allaboutcookies.org).
* Blocking advertising ID use in your mobile settings. Your mobile device settings may provide functionality to limit use of the advertising ID associated with your mobile device for interest-based advertising purposes. Using privacy plug-ins or browsers. You can block our websites from setting cookies used for interest-based ads by using a browser with privacy features.
* Platform opt-outs. The following advertising partner offers opt-out features that let you opt-out of use of your information for interest-based advertising — Google: . Advertising industry opt-out tools. You can also use the opt-out options set forth below to limit use of your information for interest-based advertising by participating companies. Note that because these opt-out mechanisms are specific to the device or browser on which they are exercised, you will need to opt out on every browser and device that you use. Digital Advertising Alliance: Network Advertising Initiative:
**NOTICE TO CALIFORNIA RESIDENTS**
We are required by the California Consumer Privacy Act of 2018 (“CCPA”) to provide this CCPA Notice to California residents to explain how we collect, use and share their personal information, and the rights and choices we offer California residents regarding our handling of their personal information.
**CCPA Scope and Exclusions**
This CCPA Notice, including the description of our Privacy Practices and your Privacy Rights, apply only to California residents whose interactions with us are limited to:
* visiting our consumer websites; and
* signing up for email alerts; and
This CCPA Notice does not apply to the personal information we collect, use or disclose about:
* individuals who provide information to us to initiate or complete the process of interacting with our platform, which are subject to the notice set forth in the Additional Disclosure section of this Policy; or
* representatives of businesses that seek to obtain our products or services, or to provide products or services to us.
**Privacy Practices**
We do not “sell” the personal information we collect (as such term is defined in the CCPA) for monetary value (and will not sell it without providing a right to opt out). Like many companies, we may use third-party cookies for our advertising purposes. If you would like to learn how you may opt out of our use of cookies and other tracking technologies, please review the instructions provided in the Online Tracking Opt-out Guide section of this Policy.
**Privacy Rights**
The CCPA grants individuals the following rights:
* Information. You can request information about how we have collected, used and shared your personal information during the past 12 months. For details about the personal information we have collected over the last 12 months, including the categories of sources, please see the What We Collect section of this Policy. We collect this information for the business and commercial purposes described in the How We Use Information section of this Policy. We share this information with the categories of third parties described in the How We Share and Disclose Information section of this Policy.
* Access. You can request a copy of the personal information that we maintain about you.
* Deletion. You can ask us to delete the personal information that we collected or maintain about you.
Please note that the CCPA limits these rights by, for example, prohibiting us from providing certain sensitive information in response to an access request and limiting the circumstances in which we must comply with a deletion request. We will also respond to requests for information and access only to the extent we are able to associate with a reasonable effort the information we maintain with the identifying details you provide in your request. If we deny your request, we will communicate our decision to you. You are entitled to exercise the rights described above free from discrimination.
**How to Submit a Request**
To request access to or deletion of personal information to .
**Identity Verification**
The CCPA requires us to verify the identity of the individual submitting a request to access or delete personal information before providing a substantive response to the request. We will ask you to verify your identity when you submit a request.
**Authorized Agents**
California residents can empower an “authorized agent” to submit requests on their behalf. We will require the authorized agent to have a written authorization confirming that authority.
**ADDITIONAL DISCLOSURE FOR OUR CONSUMERS AND CUSTOMERS**
This Additional Disclosure governs our collection, use and sharing of personal information that users provide to us to initiate or complete the process of interacting with Clipper. To the extent there are conflicting provisions between this Additional Disclosure and other sections of the Privacy Policy, the Additional Disclosure will govern.
The types of personal information we collect and share can include:
* Contact details
* Transaction history
* Cryptocurrency balances and wallets When you are no longer our customer, we continue to share your information as described in this notice.
**Reasons We Can Share Your Personal Information**
We need to share users’ personal information to operate certain aspects of Clipper and our business. Below, whether we share your personal information, the reasons we share your personal information and whether you can limit this sharing
* We share users’ personal information for our everyday business purposes, such as to process and match your orders and respond to court orders and legal investigations. You cannot limit our sharing of this information.
* We share users’ personal information for our marketing purposes, such as to offer our products and services to you. You cannot limit our sharing of this information.
* We do not share users’ personal information for joint marketing with financial companies.
* We do not share users’ personal information for our affiliates’ everyday business purposes.
* We do not share users’ personal information for our affiliates to market to you.
* We do not share users’ personal information for nonaffiliates to market to you.
**How Does Shipyard Protect My Personal Information?**
To protect your personal information from unauthorized access and use, we use security measures that comply with federal law. These measures include computer safeguards and secured files and buildings.
**How Does Shipyard Collect My Personal Information?**
We collect your personal information, for example, when you deposit Digital Assets in Clipper, make transactions using the Clipper, or withdraw Digital Assets from Clipper. We may also collect your personal information from other companies.
**Why Can’t I Limit All Sharing?**
Applicable laws give you the right to limit only (1) sharing for affiliates’ everyday business purposes, (2) affiliates from using your information to market to you, and (3) share for nonaffiliates to market to you. We do not share any information to any of those parties for those reasons; thus, you may not limit sharing of information.
State laws and individual companies may give you additional rights to limit sharing. See below for more on your rights under state law.
As used in this Additional Disclosure section, “affiliates” refer to companies related by common ownership or control; “nonaffiliates” refer to companies no related by common ownership or control; and “joint marketing” refers to a formal agreement between nonaffiliated financial companies that together market financial products or services to you.
**CONTACT US**
Please contact us if you have any questions about this Policy or if you are seeking to exercise any of your statutory rights. We will respond within a reasonable timeframe. You may contact us at .