Auction Relayer API

wss://relayer.sapience.xyz/auction

ws.send(
  JSON.stringify({
    type: 'identify',
    payload: {
      service: 'my-vault-bot',
      instanceId: '<stable-per-process-uuid>',
      chainId: 5064014,
      version: '1.0.0',
    },
  })
);

Predictor                    Relayer                  Counterparty (vault)
    │                           │                            │
    │── auction.start ─────────▶│                            │
    │◀─ auction.ack ────────────│                            │
    │                           │── auction.started ────────▶│
    │                           │                            │
    │                           │◀──────────── bid.submit ───│
    │                           │── bid.ack ────────────────▶│
    │◀─ auction.bids ───────────│                            │
    │                           │                            │
    │  (predictor selects a bid, calls escrow.mint() on-chain)

import WebSocket from 'ws';
import { privateKeyToAccount } from 'viem/accounts';
import { buildAuctionIntentTypedData } from '@sapience/sdk/auction/escrowSigning';
import { contracts } from '@sapience/sdk/contracts';
 
const chainId = 5064014;
const escrowContract = contracts.predictionMarketEscrow[chainId].address;
const predictor = privateKeyToAccount('0x...');
 
const picks = [
  {
    conditionResolver: '0x49E848A5aBb356c40b025e05Dd0F7eFE95721d55',
    conditionId: '0x...',
    predictedOutcome: 1, // 0 = NO, 1 = YES
  },
];
 
const predictorCollateral = 1_000_000_000_000_000_000n; // 1 wUSDe (18 dec)
const predictorNonce = BigInt(Date.now());
const predictorDeadline = BigInt(Math.floor(Date.now() / 1000) + 600);
 
const typedData = buildAuctionIntentTypedData({
  picks,
  predictor: predictor.address,
  predictorCollateral,
  predictorNonce,
  predictorDeadline,
  verifyingContract: escrowContract,
  chainId,
});
 
const intentSignature = await predictor.signTypedData(typedData);
 
const ws = new WebSocket('wss://relayer.sapience.xyz/auction');
ws.on('open', () => {
  ws.send(
    JSON.stringify({
      type: 'auction.start',
      payload: {
        picks: picks.map((p) => ({
          conditionResolver: p.conditionResolver,
          conditionId: p.conditionId,
          predictedOutcome: p.predictedOutcome,
        })),
        predictor: predictor.address,
        predictorCollateral: predictorCollateral.toString(),
        predictorNonce: Number(predictorNonce),
        predictorDeadline: Number(predictorDeadline),
        intentSignature,
        chainId,
        escrowContract,
      },
    })
  );
});

import { buildCounterpartyMintTypedData } from '@sapience/sdk/auction/escrowSigning';
 
ws.on('message', async (raw) => {
  const msg = JSON.parse(String(raw));
  if (msg.type !== 'auction.started') return;
 
  const auction = msg.payload; // AuctionDetails
  const counterpartyCollateral = pickQuote(auction); // your strategy
  const counterpartyNonce = BigInt(Date.now());
  const counterpartyDeadline = BigInt(Math.floor(Date.now() / 1000) + 60);
 
  const typedData = buildCounterpartyMintTypedData({
    picks: auction.picks,
    predictorCollateral: BigInt(auction.predictorCollateral),
    counterpartyCollateral,
    predictor: auction.predictor,
    counterparty: counterparty.address,
    counterpartyNonce,
    counterpartyDeadline,
    verifyingContract: auction.escrowContract,
    chainId: auction.chainId,
  });
 
  const counterpartySignature = await counterparty.signTypedData(typedData);
 
  ws.send(
    JSON.stringify({
      type: 'bid.submit',
      payload: {
        auctionId: auction.auctionId,
        counterparty: counterparty.address,
        counterpartyCollateral: counterpartyCollateral.toString(),
        counterpartyNonce: Number(counterpartyNonce),
        counterpartyDeadline: Number(counterpartyDeadline),
        counterpartySignature,
      },
    })
  );
});

/**
 * Step 1: RFQ intent — predictor broadcasts intent, no signature, no counterparty info.
 * The vault determines counterpartyCollateral (the quote).
 */
interface AuctionRFQPayload {
  picks: PickJson[];
  predictorCollateral: string;
  counterpartyCollateral?: string;
  predictor: string;
  predictorNonce: number;
  predictorDeadline: number;
  intentSignature?: string;
  chainId: number;
  escrowContract: string;
  refCode?: string;
  predictorSessionKeyData?: string;
  predictorSponsor?: string;
  predictorSponsorData?: string;
}

/**
 * Escrow bid payload - counterparty fills an auction
 */
interface BidPayload {
  auctionId: string;
  counterparty: string;
  counterpartyCollateral: string;
  counterpartyNonce: number;
  counterpartyDeadline: number;
  counterpartySignature: string;
  counterpartySessionKeyData?: string;
}

/** Broadcast to vaults when an auction starts — no counterpartyCollateral (vault decides) */
interface AuctionDetails {
  auctionId: string;
  picks: PickJson[];
  predictorCollateral: string;
  counterpartyCollateral?: string;
  predictor: string;
  predictorNonce: number;
  predictorDeadline: number;
  intentSignature?: string;
  predictorSessionKeyData?: string;
  chainId: number;
  escrowContract: string;
  createdAt: string;
  predictorSponsor?: string;
  predictorSponsorData?: string;
}

/** Bid that has been validated */
interface ValidatedBid {
  auctionId: string;
  counterparty: string;
  counterpartyCollateral: string;
  counterpartyNonce: number;
  counterpartyDeadline: number;
  counterpartySignature: string;
  counterpartySessionKeyData?: string;
  receivedAt: string;
}

/**
 * Client identity announced after WS connect. Backwards-compatible:
 * relayer treats clients without identify as anonymous.
 *
 * Three identity layers stack here:
 *   - clientId  (assigned by relayer per WS connection — changes on every reconnect)
 *   - instanceId (assigned by client per process — stable across reconnects, changes on restart)
 *   - service   (logical service name — non-unique by design)
 */
interface IdentifyPayload {
  service: string;
  instanceId: string;
  chainId?: number;
  bootAt?: number;
  version?: string;
  deploymentId?: string;
  replicaId?: string;
  /**
   * Optional human-readable label for the deployment hosting this process
   * (e.g. Railway service name). Distinguishes two deployments that share the
   * same logical `service` — for instance an `auction-bidder` running the Pyth
   * pricing strategy vs the default strategy in a separate Railway service.
   */
  serviceInstance?: string;
  /**
   * Optional bounded label for which strategy/vault flavor this bot serves
   * (e.g. `'default'`, `'pyth'`, `'experimental'`). Lets metrics break out
   * `auction-bidder` connections by which vault they bid against without
   * exploding cardinality. Relayer collapses any value outside its allowlist
   * to `'unknown'`.
   */
  variant?: string;
}

/** Optional ack a client sends on receiving auction.started — proves end-to-end delivery. */
interface AuctionReceivedPayload {
  auctionId: string;
}

type ClientToServerMessage =
  | {
      type: 'auction.start';
      payload: AuctionRFQPayload;
    }
  | {
      type: 'auction.subscribe';
      payload: {
        auctionId: string;
      };
    }
  | {
      type: 'auction.unsubscribe';
      payload: {
        auctionId: string;
      };
    }
  | {
      type: 'bid.submit';
      payload: BidPayload;
    }
  | {
      type: 'identify';
      payload: IdentifyPayload;
    }
  | {
      type: 'auction.received';
      payload: AuctionReceivedPayload;
    }
  | {
      type: 'ping';
    };

type ServerToClientMessage =
  | {
      type: 'auction.ack';
      payload: {
        auctionId?: string;
        error?: string;
        subscribed?: boolean;
        unsubscribed?: boolean;
        id?: string;
      };
    }
  | {
      type: 'bid.ack';
      payload: {
        bidId?: string;
        error?: string;
      };
    }
  | {
      type: 'auction.started';
      payload: AuctionDetails;
    }
  | {
      type: 'auction.bids';
      payload: {
        auctionId: string;
        bids: ValidatedBid[];
      };
    }
  | {
      type: 'auction.filled';
      payload: {
        auctionId: string;
        predictionId: string;
        pickConfigId: string;
        transactionHash: string;
      };
    }
  | {
      type: 'auction.expired';
      payload: {
        auctionId: string;
        reason: string;
      };
    }
  | {
      type: 'pong';
    }
  | {
      type: 'error';
      payload: {
        message: string;
        code?: string;
      };
    };

/**
 * Secondary auction request - seller lists position tokens for sale
 * Seller signs the trade approval, bots compete to fill as buyer
 */
interface SecondaryAuctionRequestPayload {
  token: string;
  collateral: string;
  tokenAmount: string;
  seller: string;
  sellerNonce: number;
  sellerDeadline: number;
  sellerSignature: string;
  chainId: number;
  escrowContract: string;
  refCode?: string;
  sellerSessionKeyData?: string;
  /** When true, this is a price discovery request — not a real listing.
   *  Relayer will exclude it from the listings snapshot and include quoteOnly
   *  on feed broadcasts so observers can identify it as quote traffic.
   *  The vault quoter responds with a simplified price. */
  quoteOnly?: boolean;
}

/**
 * Secondary bid - buyer offers to purchase position tokens
 */
interface SecondaryBidPayload {
  auctionId: string;
  buyer: string;
  price: string;
  buyerNonce: number;
  buyerDeadline: number;
  buyerSignature: string;
  buyerSessionKeyData?: string;
}

/** Secondary auction details broadcast to subscribers */
interface SecondaryAuctionDetails {
  auctionId: string;
  token: string;
  collateral: string;
  tokenAmount: string;
  seller: string;
  sellerDeadline: number;
  chainId: number;
  escrowContract: string;
  createdAt: string;
  /** True when this is a price discovery request (not a real listing) */
  quoteOnly?: boolean;
}

/** Validated secondary bid */
interface SecondaryValidatedBid {
  auctionId: string;
  buyer: string;
  price: string;
  buyerNonce: number;
  buyerDeadline: number;
  buyerSignature: string;
  buyerSessionKeyData?: string;
  receivedAt: string;
}

/** Listing summary returned in listings snapshot */
interface SecondaryListingSummary {
  auctionId: string;
  token: string;
  collateral: string;
  tokenAmount: string;
  seller: string;
  sellerDeadline: number;
  chainId: number;
  escrowContract: string;
  createdAt: string;
  bidCount: number;
}

type SecondaryClientToServerMessage =
  | {
      type: 'secondary.auction.start';
      payload: SecondaryAuctionRequestPayload;
    }
  | {
      type: 'secondary.auction.subscribe';
      payload: {
        auctionId: string;
      };
    }
  | {
      type: 'secondary.auction.unsubscribe';
      payload: {
        auctionId: string;
      };
    }
  | {
      type: 'secondary.bid.submit';
      payload: SecondaryBidPayload;
    }
  | {
      type: 'secondary.feed.subscribe';
    }
  | {
      type: 'secondary.feed.unsubscribe';
    }
  | {
      type: 'secondary.listings.request';
    }
  | {
      type: 'ping';
    };

type SecondaryServerToClientMessage =
  | {
      type: 'secondary.auction.ack';
      payload: {
        auctionId?: string;
        error?: string;
        subscribed?: boolean;
        unsubscribed?: boolean;
      };
    }
  | {
      type: 'secondary.bid.ack';
      payload: {
        bidId?: string;
        error?: string;
      };
    }
  | {
      type: 'secondary.auction.started';
      payload: SecondaryAuctionDetails;
    }
  | {
      type: 'secondary.auction.bids';
      payload: {
        auctionId: string;
        bids: SecondaryValidatedBid[];
      };
    }
  | {
      type: 'secondary.auction.filled';
      payload: {
        auctionId: string;
        tradeHash: string;
        transactionHash: string;
      };
    }
  | {
      type: 'secondary.auction.expired';
      payload: {
        auctionId: string;
        reason: string;
      };
    }
  | {
      type: 'secondary.listings.snapshot';
      payload: {
        listings: SecondaryListingSummary[];
      };
    }
  | {
      type: 'pong';
    }
  | {
      type: 'error';
      payload: {
        message: string;
        code?: string;
      };
    };