# 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**

<mark style="color:orange;">`function swap(address inputToken, address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;`</mark>

<mark style="color:orange;">`function transmitAndSwap(address inputToken, address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;`</mark>

Observe that the signed quote has all of these values to use, except for <mark style="color:orange;">`auxiliaryData`</mark> which can be set to any string and is used for identification purposes in the event logs.

The difference between <mark style="color:orange;">`swap`</mark> and `transmitAndSwap` is that <mark style="color:orange;">`transmitAndSwap`</mark> starts by transferring <mark style="color:orange;">`inputAmount`</mark> of the <mark style="color:orange;">`inputToken`</mark> from <mark style="color:orange;">`msg.sender`</mark> to the exchange, while <mark style="color:orange;">`swap`</mark> 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](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/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:

<mark style="color:orange;">`function sellTokenForEth(address inputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;`</mark>

<mark style="color:orange;">`function transmitAndSellTokenForEth(address inputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;`</mark>

As with token-to-token swaps, the difference between these functions is that the first assumes that at least <mark style="color:orange;">`inputAmount`</mark> of <mark style="color:orange;">`inputToken`</mark> has already been sent, while the second pulls that input token directly from <mark style="color:orange;">`msg.sender`</mark>. 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:

<mark style="color:orange;">`function sellEthForToken(address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external payable;`</mark>

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](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/swap-native-token-shorttail) and [here](https://docs.clipper.exchange/disclaimers-and-technical/integrating-with-clipper-rfq/guides/integration-examples/swap-shorttail-native-token)&#x20;
{% 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:

<mark style="color:orange;">`function packedTransmitAndSwap(uint256 packedInput, uint256 packedOutput, uint256 packedGoodUntil, bytes32 auxData, bytes32 r, bytes32 vs) external payable;`</mark>

<mark style="color:orange;">`function packedSwap(uint256 packedInput, uint256 packedOutput, uint256 packedGoodUntil, bytes32 auxData, bytes32 r, bytes32 vs) external payable;`</mark>

Similar to the other Clipper functions, use <mark style="color:orange;">`packedTransmitAndSwap`</mark> to transmit the token from <mark style="color:orange;">`msg.sender`</mark> and use <mark style="color:orange;">`packedSwap`</mark> 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 <mark style="color:orange;">`uint256`</mark> 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:

<mark style="color:orange;">`packedInput`</mark>: input amount and contract address

<mark style="color:orange;">`auxData`</mark> - this is a <mark style="color:orange;">`bytes32`</mark> value that is a packed representation of an identifying string, and the <mark style="color:orange;">`destination_address`</mark> (lowest order bytes). The identifying string is emitted as part of <mark style="color:orange;">`Swapped`</mark> event and allows us to attribute trade sourced correctly.

<mark style="color:orange;">`packedOutput`</mark>: output amount and contract address

<mark style="color:orange;">`packedGoodUntil`</mark>: Simply use the <mark style="color:orange;">`good_until`</mark> 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 <mark style="color:orange;">`destination_address`</mark>. 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.