Flow Dealers API

A REST API for the Flow Dealers wholesale marketplace. Search listings from other verified dealers, create and update your own listings, and read your offers and orders. The API is part of the Pro and Enterprise plans.

Quick start

Put your organization on the Pro or Enterprise plan.
As an owner or admin, create a key in Settings, API keys. Copy it; it is shown once.
Send it as a bearer token:

curl "https://api.flowauctions.com/dealers/v1/listings?q=morgan&limit=5" \
  -H "Authorization: Bearer fd_live_..."

Authentication

Every request needs Authorization: Bearer <key>. Keys start with fd_live_ and belong to your organization. A key acts as the owner or admin who created it, so it stops working if that person leaves or is no longer an owner or admin. Revoke a key from the settings page at any time. Keep keys on your server; do not put them in a web page or mobile app.

Requests and limits

Base URL: https://api.flowauctions.com/dealers/v1
Each key allows 120 requests per 60 seconds. Over the limit, the API returns 429 with a Retry-After header.
Send JSON bodies with Content-Type: application/json.
Money is in integer cents (USD). Timestamps are ISO 8601 in UTC.
Lists take page and limit (1 to 100) and return hasMore.

Errors

Errors return { code, message }, plus issues for validation errors.

Status	Code	Meaning
400	BAD_REQUEST	The request failed validation. `issues` lists each field.
401	UNAUTHORIZED	The key is missing, unknown, expired, or revoked.
403	FORBIDDEN	The plan no longer includes the API, or the key's creator is no longer an owner or admin.
404	NOT_FOUND	No such resource, or it belongs to another organization.
429	TOO_MANY_REQUESTS	Rate limit reached. Wait for the seconds in `Retry-After`.
500	INTERNAL_SERVER_ERROR	Something failed on our side. Retry, or email us.

Endpoints

The full machine-readable reference is the OpenAPI 3.1 document. Load it into Postman, Insomnia, or a code generator.

Account

get/me

Check your API key

Returns the organization and key that the request is authenticated as.

Returns object.

Listings

get/listings

Search the marketplace

Listings that other verified dealers can buy now: unsold, not delisted, and in stock.

Parameters

Field	Type	Notes
q	string
categoryId	uuid
sellerId	uuid
gradingService	string
grade	string
minPriceInCents	integer
maxPriceInCents	integer
sort	"newest" \| "oldest" \| "price_asc" \| "price_desc"	Default "newest".
page	integer	Page number, starting at 1. Default 1.
limit	integer	Results per page, 1 to 100. Default 20.

Returns a page of Listing[].

get/listings/{id}

Get a marketplace listing

Parameters

Field	Type	Notes
{id}*	uuid

Returns Listing.

Your listings

get/me/listings

List your listings

Your organization's listings, including cost and sold or delisted ones.

Parameters

Field	Type	Notes
q	string
status	"active" \| "sold" \| "all"	Default "all".
sort	"newest" \| "oldest" \| "price_asc" \| "price_desc"	Default "newest".
page	integer	Page number, starting at 1. Default 1.
limit	integer	Results per page, 1 to 100. Default 20.

Returns a page of OwnListing[].

post/me/listings

Create a listing

Lists a coin on the marketplace. Your organization must be a verified dealer. Photos are added in the Flow Dealers app.

JSON body

Field	Type	Notes
title*	string
description	string	Plain text. Each line becomes a paragraph.
priceInCents	integer
costInCents	integer
quantity	integer	Default 1.
sku	string
number	string
categoryId	uuid
gradingService	string
grade	string
certificateNumber	string
attributes	object
shippingMethod	"flat_rate" \| "free" \| "calculated" \| "pickup_only"	Default "flat_rate".
shippingCostInCents	integer
freeShippingThresholdInCents	integer
allowLocalPickup	boolean	Default false.
shippingNotes	string

Returns OwnListing.

get/me/listings/{id}

Get one of your listings

Parameters

Field	Type	Notes
{id}*	uuid

Returns OwnListing.

patch/me/listings/{id}

Update a listing

Changes only the fields you send.

Parameters

Field	Type	Notes
{id}*	uuid

JSON body

Field	Type	Notes
title	string
description	string	Plain text. Each line becomes a paragraph.
priceInCents	integer
costInCents	integer
quantity	integer	Default 1.
sku	string
number	string
categoryId	uuid
gradingService	string
grade	string
certificateNumber	string
attributes	object
shippingMethod	"flat_rate" \| "free" \| "calculated" \| "pickup_only"	Default "flat_rate".
shippingCostInCents	integer
freeShippingThresholdInCents	integer
allowLocalPickup	boolean	Default false.
shippingNotes	string

Returns OwnListing.

delete/me/listings/{id}

Delete a listing

Parameters

Field	Type	Notes
{id}*	uuid

Returns object.

Offers

get/me/offers

List your offers

Offers your organization sent or received, newest first.

Parameters

Field	Type	Notes
direction	"sent" \| "received"
status	"pending" \| "accepted" \| "rejected" \| "countered" \| "expired" \| "withdrawn"
open	"true" \| "false"
listingId	uuid
page	integer	Page number, starting at 1. Default 1.
limit	integer	Results per page, 1 to 100. Default 20.

Returns a page of Offer[].

post/me/offers

Make an offer

Offers a price for one unit of another dealer's listing. You can have one open offer per listing. Your organization must be a verified dealer.

JSON body

Field	Type	Notes
listingId*	uuid
amountInCents*	integer	Your price for one unit.
quantity	integer	Default 1.
message	string
expiresInHours	integer	Hours the other side has to answer. Defaults to 48.

Returns Offer.

get/me/offers/{id}

Get an offer

Parameters

Field	Type	Notes
{id}*	uuid

Returns Offer.

post/me/offers/{id}/counter

Counter an offer

Names a new price when the offer waits for you. A seller counters a pending offer. A buyer counters a countered offer.

Parameters

Field	Type	Notes
{id}*	uuid

JSON body

Field	Type	Notes
amountInCents*	integer	Your new price for one unit.
message	string
expiresInHours	integer	Hours the other side has to answer. Defaults to 48.

Returns Offer.

post/me/offers/{id}/accept

Accept an offer

Accepts the price on the table when the offer waits for you. This makes an order that holds the stock for 48 hours while the buyer pays. Open offers the remaining stock cannot fill are declined.

Parameters

Field	Type	Notes
{id}*	uuid

Returns Offer.

post/me/offers/{id}/decline

Decline an offer

Declines the offer when it waits for you. A buyer that wants to stop at any time can withdraw.

Parameters

Field	Type	Notes
{id}*	uuid

JSON body

Field	Type	Notes
message	string

Returns Offer.

post/me/offers/{id}/withdraw

Withdraw your offer

Takes back an open offer you sent.

Parameters

Field	Type	Notes
{id}*	uuid

Returns Offer.

Orders

get/me/orders

List your orders

Orders your organization bought (role=buyer) or sold (role=seller), newest first.

Parameters

Field	Type	Notes
role*	"buyer" \| "seller"	Orders you bought, or orders you sold.
status	"pending" \| "confirmed" \| "shipped" \| "delivered" \| "cancelled"
page	integer	Page number, starting at 1. Default 1.
limit	integer	Results per page, 1 to 100. Default 20.

Returns a page of Order[].

get/me/orders/{id}

Get an order

Parameters

Field	Type	Notes
{id}*	uuid

Returns Order.

Help

Questions about the API: email support@flowauctions.com.