Placing Bids

Learn how to programmatically bid on auctions via the API

How Bidding Works

The API validates the auction state on-chain, then returns an unsigned Solana transaction. You sign it with your bidder wallet and broadcast it to the network.

Call POST /api/v1/auctions/:id/bid → receive transaction (base64)
Sign with the bidder wallet
Broadcast to Solana — your SOL moves on-chain atomically

Bidding Rules

Minimum Bid:

First bid must be ≥ starting price
Subsequent bids must be ≥ current top bid + auction's minBidIncrement

Restrictions:

The auction seller cannot bid on their own listing
Auction must be active (bidding window open)
Your wallet must have sufficient SOL to cover the bid + tx fees

Anti-Snipe Protection

If a bid lands in the snipe window (default: last 60 seconds), the auction timer is extended by the configured amount (default: 300 seconds). This is enforced on-chain by the smart contract.

Placing a Bid

Use the POST /api/v1/auctions/:id/bid endpoint:

import { Transaction, Connection } from '@solana/web3.js';

// The auction :id is the base58-encoded Solana PDA returned by /auctions/create
const auctionId = '7K8mN2qPxR...';

// 1. Request unsigned bid transaction
const res = await fetch(
  `https://snsauctions.xyz/api/v1/auctions/${auctionId}/bid`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_live_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ bidAmount: 3.5 }) // SOL
  }
);

const { data } = await res.json();
// data.transaction     = base64 unsigned tx
// data.nextMinimumBid  = minimum for next bid in SOL

// 2. Sign and broadcast
const connection = new Connection(process.env.RPC_URL);
const tx = Transaction.from(Buffer.from(data.transaction, 'base64'));
tx.sign(bidderKeypair);
const signature = await connection.sendRawTransaction(tx.serialize());
await connection.confirmTransaction(signature, 'confirmed');

console.log('Bid confirmed. Next minimum bid:', data.nextMinimumBid, 'SOL');

Request Parameters

Parameter	Type	Required	Description
bidAmount	number	Yes	Bid amount in SOL. Must be ≥ the current minimum bid.

Response Example

{
  "success": true,
  "data": {
    "transaction": "AQAAAAAAAA...", // Base64 unsigned tx — sign and broadcast this
    "auctionId": "7K8mN2qPxR...",
    "bidder": "YourWalletAddress...",
    "bidAmount": 3.5,
    "nextMinimumBid": 3.6,
    "timestamp": 1711464000000
  },
  "timestamp": 1711463000000
}

Checking Bid Status

Get live auction details to see current bids:

const res = await fetch(
  'https://snsauctions.xyz/api/v1/auctions/7K8mN2qPxR...',
  { headers: { 'X-API-Key': 'sk_live_your_key_here' } }
);

const { data } = await res.json();
console.log('Current price:', data.currentPrice, 'SOL');
console.log('Top bidder:',    data.topBidder);
console.log('Total bids:',    data.totalBids);
console.log('Ends at:',       new Date(data.endTime).toISOString());

Bidding Strategies

Incremental Bidding

Poll the auction periodically and bid only the minimum required. Use nextMinimumBid from the bid response to calculate your next bid.

Snipe Awareness

Check snipeProtectionEnabled and snipeWindowSeconds before placing a bid close to the end time. The auction may extend if you trigger the snipe window.

Dutch Auction Timing

For Dutch auctions, the currentPrice decreases over time. Bid when the price reaches your target — first buyer wins instantly, no separate settle needed.

Common Errors

BID_TOO_LOW: Bid is below the minimum required. Check nextMinimumBid from the previous response.

AUCTION_ENDED: The auction's bidding window has closed. It must be settled before the domain transfers.

INVALID_REQUEST (seller cannot bid): The auction seller wallet cannot place bids on their own listing.

NOT_FOUND: Auction PDA does not exist on-chain. Double-check the auction ID.

Creating Auctions

AI Agent Integration

Follow Notify Join Discord