Natural Order API v1

Build integrations for proximity-based MTG card trading.

Authentication

Generate an API key from your profile page. Include it in every request as a Bearer token.

Authorization: Bearer sk_live_abc123...

Base URL:

https://natural-order.vercel.app/api/v1

Rate Limits

Response Format

All responses return JSON.

Success (single)

{
  "data": { ... }
}

Success (list)

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total_count": 128,
    "has_more": true
  }
}

Error

{
  "error": "Descriptive error message"
}

Profile

Returns the authenticated user's profile information.

Response

{
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "display_name": "TraderJoe",
    "preferred_language": "es"
  }
}

Collection

List your collection. Paginated.

Response

{
  "data": [
    {
      "id": "uuid",
      "scryfall_id": "abc123",
      "card_name": "Lightning Bolt",
      "quantity": 4,
      "condition": "NM",
      "foil": false,
      "asking_price": 1.20
    }
  ],
  "meta": { "page": 1, "limit": 50, "total_count": 215, "has_more": true }
}

Add a card to your collection.

Response

{
  "data": {
    "id": "uuid",
    "scryfall_id": "abc123",
    "card_name": "Lightning Bolt",
    "quantity": 4,
    "condition": "NM"
  }
}

Update a card in your collection.

Remove a card from your collection.

Response

{
  "data": { "deleted": true }
}

Wishlist

List your wishlist. Paginated.

Response

{
  "data": [
    {
      "id": "uuid",
      "scryfall_id": "abc123",
      "card_name": "Ragavan, Nimble Pilferer",
      "quantity": 1,
      "max_price": 50.00,
      "min_condition": "LP",
      "priority": 8
    }
  ],
  "meta": { "page": 1, "limit": 50, "total_count": 42, "has_more": false }
}

Add a card to your wishlist.

Update a wishlist item.

Remove a card from your wishlist.

Card Search

Search for Magic cards by name. Powered by Scryfall data.

Response

{
  "data": [
    {
      "scryfall_id": "abc123",
      "name": "Lightning Bolt",
      "set_code": "lea",
      "set_name": "Limited Edition Alpha",
      "prices_usd": "385.00",
      "image_uri": "https://cards.scryfall.io/..."
    }
  ]
}

Preferences

Get your trading preferences.

Response

{
  "data": {
    "trade_mode": "both",
    "default_price_percentage": 80,
    "minimum_price": 0.50,
    "collection_paused": false,
    "price_source": "scryfall"
  }
}

Update your trading preferences.

Matches

List your trading matches. Paginated.

Response

{
  "data": [
    {
      "id": "uuid",
      "counterpart": { "display_name": "CardShark", "avatar_url": "..." },
      "match_type": "two_way",
      "match_score": 72,
      "distance_km": 3.5,
      "cards_you_want": 5,
      "cards_they_want": 3,
      "status": "active"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total_count": 8, "has_more": false }
}

Get full match details including matched cards.

Response

{
  "data": {
    "id": "uuid",
    "counterpart": { "display_name": "CardShark" },
    "match_type": "two_way",
    "status": "active",
    "distance_km": 3.5,
    "cards_you_want": [
      { "card_id": "uuid", "card_name": "Lightning Bolt", "asking_price": 1.20 }
    ],
    "cards_they_want": [
      { "card_id": "uuid", "card_name": "Counterspell", "asking_price": 0.80 }
    ]
  }
}

Update match status or favorite flag.

Run the matching algorithm. Finds nearby users with compatible collections and wishlists. Rate limited to 5 requests per minute.

Response

{
  "data": {
    "matches_found": 5,
    "new_matches": 3,
    "updated_matches": 2
  }
}

Trade Actions

Trade lifecycle: active → requested → confirmed → completed

Request a trade with this match. The other user will be notified.

Response

{
  "data": { "status": "requested", "requested_by": "your-uuid" }
}

Cancel or reject a pending trade request.

Confirm the trade. Starts a 15-day escrow period. Cards are reserved from other matches.

Response

{
  "data": {
    "status": "confirmed",
    "confirmed_at": "2026-01-15T10:30:00Z",
    "escrow_expires_at": "2026-01-30T10:30:00Z"
  }
}

Mark the trade as completed (or not).

Match Cards

Toggle exclusion of a specific card in a match.

Bulk update card exclusions. All cards not in the array will be included.

Response

{
  "data": { "updated": 3 }
}

Comments

List comments on a match. Paginated.

Response

{
  "data": [
    {
      "id": "uuid",
      "content": "Hey, I can meet downtown tomorrow!",
      "author": { "display_name": "TraderJoe" },
      "created_at": "2026-01-15T14:30:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total_count": 3, "has_more": false }
}

Post a comment on a match. Max 300 characters. Limited to 10 comments per month.

Error Codes

Error response shape

{
  "error": "Missing required field: scryfall_id"
}

Rate Limiting

Rate limit information is included in response headers.

Example 429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706112000

{
  "error": "Rate limit exceeded. Try again in 23 seconds."
}

Full Workflow Example

End-to-end example of finding and completing a trade via the API.

1. 1

   Search for a card

   GET /v1/cards/search?q=Lightning%20Bolt

2. 2

   Add to your wishlist

   POST /v1/wishlist
   {
     "scryfall_id": "e2d1f9c2-...",
     "max_price": 2.00,
     "priority": 8
   }

3. 3

   Add cards to your collection

   POST /v1/collection
   {
     "scryfall_id": "f5a2b8e1-...",
     "quantity": 2,
     "condition": "NM"
   }

4. 4

   Compute matches

   POST /v1/matches/compute

5. 5

   Review matches

   GET /v1/matches?status=active

6. 6

   Request a trade

   POST /v1/matches/abc123/request

7. 7

   Other user confirms the trade

   POST /v1/matches/abc123/confirm

8. 8

   Mark trade as complete

   POST /v1/matches/abc123/complete
   {
     "completed": true
   }