SDK reference
Quoting
Builders and signers for the two messages a desk sends in an opening auction: a sealed bid intent while the RFQ collects, and an executable quote when you win the award. The builders only copy fields. The price is always yours: the SDK has no pricing logic.
How an auction uses these
- An RFQ arrives on your feed. Read its snapshot with
client.getRfqand decode its market (decodeMarketV3). - Within 3 s of the RFQ (
COLLECT_MS), send one bid intent:buildBidIntent,signIntent,client.sendBidIntent. One intent per maker per auction. - The gateway ranks intents by price. The winner gets an
awardwith anawardUntildeadline (at most 3 s,AWARD_MS). - The winner answers with a quote:
buildQuote,signQuote,client.sendQuote, or passes withclient.sendAwardDecline. - The customer's wallet signs and submits the fill. You see it only on chain, as your position PDA (
derivePosition).
covr's markets list only covr's own maker today. Every other desk's bid intent is verified exactly like a real one and then refused with Bid intent verified but not entered: this market does not list this maker yet ("practice mode"). It never wins and never moves a price.
See RFQ lifecycle for the full protocol.
Units used on this page
| Field | Unit |
|---|---|
price | Gross premium per one whole collateral token, in USDC × 10^18 (priceE18), as a decimal string on the wire. 2400000000000000000 is 2.40 USDC per token. |
quantity | Collateral atoms scaled to 18 decimals (quantityE18), decimal string. For JitoSOL (9 decimals), 1 atom is 1000000000. Convert with atomsFromWire. |
strike | Strike in USD × 10^8 (strikeE8), decimal string. 17000000000 is $170. |
expiry, validUntil | Unix seconds, integer number. |
nonce | u64 as a decimal string. |
closesAt, hardDeadline, awardUntil | Epoch milliseconds. |
The gross premium of a fill is atoms × price / 10^(decimals + 12) USDC atoms, and it must be exact. The gateway refuses an intent whose premium is not a whole USDC atom. Round your price with exactPriceAtOrBelow.
BID_INTENT_TYPES
The EIP-712 types of a bid intent.
export declare const BID_INTENT_TYPES: {
BidIntent: {
name: string;
type: string;
}[];
};- Value:
BidIntent(bytes32 auctionId, uint8 kind, bytes32 market, bytes32 position, bytes32 wallet, address assetAddress, uint256 chainId, bool isPut, uint256 strike, uint64 expiry, address maker, uint256 price, uint256 quantity, bool isTakerBuy, uint64 validUntil, address usd, address collateralAsset), in that order. - Where it matters:
signIntentsigns with it, and the gateway verifies with it. The object is not frozen: never modify it.
QUOTE_V2_TYPES
The EIP-712 types of an executable quote. The program rebuilds the same digest at fill.
export declare const QUOTE_V2_TYPES: {
QuoteV2: {
name: string;
type: string;
}[];
};- Value:
QuoteV2(bytes32 auctionId, bytes32 writer, address assetAddress, uint256 chainId, bool isPut, uint256 strike, uint64 expiry, address maker, uint64 nonce, uint256 price, uint256 quantity, bool isTakerBuy, uint64 validUntil, address usd, address collateralAsset), in that order. - Where it matters:
signQuote. The object is not frozen: never modify it.
WITHDRAW_TYPES
The EIP-712 types of a quote withdrawal: WithdrawBid(string rfqId, bytes32 quoteHash).
export declare const WITHDRAW_TYPES: {
WithdrawBid: {
name: string;
type: string;
}[];
};- Value:
{ WithdrawBid: [{ name: 'rfqId', type: 'string' }, { name: 'quoteHash', type: 'bytes32' }] } - Where it matters: only
signWithdrawal, which desks cannot use today.
auctionKey
Hashes an RFQ id into the bytes32 the intent and quote sign: keccak256(utf8(id)).
export declare const auctionKey: (id: string) => string;| Name | Type | Description |
|---|---|---|
id | string | RFQ id: a lowercase UUID v4, for example 3f2b8c1e-5d4a-4e7b-9c2d-1a2b3c4d5e6f. |
Returns: string, 0x plus 64 hex characters.
Throws: Invalid auction ID when id is not a lowercase UUID v4 (uppercase is refused).
import { auctionKey } from '@covrfun/maker-sdk';
auctionKey('3f2b8c1e-5d4a-4e7b-9c2d-1a2b3c4d5e6f');
// '0x7237c0c9e587161e71471ae107a640d9a6f65b26ab32795d70836ee1e90cd42d'defaultIntentValidUntil
Returns the bid intent expiry covr's own maker uses: min(option expiry, ceil(hardDeadline / 1000) + 60).
export declare function defaultIntentValidUntil(snapshot: Pick<RfqSnapshot, 'hardDeadline' | 'request'>): number;| Name | Type | Description |
|---|---|---|
snapshot.hardDeadline | number | Auction hard deadline, epoch ms. |
snapshot.request.expiry | number | Option expiry, unix seconds. |
Returns: number, unix seconds. It always lies after the collection window closes, which buildBidIntent requires.
Throws: nothing. A missing hardDeadline yields NaN, which buildBidIntent then refuses.
import { defaultIntentValidUntil, type RfqSnapshot } from '@covrfun/maker-sdk';
declare const snapshot: RfqSnapshot;
const validUntil = defaultIntentValidUntil(snapshot);buildBidIntent
Builds the unsigned sealed bid intent for an opening RFQ. It copies every instrument field verbatim from the snapshot, because the gateway compares them as exact strings.
export declare function buildBidIntent(snapshot: RfqSnapshot, input: {
maker: string;
price: bigint | string;
validUntil: number;
}): UnsignedBidIntent;| Name | Type | Description |
|---|---|---|
snapshot | RfqSnapshot | From client.getRfq. |
input.maker | string | Your quote key address (0x…). The gateway requires it to equal the key your token is registered to. |
input.price | bigint | string | Gross premium per one whole collateral token, USDC × 10^18. Positive, below 2^128. A string must be a canonical decimal integer. |
input.validUntil | number | Intent expiry, unix seconds. Must be after ceil(closesAt / 1000) and at most request.expiry. |
Returns: UnsignedBidIntent with 17 fields: auctionId (= snapshot.id), kind: 'open', market, position: null, wallet (the writer), assetAddress (= request.asset), chainId, expiry, isPut, isTakerBuy, quantity, strike, usd, collateralAsset, maker, price (decimal string) and validUntil.
It does not check snapshot.status, your clock or the market. Skip RFQs whose status is not collecting or whose closesAt has passed.
Throws:
| Condition | Message |
|---|---|
snapshot.kind is not open, or position is not null | maker-sdk: only open (opening) auctions take bid intents |
snapshot.id is not a lowercase UUID v4 | maker-sdk: invalid auction id |
market or wallet is not a string | maker-sdk: snapshot must carry market and wallet |
price is a string that is not a canonical decimal integer | canonical unsigned integer required |
price is a string of 2^128 or more | integer overflow |
price is zero, negative, or a bigint of 2^128 or more | maker-sdk: price must be a positive u128 priceE18 (USDC per whole token, 18 decimals) |
validUntil is not a safe integer | maker-sdk: validUntil must be integer unix seconds |
validUntil <= ceil(closesAt / 1000) | maker-sdk: validUntil must be after the collection window closes |
validUntil > request.expiry | maker-sdk: validUntil must not exceed the option expiry |
import {
atomsFromWire,
buildBidIntent,
defaultIntentValidUntil,
exactPriceAtOrBelow,
type DecodedMarketV3,
type RfqSnapshot,
} from '@covrfun/maker-sdk';
declare const snapshot: RfqSnapshot;
declare const market: DecodedMarketV3;
declare const quoteKeyAddress: string;
// Your model: USDC x 1e18 per whole collateral token.
declare function myModel(snapshot: RfqSnapshot, market: DecodedMarketV3): Promise<bigint>;
const atoms = atomsFromWire(snapshot.request.quantity, market.collateralDecimals);
const myPriceE18 = await myModel(snapshot, market);
const price = exactPriceAtOrBelow(myPriceE18, atoms, market.collateralDecimals);
if (price === 0n) throw new Error('no exact price at or below the model: skip this RFQ');
const unsigned = buildBidIntent(snapshot, {
maker: quoteKeyAddress,
price,
validUntil: defaultIntentValidUntil(snapshot),
});buildQuote
Builds the unsigned executable quote that answers an award. It takes the maker, price and instrument from your intent, and binds the quote to this auction and to the writer's wallet.
export declare function buildQuote(snapshot: Pick<RfqSnapshot, 'id' | 'wallet'>, intent: UnsignedBidIntent | BidIntent, input: {
nonce: bigint;
validUntil: number;
}): UnsignedQuoteV2;| Name | Type | Description |
|---|---|---|
snapshot.id | string | The RFQ id. Must equal intent.auctionId. |
snapshot.wallet | string | The writer (customer) wallet. Becomes writer. |
intent | BidIntent | Your own stored copy of the intent you signed, never the copy inside the award. |
input.nonce | bigint | A fresh nonce: 0 to 2^64 - 2, at least your on-chain min_nonce, never used before. |
input.validUntil | number | Quote expiry, unix seconds, positive, at most the option expiry. |
Returns: UnsignedQuoteV2 with 15 fields: auctionId, writer, assetAddress, chainId, isPut, strike, expiry, maker, nonce (decimal string), price, quantity, isTakerBuy, validUntil, usd, collateralAsset.
Beyond what this function checks, the quote must also pass:
- the gateway:
now < validUntil <= now + 60on its clock, and the award not yet expired; - the program at fill: chain clock
< validUntil,validUntil <= expiry,nonce >= min_nonce, and the position PDA for this nonce not existing yet.
Leave a few seconds of margin: covr's example bot uses min(expiry, now + 55).
Write the nonce, terms and the cash it can cost to durable storage before you sign. A reply that times out can still mean a live quote, and only the chain settles it.
Throws:
| Condition | Message |
|---|---|
intent.auctionId !== snapshot.id | maker-sdk: intent belongs to another auction |
nonce is not a bigint in [0, 2^64 - 2] | maker-sdk: nonce must be a u64 below 2^64-1 (that value is reserved) |
validUntil not a positive safe integer, or after intent.expiry | maker-sdk: validUntil must be unix seconds no later than the option expiry |
If the award's intent is not the one you stored, decline it at once. Throwing or staying silent holds the award until the hard deadline, and the customer gets no quote.
import {
buildQuote,
REVIEW_SECONDS,
type Award,
type BidIntent,
type GatewayClient,
type RfqSnapshot,
} from '@covrfun/maker-sdk';
declare const client: GatewayClient;
declare const snapshot: RfqSnapshot;
declare const myIntent: BidIntent; // the intent you signed and stored for award.id
declare function reserveNonceDurably(): Promise<bigint>; // your journal: fsync before signing
async function onAward(award: Award) {
if (JSON.stringify(myIntent) !== JSON.stringify(award.intent)) {
await client.sendAwardDecline(award.id, award.intent.signature); // pass it on now
return;
}
const nonce = await reserveNonceDurably();
const now = Math.floor(Date.now() / 1000);
const unsignedQuote = buildQuote(snapshot, myIntent, {
nonce,
validUntil: Math.min(snapshot.request.expiry, now + REVIEW_SECONDS - 5),
});
// Sign with signQuote, then client.sendQuote(myIntent.signature, quote).
}signIntent
Signs a bid intent with your quote key in the market's domain. Returns the exact 18-field object to send as bid_intent params.
export declare function signIntent(signer: TypedDataSigner, domain: TypedDataDomain, intent: UnsignedBidIntent): Promise<BidIntent>;| Name | Type | Description |
|---|---|---|
signer | TypedDataSigner | Your quote key. |
domain | TypedDataDomain | quoteDomain of the RFQ's market. |
intent | UnsignedBidIntent | From buildBidIntent. Exactly the 17 unsigned fields (a signature key is ignored). |
Returns: BidIntent: the 17 fields in canonical order plus signature (lowercase 0x-hex, 65 bytes).
Throws:
| Condition | Message |
|---|---|
intent is not an object | maker-sdk: intent object required |
| Any field missing or extra | maker-sdk: intent must have exactly the 17 unsigned bid intent fields |
auctionId is not a lowercase UUID v4 | Invalid auction ID |
market, wallet or position is not a valid Solana key | SolanaError from @solana/kit |
An address or uint field is malformed | an ethers encoding error |
| Signature malformed or high-s | see assertCanonicalSignature |
| Signature recovers to another key | maker-sdk: signature recovers to <recovered>, not the maker <maker> |
import { quoteDomain, signIntent, type DecodedMarketV3, type TypedDataSigner, type UnsignedBidIntent } from '@covrfun/maker-sdk';
declare const signer: TypedDataSigner;
declare const market: DecodedMarketV3;
declare const unsigned: UnsignedBidIntent; // from buildBidIntent
const intent = await signIntent(signer, quoteDomain(market), unsigned);
// Store `intent` by RFQ id before sending it: you answer the award from this copy.signQuote
Signs an executable quote in the market's domain. Returns the exact 16-field object to send as the quote param.
export declare function signQuote(signer: TypedDataSigner, domain: TypedDataDomain, quote: UnsignedQuoteV2): Promise<QuoteV2>;| Name | Type | Description |
|---|---|---|
signer | TypedDataSigner | Your quote key. |
domain | TypedDataDomain | quoteDomain of the RFQ's market. The program verifies the signature in the same domain at fill. |
quote | UnsignedQuoteV2 | From buildQuote. Exactly the 15 fields. |
Returns: QuoteV2: the 15 fields plus signature (lowercase 0x-hex).
Throws:
| Condition | Message |
|---|---|
quote is not an object | quote object required |
| Fields missing or extra | Unsupported quote schema |
auctionId or writer missing | maker-sdk: QuoteV2 (with auctionId and writer) required |
auctionId is not a lowercase UUID v4 | Invalid auction ID |
writer is not a valid Solana key | SolanaError from @solana/kit |
| Signature malformed or high-s | see assertCanonicalSignature |
| Signature recovers to another key | maker-sdk: signature recovers to <recovered>, not the maker <maker> |
import { signQuote, quoteDomain, type DecodedMarketV3, type TypedDataSigner, type UnsignedQuoteV2 } from '@covrfun/maker-sdk';
declare const signer: TypedDataSigner;
declare const market: DecodedMarketV3;
declare const unsignedQuote: UnsignedQuoteV2; // from buildQuote, journaled first
const quote = await signQuote(signer, quoteDomain(market), unsignedQuote);signWithdrawal
Signs the body of a quote withdrawal: WithdrawBid(rfqId, keccak256(quote signature)).
export declare function signWithdrawal(signer: TypedDataSigner, domain: TypedDataDomain, quote: Pick<QuoteV2, 'auctionId' | 'maker' | 'signature'>): Promise<{
quoteSignature: string;
signature: string;
}>;Desks cannot use this today. The gateway serves the withdrawal route only to covr's own maker, not on the desk listener. A withdrawal would never cancel a quote on chain anyway. For an immediate, reversible stop, pause your mint policy (Cancel quotes). To cancel signed quotes for good, raise min_nonce with configureMaker.
| Name | Type | Description |
|---|---|---|
signer | TypedDataSigner | The quote's maker key. |
domain | TypedDataDomain | The quote's market domain. |
quote | Pick<QuoteV2, 'auctionId' | 'maker' | 'signature'> | The signed quote to withdraw. |
Returns: { quoteSignature, signature }: the quote's signature and the withdrawal signature (lowercase).
Throws:
| Condition | Message |
|---|---|
quote is not an object or auctionId is not a lowercase UUID v4 | maker-sdk: invalid auction id |
quote.signature malformed or high-s | see assertCanonicalSignature |
The new signature recovers to another key than quote.maker | maker-sdk: signature recovers to <recovered>, not the maker <maker> |
import { signWithdrawal, type QuoteV2, type TypedDataSigner } from '@covrfun/maker-sdk';
import type { TypedDataDomain } from 'ethers';
declare const signer: TypedDataSigner;
declare const domain: TypedDataDomain;
declare const quote: QuoteV2;
const body = await signWithdrawal(signer, domain, quote);