⚡

paySwapr Developer API

REST API for building your own tools on top of paySwapr. Base URL: https://payswapr.com/api/dev/v1. Access is via a scoped API key you generate from your account.

# Authentication

You must already have a paySwapr account. Sign in and go to Profile → Developer / API to create a key, choose its scopes, and copy the secret (shown only once). Keys are revocable and can be regenerated at any time.

Send your key on every request:

Authorization: Bearer YOUR_API_KEY
Accept: application/json

A developer key is limited to the scopes you grant it and can never access wallet balances, withdrawals, seed phrases, KYC, or account settings — those live on the first-party app only. There is no login or register endpoint here by design.

Example

curl https://payswapr.com/api/dev/v1/coins \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Scopes

Each key holds one or more scopes. A request is rejected with 403 insufficient_scope if the key lacks the scope its endpoint requires.

Scope	Grants	Status
dev:market:read	Market data — Read prices, supported coins and currencies.	Available
dev:profile:read	Read profiles — Read your own profile and other traders' public profiles, feedback and stats.	Available
dev:offers:read	Read offers — Browse public offers and read your own offers.	Available
dev:trades:read	Read trades — Read your trades and their messages.	Available
dev:offers:write	Manage offers — Create, update and cancel your offers. Requires request signing (HMAC).	Available HMAC
dev:trades:write	Trade actions — Start, accept, mark-paid, release and send messages in trades. Requires request signing (HMAC).	Available HMAC

Market Data

Requires scope dev:market:read

Method	Endpoint	Description	Query / Params
GET	/api/dev/v1/market/prices	Full price matrix (all coins vs currencies)	—
GET	/api/dev/v1/market/price/{coin}	Live price for one coin	—
GET	/api/dev/v1/coins	Supported coins	—
GET	/api/dev/v1/currencies	Active fiat currencies + trade limits	—

Profile

Requires scope dev:profile:read

Method	Endpoint	Description	Query / Params
GET	/api/dev/v1/profile	Your own public profile	—
GET	/api/dev/v1/users/{username}	Any trader's public profile (bio, trades, feedback counts, active offers, medals)	—
GET	/api/dev/v1/users/{username}/feedback	Paginated feedback left on that trader	?type=positive\|negative &payment_method_id= &per_page=
GET	/api/dev/v1/users/{username}/stats	30-day + lifetime trade stats, coin breakdown	—

Offers

Requires scope dev:offers:read

Method	Endpoint	Description	Query / Params
GET	/api/dev/v1/offers	Browse active offers	?coin= &type=buy\|sell &payment= &currency= &min= &max= &sort=best_rate\|trades\|newest &page=
GET	/api/dev/v1/offers/mine	Your own offers	—
GET	/api/dev/v1/offers/{slug}	Single offer with trader stats	—

Trades

Requires scope dev:trades:read

Method	Endpoint	Description	Query / Params
GET	/api/dev/v1/trades	Your trades	?status= &coin= &role= &search= &date_from= &date_to= &page=
GET	/api/dev/v1/trades/{ref}	Trade detail	—
GET	/api/dev/v1/trades/{ref}/messages	Trade chat history	—

Write actions HMAC

Value-moving endpoints require the write scope and a valid HMAC signature on every request. The signature authorises the action in place of a wallet PIN, so your secret never travels on the wire. A dev key can only ever release escrow to the trade counterparty — never to an arbitrary address — and withdrawals/seed export are not part of the developer API.

Signing a request

Creating a key with a write scope returns a one-time signing secret. Build the canonical string, HMAC-SHA256 it with that secret, and send the hex digest.

canonical = "{timestamp}\n{METHOD}\n{path}\n{rawBody}"
signature = hex( hmac_sha256( signing_secret, canonical ) )

# headers on every write request
Authorization: Bearer YOUR_API_KEY
X-Timestamp:   {unix seconds}   # within 5 min of server time
X-Signature:   {signature}

path begins with a slash, e.g. /api/dev/v1/trades/CS-AB12/release. rawBody is the exact JSON body sent (empty string when there is none).

Offers — requires dev:offers:write HMAC

POST	/api/dev/v1/offers	Create an offer	coin, type, payment_method_id, price_type=market_plus\|fixed, premium (if market_plus), fixed_price (if fixed), min_amount_usd, max_amount_usd, currency?, terms?
PUT	/api/dev/v1/offers/{slug}	Update an offer	price_type?, premium?, fixed_price?, min_amount_usd?, max_amount_usd?, currency?, terms?, status?=active\|paused
DELETE	/api/dev/v1/offers/{slug}	Delete an offer	—

Trades — requires dev:trades:write HMAC

POST	/api/dev/v1/trades	Start a trade from an offer	offer_id, amount_usd
POST	/api/dev/v1/trades/{ref}/accept	Offer owner accepts the trade	—
POST	/api/dev/v1/trades/{ref}/escrow	Seller funds escrow (signed via server key copy)	—
POST	/api/dev/v1/trades/{ref}/mark-paid	Buyer marks payment sent	—
POST	/api/dev/v1/trades/{ref}/release	Seller releases escrow to buyer	—
POST	/api/dev/v1/trades/{ref}/cancel	Cancel trade	reason
POST	/api/dev/v1/trades/{ref}/dispute	Open a dispute	reason
POST	/api/dev/v1/trades/{ref}/messages	Send a trade chat message	message, reply_to_id?

Funding escrow: spends from the seller's wallet and is authorised by the signature on your request. If your wallet hasn't been enabled for signed requests yet you'll get 422 escrow_pin_setup_required; confirm your PIN once in the app, then retry. USDT-collateral escrow remains app-only.

Standard Error Responses

Response Shape

{
  "error": "insufficient_scope",
  "message": "This API key is missing the required scope: dev:trades:read.",
  "scope": "dev:trades:read"
}

HTTP Status Codes

200 Success

401 Unauthenticated (missing/invalid API key)

401 signature_required — signed endpoint called without X-Timestamp/X-Signature

401 stale_timestamp — timestamp older/newer than the 5-minute window

401 invalid_signature — HMAC does not match (wrong secret or tampered body/path)

403 insufficient_scope / invalid_token_type (frontend token used)

409 replayed_signature — this exact signature was already used within the window

404 Resource not found

422 Validation failed

422 escrow_pin_setup_required — confirm your wallet PIN once in the app, then retry the escrow

429 Too many requests (rate limit)

Rate Limits

• Developer API: 120 req/min per key

• Exceeding the limit returns 429 — back off and retry.

• Revoking or regenerating a key takes effect immediately.

Wallet PIN Required