Basket Logo
TwitterDocsSupportPrivacy

Base URL:https://api.basket.gg

This section covers endpoints related to retrieving data from the platform.

List Products

Returns a paginated list of available gift card products, grouped by brand and country.

  • Endpoint: /api/products
  • Method: GET
  • Authentication: None required

Query Parameters

page · integer

The page number for pagination. Must be `1` or greater. Defaults to `1`.

limit · integer

The number of items to return per page. Min: `1`, Max: `100`. Defaults to `10`.

order_by · string

The order in which to sort the results. Examples: `popularity DESC`, `name ASC`. Defaults to `popularity DESC`.

Success Response (200 OK)

{
  "pagination": { "current_page": 1, "per_page": 1, "total_pages": 150, "total_items": 150 },
  "data": [
    {
      "card": {
        "name": "Amazon", "colour": "#FF9900", "logo": null, "instructions_html": "Use this gift card on amazon.com.",
        "countries": [
          { "country_name": "United States", "product_id": "amazon-us-usd", "country_code": "US", "currency_symbol": "$", "currency_abbreviation": "USD", "min_amount": 1, "max_amount": 2000, "set_amounts": [{ "amount": 25 }, { "amount": 50 }, { "amount": 100 }] },
          { "country_name": "Germany", "product_id": "amazon-de-eur", "country_code": "DE", "currency_symbol": "€", "currency_abbreviation": "EUR", "min_amount": 5, "max_amount": 1000, "set_amounts": [] }
        ]
      }
    }
  ]
}

Error Responses

  • 422 Unprocessable Entity: If a query parameter has an invalid value.
  • 500 Internal Server Error: If there is an issue on the server.

Search Brands

Performs a case-insensitive search for brands by a keyword.

  • Endpoint: /api/search
  • Method: GET
  • Authentication: None required

Query Parameters

q · string

The search keyword. Min length: 1, Max length: 50. Required.

page · integer

The page number for pagination. Must be 1 or greater. Defaults to 1.

limit · integer

The number of items to return per page. Min: 1, Max: 100. Defaults to 10.

Success Response (200 OK)

{
  "pagination": { "current_page": 1, "per_page": 1, "total_pages": 1, "total_items": 1 },
  "data": [
    {
      "card": {
        "name": "Amazon", "colour": "#FF9900", "logo": null, "instructions_html": "Use this gift card on amazon.com.",
        "countries": [
          { "country_name": "United States", "product_id": "amazon-us-usd", "country_code": "US", "currency_symbol": "$", "currency_abbreviation": "USD", "min_amount": 1, "max_amount": 2000, "set_amounts": [{ "amount": 25 }, { "amount": 50 }, { "amount": 100 }] }
        ]
      }
    }
  ]
}

Error Responses

  • 422 Unprocessable Entity: If the `q` parameter is missing or other parameters have invalid values.
  • 500 Internal Server Error: If there is an issue on the server.

Get Live Currency Rates

Provides live currency exchange rates, updated every 5 minutes.

  • Endpoint: /rates
  • Method: GET
  • Authentication: None required

Success Response (200 OK)

{
  "USD": 1,
  "EUR": 0.92,
  "GBP": 0.79,
  "SOL": 0.007,
  "BTC": 0.000015
}

Error Responses

  • 503 Service Unavailable: If currency rates are not available yet.
  • 500 Internal Server Error: If the currency data file is corrupted or there is a server issue.

This section covers endpoints related to user authentication and profile management. Access to most of these endpoints requires a JWT Authorization token, which is obtained upon successful registration or login. The token should be included as a cookie in subsequent requests.

Register New User

Creates a new user account and returns an authentication token.

  • Endpoint: /api/register
  • Method: POST
  • Authentication: None required

Request Body

referral_username · string

The username of the user who referred this new user.

Success Response (200 OK)

{
  "Authorization": "ey...",
  "user_id": 12345
}

Error Responses

  • 403 Forbidden: If the user is already logged in (i.e., an Authorization cookie is present).

Login with User ID

Authenticates a user with their User ID.

  • Endpoint: /api/login
  • Method: POST
  • Authentication: None required

Request Body

user_id · integer

The user's unique ID. Required.

Success Response (200 OK)

{
  "Authorization": "ey...",
  "user_id": 12345
}

Error Responses

  • 403 Forbidden: If the User ID does not exist.
  • 422 Unprocessable Entity: If the `user_id` is not provided or invalid.

Login with Solana Wallet

Authenticates a user by verifying a signature from their Solana wallet.

  • Endpoint: /api/wallet-login
  • Method: POST
  • Authentication: None required

Request Body

public_key · string

The user's Solana public key. Required.

signature · string

The signature of the message. Required.

timestamp · integer

The Unix timestamp (in milliseconds) when the message was created. Required.

referral_username · string

The username of a referrer, if applicable during initial login/registration.

Success Response (200 OK)

{
  "Authorization": "ey...",
  "public_key": "AWCc8AtfZVJMh18vZdSUzBz9Q1pTv7JT27kvEFaiWoBU"
}

Error Responses

  • 403 Forbidden: If the signature is invalid or the timestamp is too old.
  • 422 Unprocessable Entity: If the request body is missing required fields.

Get User Profile

Retrieves the profile of the currently authenticated user.

  • Endpoint: /api/profile
  • Method: GET
  • Authentication: Required (Authorization token)

Success Response (200 OK)

{
  "user_id": "12345", "username": "test_user", "profile_picture_url": "https://api.basket.gg/images/pfps/...", "email": "user@example.com",
  "total_orders": 10, "user_creation": 1678886400000, "total_spent_usdc": 150.50, "total_spent_sol": 1.25, "total_burned": 3010.0,
  "points": 500, "points_from_purchases": 400, "points_from_referrals": 100, "percentage_points_from_purchases": 80.0,
  "percentage_points_from_referrals": 20.0, "referred_users_count": 5, "referred_users_total_spent_usdc": 250.0,
  "tag": "VIP", "tag_colour": "#FFD700", "solana_public_key": "AWCc8AtfZVJMh18vZdSUzBz9Q1pTv7JT27kvEFaiWoBU", "est_bask_amnt": 1234.56
}

Error Responses

  • 401 Unauthorized: If the Authorization token is missing or invalid.
  • 404 Not Found: If the user's profile cannot be found.

Set Username and Profile Picture

Sets or updates the user's username and profile picture. The username can only be set once.

  • Endpoint: /api/profile/identity
  • Method: POST
  • Authentication: Required (Authorization token)

Request Body (multipart/form-data)

username · string

The desired username (3-20 characters, `a-z`, `0-9`, `_`). Required if not already set.

profile_picture · file

The image file for the profile picture (JPEG, PNG, GIF, max 2MB). Required.

Success Response (200 OK)

{
  "success": true,
  "message": "Profile updated successfully.",
  "profile_picture_url": "https://api.basket.gg/images/pfps/..."
}

Error Responses

  • 400 Bad Request: If required fields are missing or the username is being changed after it has already been set.
  • 401 Unauthorized: If the Authorization token is missing or invalid.
  • 409 Conflict: If the username is already taken.
  • 413 Payload Too Large: If the profile picture exceeds the 2MB size limit.
  • 422 Unprocessable Entity: If the username has an invalid format.

Check Username Availability

Checks if a username is available.

  • Endpoint: /api/username/available
  • Method: GET
  • Authentication: None required

Query Parameters

name · string

The username to check (3-20 characters, `a-z`, `0-9`, `_`). Required.

Success Response (200 OK)

{
  "username": "new_user",
  "available": true,
  "message": "Username is available."
}

{
  "username": "existing_user",
  "available": false,
  "message": "Username is already taken."
}

Error Responses

  • 422 Unprocessable Entity: If the `name` parameter is missing or invalid.

Update User Profile (Email)

Updates the email address for the authenticated user.

  • Endpoint: /api/change
  • Method: POST
  • Authentication: Required (Authorization token)

Request Body

to_change · string

The field to change. Must be "email". Required.

value · string

The new email address. Required.

Success Response (200 OK)

{
  "success": true,
  "message": "email updated"
}

Error Responses

  • 401 Unauthorized: If the `Authorization` token is missing or invalid.
  • 422 Unprocessable Entity: If the request body is malformed or the email is invalid.

This section covers endpoints for managing the user's shopping basket and placing orders. All endpoints require a valid JWT Authorization token.

Get User Basket

Retrieves the current contents of the authenticated user's shopping basket.

  • Endpoint: /api/basket
  • Method: GET
  • Authentication: Required (Authorization token)

Success Response (200 OK)

{
  "max_basket": 50, "max_amount": 10, "basket_len": 1,
  "basket_items": [
    { "product_id": "amazon-us-usd", "card_name": "Amazon", "card_colour": "#FF9900", "card_logo": null, "value": 50, "quantity": 2, "country_name": "United States", "country_code": "US", "currency_symbol": "$", "currency_abbreviation": "USD" }
  ]
}

Error Responses

  • 401 Unauthorized: If the Authorization token is missing or invalid.

Add/Update Basket Item

Adds a product to the basket or updates its quantity. If the quantity (amount) is 0, the item is removed.

  • Endpoint: /api/basket
  • Method: PUT
  • Authentication: Required (Authorization token)

Request Body

product_id · string

The unique identifier for the product. Required.

amount · integer

The quantity of the product to add/update. Required.

value · number

The value of a single item. Required.

Success Response (200 OK) - Returns updated BasketResponse object

{
  "max_basket": 50, "max_amount": 10, "basket_len": 1,
  "basket_items": [
    { "product_id": "amazon-us-usd", "card_name": "Amazon", "card_colour": "#FF9900", "card_logo": null, "value": 50, "quantity": 2, "country_name": "United States", "country_code": "US", "currency_symbol": "$", "currency_abbreviation": "USD" }
  ]
}

Error Responses

  • 401 Unauthorized: If the Authorization token is missing or invalid.
  • 403 Forbidden: If an item is out of stock or the amount exceeds the configured maximum.
  • 404 Not Found: If the specified product_id does not exist.
  • 422 Unprocessable Entity: If the request body is invalid.
  • 500 Internal Server Error: If an item of high value cannot be split correctly.

Clear User Basket

Deletes all items from the user's shopping basket.

  • Endpoint: /api/basket
  • Method: DELETE
  • Authentication: Required (Authorization token)

Success Response (200 OK)

{
    "max_basket": 50,
    "max_amount": 10,
    "basket_len": 0,
    "basket_items": []
}

Error Responses

  • 401 Unauthorized: If the Authorization token is missing or invalid.

Create Order from Basket

Creates a new order (invoice) from the items in the user's basket. This will clear the basket upon success.

  • Endpoint: /api/invoice
  • Method: POST
  • Authentication: Required (Authorization token)

Success Response (200 OK)

{
  "invoice_id": "ord-basket-...", "status": "creating", "order_creation": 1678886400, "order_expiry": 1678890000,
  "payment": { "solana_address": "...", "solana_amount": 1.23, "usdc_amount": 100.00, "left_to_pay": null, "bask_burned": 2000 },
  "items": [ { "invoice_id": "ord-basket-...", "product_id": "amazon-us-usd", "amount": 2, "value": 50, "failed": false, "flags": [], "pin_info": null, "card": { ... } } ]
}

Error Responses

  • 401 Unauthorized: If the Authorization token is missing or invalid.
  • 403 Forbidden: If the basket is empty or an item is out of stock.

Get Order Details

Retrieves details for a specific order by its ID.

  • Endpoint: /api/order/order_id
  • Method: GET
  • Authentication: Required (Authorization token)

Path Parameters

order_id · string

The ID of the order. Required.

Success Response (200 OK) - Returns BasketOrder object

{
  "invoice_id": "ord-basket-...", "status": "creating", "order_creation": 1678886400, "order_expiry": 1678890000,
  "payment": { "solana_address": "...", "solana_amount": 1.23, "usdc_amount": 100.00, "left_to_pay": null, "bask_burned": 2000 },
  "items": [ { "invoice_id": "ord-basket-...", "product_id": "amazon-us-usd", "amount": 2, "value": 50, "failed": false, "flags": [], "pin_info": null, "card": { ... } } ]
}

Error Responses

  • 400 Bad Request: If the order_id format is invalid.
  • 401 Unauthorized: If the token is missing/invalid or the user does not own the order.
  • 404 Not Found: If the order does not exist.

List User Orders

Retrieves a paginated list of a user's orders, with optional status filtering.

  • Endpoint: /api/orders
  • Method: GET
  • Authentication: Required (Authorization token)

Query Parameters

page · integer

The page number for pagination. Defaults to `1`.

limit · integer

The number of items per page (max 30). Defaults to `30`.

status · string

Filter by status. Can provide multiple statuses. Defaults to `completed`.

Success Response (200 OK)

{
    "pagination": { "current_page": 1, "previous_page": null, "next_page": null, "total_pages": 1, "total_records": 1 },
    "selection": { "status": [ "completed" ], "page": 1, "limit": 30 },
    "data": [ { ... } ]
}

Error Responses

  • 401 Unauthorized: If the Authorization token is missing or invalid.
  • 422 Unprocessable Entity: If query parameters are invalid.

This section provides definitions and examples for the main data structures used in the API responses.

ProductV2Response

The standard response format for endpoints that return a paginated list of products (`/api/products`, `/api/search`).

{
  "pagination": { "current_page": 1, "per_page": 1, "total_pages": 150, "total_items": 150 },
  "data": [
    {
      "card": {
        "name": "Amazon", "colour": "#FF9900", "logo": null, "instructions_html": "Use this gift card on amazon.com.",
        "countries": [
          { "country_name": "United States", "product_id": "amazon-us-usd", "country_code": "US", "currency_symbol": "$", "currency_abbreviation": "USD", "min_amount": 1, "max_amount": 2000, "set_amounts": [{ "amount": 25 }, { "amount": 50 }] }
        ]
      }
    }
  ]
}

LoginResponse

The response format for successful authentication (`/api/login`, `/api/register`, `/api/wallet-login`). The `Authorization` token should be stored and used as a cookie for subsequent authenticated requests.

{
  "Authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user_id": "1234567890123456",
  "public_key": "AWCc8AtfZVJMh18vZdSUzBz9Q1pTv7JT27kvEFaiWoBU"
}

ProfileInfo

Represents the detailed profile information for a user (`/api/profile`).

{
  "user_id": "12345", "username": "test_user", "profile_picture_url": "https://api.basket.gg/images/pfps/...", "email": "user@example.com",
  "total_orders": 10, "user_creation": 1678886400000, "total_spent_usdc": 150.50, "total_spent_sol": 1.25, "total_burned": 3010.0,
  "points": 500, "points_from_purchases": 400, "points_from_referrals": 100, "percentage_points_from_purchases": 80.0,
  "percentage_points_from_referrals": 20.0, "referred_users_count": 5, "referred_users_total_spent_usdc": 250.0,
  "tag": "VIP", "tag_colour": "#FFD700", "solana_public_key": "AWCc8AtfZVJMh18vZdSUzBz9Q1pTv7JT27kvEFaiWoBU", "est_bask_amnt": 1234.56
}

BasketResponse

Represents the user's shopping basket (`/api/basket`).

{
  "max_basket": 50, "max_amount": 10, "basket_len": 1,
  "basket_items": [
    { "product_id": "amazon-us-usd", "card_name": "Amazon", "card_colour": "#FF9900", "card_logo": null, "value": 50, "quantity": 2, "country_name": "United States", "country_code": "US", "currency_symbol": "$", "currency_abbreviation": "USD" }
  ]
}

BasketOrder

Represents a single order, either newly created or retrieved (`/api/invoice`, `/api/order/order_id`).

{
  "invoice_id": "ord-basket-...", "status": "creating", "order_creation": 1678886400, "order_expiry": 1678890000,
  "payment": { "solana_address": "...", "solana_amount": 1.23, "usdc_amount": 100.00, "left_to_pay": null, "bask_burned": 2000 },
  "items": [
    { "invoice_id": "ord-basket-...", "product_id": "amazon-us-usd", "amount": 2, "value": 50, "failed": false, "flags": [], "pin_info": null, "card": { ... } }
  ]
}

UserOrders

The response format for a paginated list of a user's orders (`/api/orders`).

{
    "pagination": { "current_page": 1, "previous_page": null, "next_page": null, "total_pages": 1, "total_records": 1 },
    "selection": { "status": [ "completed" ], "page": 1, "limit": 30 },
    "data": [ { ... } ]
}
FAQ

Frequently Asked Questions

Got more questions?

TelegramContact us

Background
Get started

Turn your profits

into gift cards.

No Limits, No KYC, Thousands of options.