Creating Auctions

Learn how to create and configure auctions programmatically via the API

Prerequisites

✓ A Developer or Agent API key
✓ Ownership of the SNS domain(s) in the wallet tied to your API key
✓ Sufficient SOL balance to pay the on-chain transaction fee

How Transaction Signing Works

The API builds an unsigned Solana transaction and returns it as a base64 string. You must sign and broadcast it yourself — the server never holds your private key.

Call POST /api/v1/auctions/create → receive transaction (base64)
Decode the base64 string into a Solana Transaction object
Sign with the seller wallet (must match the wallet that owns the listed domains)
Broadcast to Solana via your RPC endpoint

Auction Types

Standard Auction

Traditional English auction. Highest bidder wins after time expires.

• Best for: Maximum exposure
• Starting bid required
• Duration: 15 min to 30 days

Dutch Auction

Price descends over time. First buyer wins at current price. Settles instantly via place_bid — no separate settle call needed.

• Best for: Quick sales
• Starting price → floor price over time
• Requires dutchEndPrice

Reserve Price Auction

Standard auction with a hidden reserve. If reserve is not met the domain is returned to seller at settlement.

• Best for: Protection from lowballs
• Requires reservePrice

Buy Now

Fixed price listing. First interested buyer wins. Settles instantly via place_bid.

• Best for: Immediate sales
• Requires buyNowPrice

Creating an Auction

Use the POST /api/v1/auctions/create endpoint:

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

// 1. Request unsigned transaction from the API
const res = await fetch('https://snsauctions.xyz/api/v1/auctions/create', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_your_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    domainNames: ['myname.sol'],
    type: 'standard',
    startingPrice: 2.5,
    minBidIncrement: 0.1,
    durationHours: 48
  })
});

const { data } = await res.json();
// data.transaction = base64 unsigned Solana tx
// data.auctionId   = auction PDA (base58) — use as :id in bid/settle

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

console.log('Auction PDA:', data.auctionId);
console.log('Tx:', signature);

Request Parameters

Parameter	Type	Required	Description
domainNames	string[]	Yes	Array of .sol domain names (1–5). All must be owned by the authenticated wallet.
type	string	Yes	'standard' \| 'dutch' \| 'reserve' \| 'buy_now'
startingPrice	number	Yes	Starting price in SOL
minBidIncrement	number	Yes	Minimum raise between bids in SOL
durationHours	number	Yes	Duration in hours (0.25 to 720)
reservePrice	number	No*	Reserve price in SOL (required for 'reserve' type)
buyNowPrice	number	No*	Fixed price in SOL (required for 'buy_now' type)
dutchEndPrice	number	No*	Floor price in SOL for Dutch auctions (required for 'dutch' type)
snipeProtectionEnabled	boolean	No	Extend auction on last-minute bids (default: false)
snipeExtensionSeconds	number	No	Seconds to add when snipe triggered (default: 300)

Response Example

{
  "success": true,
  "data": {
    "auctionId": "7K8mN2qPxR...",   // Auction PDA (base58) — use as :id in bid/settle
    "transaction": "AQAAAAAAAA...", // Base64 unsigned tx — sign and broadcast this
    "seller": "YourWalletAddress...",
    "status": "upcoming",
    "estimatedStartTime": 1711464000000
  },
  "timestamp": 1711463000000
}

Best Practices

1. Choose Duration Wisely

Longer durations (3–7 days) increase exposure and bidding, while shorter durations (12–24 hours) create urgency.

2. Set Realistic Starting Prices

Research comparable sales. Too high and nobody bids, too low and you leave money on the table.

3. Use Reserve Price for Premium Domains

Protects you from selling valuable domains below their worth while still generating bidding excitement.

4. Batch Related Domains

Group related domains in one bundle auction (up to 5) to attract buyers interested in portfolios or cohesive branding.

Common Errors

Domain not owned: The server verifies on-chain ownership before building the transaction. Returns 403 UNAUTHORIZED if the API key wallet does not own every domain in the request.

Domain not found: Domain is not registered on-chain yet. Returns 404 NOT_FOUND.

Invalid domain name: Must be 3–63 characters and end with .sol.

Invalid duration: Duration must be between 15 minutes and 30 days.

Webhooks

Placing Bids

Follow Notify Join Discord