Developers

OSWiki API

Query the OSWiki orderbook, fetch fulfillment data, and submit signed orders over the public API. Everything the OSWiki marketplace does - browsing listings, buying, listing, bidding - is available programmatically, on Ethereum and ApeChain.

The reference is generated from the live OpenAPI spec - every endpoint can be called directly from the browser with your API key, and each request exports as cURL or code.

Getting started

1. Create an API key in Account → Developer (sign in with your wallet first).
2. Make your first request - listings are public, so this works even without a key:

curl "https://api.oswiki.xyz/v1/listings?collection=otherdeed&sort=price_asc"

Explore every endpoint, schema and example in the API Reference.

Authentication

Pass your key in the X-API-Key header. Read and fulfillment endpoints work without a key at a lower shared limit; submitting and cancelling orders requires one. Order submission itself is authenticated by your wallet signature - the API key only identifies your integration.

curl "https://api.oswiki.xyz/v1/bids?collection=otherdeed" \
  -H "X-API-Key: oswk_..."

Approvals & funding

PaymentProcessor moves assets on your behalf at fill time, so one-time on-chain approvals are required before an order can be created or filled. These are the most common reason a first request is rejected - do them once per collection/token, then reuse.

• Listing an NFT - call setApprovalForAll(PaymentProcessor, true) on the collection. Without it, intake rejects with no_approval.
• Making an offer- offers are paid in the chain's wrapped-native token (address in /v1/orders/params). Wrap enough native, then approve(PaymentProcessor, amount) on that token, or intake rejects with insufficient_balance / insufficient_allowance.
• Buying - no approval needed; a listing is paid in native currency and the value rides with the fill transaction.

Buying

Request buy-data for a listing with the address that will send the transaction as taker (this must be whatever ends up as msg.sender on-chain - a router address if you fill through one). The response contains the signed order plus a fresh cosignature bound to that taker - submit it to PaymentProcessor and the NFT is delivered on-chain. Sweeps work the same way through buy-data-bulk. Poll an order any time with GET /v1/listings/{askId} to see if it is still active or already filled.

curl -X POST "https://api.oswiki.xyz/v1/listings/{askId}/buy-data" \
  -H "Content-Type: application/json" -H "X-API-Key: oswk_..." \
  -d '{"taker": "0xYourAddress", "chainId": 33139}'

Selling & bidding

Fetch the signing parameters (EIP-712 domain, the mandatory cosigner, marketplace + fee numerator, and your current master nonce), sign a PaymentProcessor V3 approval with your wallet, and post it. All values that appear in your order - cosigner, marketplace, fee numerator - must match what the params endpoint returned, or intake rejects the order. Listings pay out in the native currency; offers use the chain's wrapped token. Cancelling is gas-free with a signed message.

# 1. Signing parameters
curl "https://api.oswiki.xyz/v1/orders/params?chainId=33139&maker=0xYou"

# 2. Sign the SaleApproval typed data with your wallet, then:
curl -X POST "https://api.oswiki.xyz/v1/orders/asks" \
  -H "Content-Type: application/json" -H "X-API-Key: oswk_..." \
  -d '{"contractAddress": "0x...", "tokenId": "42", "chainId": 33139,
       "saleApproval": { ... }, "signature": "0x..."}'

Offers come in two shapes: a single-token offer (/v1/orders/bids, an ItemOfferApproval with a tokenId) and a collection-wide offer that any holder can accept (/v1/orders/bids/collection, a CollectionOfferApproval with no tokenId - the seller picks the token at accept time).

Errors

Rejections return HTTP 4xx with { "success": false, "error": "..." }. Validation failures on order intake also include a machine-readable reason so a bot can react without parsing prose:

Rate limits

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining headers; a 429 includes Retry-After. Need a higher limit for your integration? Reach out on Discord.