SwapR API — reference

The account behind the key — id, name, email, username, role, verification state, market and currency.

{"id":"85916a4a-…","name":"Ife BNPL Test","email":"you@example.com","username":"you",
 "role":"USER","verified":true,"kyc_tier":1,"market":"US","currency":"USD",
 "member_since":"2026-09-24 00:02:11"}

Browse listings. Query parameters: limit (1–50, default 20), offset (default 0), mine=1 (only your own listings instead of the public active feed).

curl -s "https://www.myswapr.com/api/v1/listings?limit=2&mine=1" \
  -H "X-API-Key: sk_YOUR_KEY"

{"listings":[{"id":"b4cf8a8f-…","title":"Camera lens","description":"Clean glass…",
  "price_cents":3000,"currency":"USD","condition":"GOOD","type":"SALE","status":"ACTIVE",
  "created_at":"2026-09-24 00:05:40","owner_name":"Ife BNPL Test","image":null}],
 "count":1,"limit":2,"offset":0}

Create a listing (JSON body; form fields also accepted). Same monthly plan allowance as the web form — the Free plan allows 1/month.

curl -s -X POST https://www.myswapr.com/api/v1/listings \
  -H "X-API-Key: sk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Camera lens","description":"Clean glass, no fungus",
       "price":30.00,"currency":"USD","condition":"GOOD","type":"SALE",
       "category":"electronics"}'

201 → {"created":true,"id":"…","url":"/listing/…"}

Fields: title (required), description (10+ characters), price (> 0, in money units — stored as cents), currency (default USD, must be a supported market currency), condition (NEW · LIKE_NEW · GOOD · FAIR, unknown falls back to GOOD), type (SALE · SWAP · BOTH, unknown falls back to SALE), category (electronics · fashion · home · collectibles · sports · other, unknown falls back to other).

Idempotency-Key (header, optional but recommended): send a unique value per create — replaying the same key with the same body returns the original 201 response byte-for-byte (Idempotency-Replayed: true); the same key with a different body is refused with 409.

Your last 30 offers — sent and received — with listing title, price and status.

{"offers":[{"id":"2362a4eb-…","status":"ACCEPTED","created_at":"2026-09-22 18:11:03",
  "title":"Camera lens","price_cents":3000,"currency":"USD"}],"count":1}

Send an offer on a listing — the same state machine as the website. JSON body: listing_id (required), amount (money units; required for BUY), message (≤ 1000 chars), kind (BUY · SWAP), swap_listing_id (your own active listing — required when kind=SWAP).

curl -s -X POST https://www.myswapr.com/api/v1/offers \
  -H "X-API-Key: sk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"listing_id":"b4cf8a8f-…","amount":25.50,"message":"Cash today?"}'

201 → {"created":true,"id":"…","status":"PENDING","listing_id":"…","amount_cents":2550}

Answers: 404 no listing · 409 listing not active, swap-only/sale-only mismatch, or your own listing (403) · 422 amount ≤ 0 or missing swap_listing_id.

Answer a pending offer. accept (seller only — creates the escrow order and reserves the listing, 201), decline (seller), withdraw (buyer), counter (either side; body needs amount, optional message). Sibling paths: /api/v1/offers/{id}/decline · /api/v1/offers/{id}/withdraw · /api/v1/offers/{id}/counter.

201 → {"offer_id":"…","status":"ACCEPTED","order_id":"…","url":"/order/…"}
403 wrong side · 409 offer no longer PENDING / listing gone · 422 counter without amount

Escrow orders where the key's account is buyer or seller. Query parameters: limit (1–50, default 20), offset (default 0). Each row carries side (BUY/SELL), status, amounts in cents and the counterparty.

{"orders":[{"id":"9c1f…","status":"FUNDED","side":"BUY","amount_cents":3000,
  "fee_cents":75,"payout_cents":0,"listing_title":"Camera lens","counterparty":"Ada"}],
 "count":1,"limit":20,"offset":0}

Balances for the account behind the key. Read-only by design — this endpoint can never move money.

{"available_cents":107800,"held_cents":0,"currency":"USD",
 "note":"Ledger settles in USD cents; display conversion is a client concern."}