API Reference

The Cart.fun REST API provides programmatic access to all protocol features, allowing you to build applications that interact with the Cart.fun protocol without directly using the Solana blockchain.

While the REST API offers simplified access to protocol features, for high-performance applications or those requiring direct blockchain integration, we recommend using our TypeScript SDK.

Authentication

All API requests require authentication using JWT tokens. Tokens can be obtained through the authentication endpoint.

Obtaining a Token

curl -X POST https://api.cart.fun/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "YOUR_SOLANA_WALLET_ADDRESS",
    "signature": "SIGNED_MESSAGE_DATA"
  }'

The response will include your access token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Using the Token

Include the token in all API requests using the Authorization header:

curl https://api.cart.fun/v1/marketplaces \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Base URL

All API endpoints are relative to the following base URL:

https://api.cart.fun/v1

For development and testing, use the sandbox environment:

https://api-sandbox.cart.fun/v1

Request Format

API requests should be formatted as JSON and include the appropriate HTTP method (GET, POST, PUT, DELETE).

Headers

All requests should include these headers:

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Query Parameters

For GET requests, parameters should be included as query string parameters:

GET /marketplaces?limit=10&offset=0

Request Body

For POST and PUT requests, parameters should be included in the JSON request body:

{
  "name": "My New Marketplace",
  "description": "A marketplace for digital art",
  "fee_basis_points": 250
}

Response Format

All API responses are returned in JSON format. Successful responses include a data field containing the requested information.

Successful Response

{
  "success": true,
  "data": {
    "id": "marketplace_123456",
    "name": "My New Marketplace",
    "description": "A marketplace for digital art",
    "fee_basis_points": 250,
    "created_at": "2023-06-15T10:30:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": "The 'name' field is required"
  }
}

Common Error Codes

  • Name
    invalid_request
    Type
    error
    Description

    The request was malformed or missing required fields

  • Name
    unauthorized
    Type
    error
    Description

    Authentication failed or token is invalid

  • Name
    forbidden
    Type
    error
    Description

    The authenticated user doesn't have permission

  • Name
    not_found
    Type
    error
    Description

    The requested resource was not found

  • Name
    rate_limited
    Type
    error
    Description

    Too many requests, exceeding rate limits

  • Name
    internal_error
    Type
    error
    Description

    An internal server error occurred

Rate Limits

The API employs rate limiting to ensure fair usage and system stability. Limits are applied per API key and vary by endpoint.

Endpoint CategoryRate LimitReset Period
Authentication10 requestsPer minute
Read operations100 requestsPer minute
Write operations30 requestsPer minute
Listing endpoints60 requestsPer minute

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623766000

Protocol Endpoints

Endpoints for interacting with the core Protocol module.

Get Protocol Information

GET /protocol

Returns global protocol information, including fees and treasury statistics.

Example Response

{
  "success": true,
  "data": {
    "protocol_id": "protocol_123456",
    "authority": "5xNYNdV6VqPRQXkd8pKBhJ2ky6EDjgb6rUKJo7e1VuLL",
    "fee_basis_points": 100,
    "treasury_balance": 1250000000,
    "total_volume": 15000000000,
    "total_platforms": 28,
    "is_active": true,
    "supported_features": {
      "supports_nft_marketplaces": true,
      "supports_subscriptions": true,
      "supports_token_gating": true,
      "supports_auctions": true,
      "supports_dynamic_pricing": true,
      "supports_ai_integration": true
    }
  }
}

Get Protocol Treasury

GET /protocol/treasury

Returns information about the protocol treasury.

Example Response

{
  "success": true,
  "data": {
    "treasury_id": "treasury_789012",
    "authority": "5xNYNdV6VqPRQXkd8pKBhJ2ky6EDjgb6rUKJo7e1VuLL",
    "balance": 1250000000,
    "total_collected": 3750000000,
    "total_withdrawn": 2500000000,
    "last_transaction": "2023-06-14T15:45:00Z"
  }
}

Platform Endpoints

Endpoints for managing platforms.

List Platforms

GET /platforms

Returns a list of platforms.

Query Parameters

  • Name
    limit
    Type
    integer
    Description

    Number of results per page (default: 20, max: 100)

  • Name
    offset
    Type
    integer
    Description

    Pagination offset (default: 0)

  • Name
    sort
    Type
    string
    Description

    Field to sort by (created_at, total_volume, etc.)

  • Name
    order
    Type
    string
    Description

    Sort order (asc or desc)

Example Response

{
  "success": true,
  "data": {
    "platforms": [
      {
        "platform_id": "platform_123456",
        "admin": "8YUkBRzwgNmxYQQGx6qYt9LNJ6NSuR5f3KYwGxEFTQZm",
        "name": "Digital Art Platform",
        "description": "A platform for digital art and collectibles",
        "fee_basis_points": 200,
        "total_marketplaces": 5,
        "total_volume": 7500000000,
        "created_at": "2023-05-10T09:30:00Z"
      },
      ...
    ],
    "pagination": {
      "total": 28,
      "limit": 20,
      "offset": 0
    }
  }
}

Get Platform

GET /platforms/{platform_id}

Returns detailed information about a specific platform.

Example Response

{
  "success": true,
  "data": {
    "platform_id": "platform_123456",
    "admin": "8YUkBRzwgNmxYQQGx6qYt9LNJ6NSuR5f3KYwGxEFTQZm",
    "name": "Digital Art Platform",
    "description": "A platform for digital art and collectibles",
    "fee_basis_points": 200,
    "total_marketplaces": 5,
    "total_volume": 7500000000,
    "is_active": true,
    "treasury": {
      "balance": 950000000,
      "total_collected": 1500000000,
      "total_withdrawn": 550000000
    },
    "created_at": "2023-05-10T09:30:00Z",
    "updated_at": "2023-06-15T14:20:00Z"
  }
}

Create Platform

POST /platforms

Creates a new platform.

Request Body

{
  "name": "Digital Art Platform",
  "description": "A platform for digital art and collectibles",
  "fee_basis_points": 200
}

Example Response

{
  "success": true,
  "data": {
    "platform_id": "platform_123456",
    "admin": "8YUkBRzwgNmxYQQGx6qYt9LNJ6NSuR5f3KYwGxEFTQZm",
    "name": "Digital Art Platform",
    "description": "A platform for digital art and collectibles",
    "fee_basis_points": 200,
    "treasury": {
      "treasury_id": "treasury_567890",
      "balance": 0
    },
    "created_at": "2023-06-15T14:30:00Z"
  }
}

Update Platform

PUT /platforms/{platform_id}

Updates an existing platform.

Request Body

{
  "name": "Updated Art Platform",
  "description": "An updated platform for premium digital art",
  "fee_basis_points": 250
}

Marketplace Endpoints

Endpoints for managing marketplaces.

List Marketplaces

GET /marketplaces

Returns a list of marketplaces.

Query Parameters

  • Name
    platform_id
    Type
    string
    Description

    Filter by platform ID

  • Name
    marketplace_type
    Type
    string
    Description

    Filter by marketplace type

  • Name
    limit
    Type
    integer
    Description

    Number of results per page (default: 20, max: 100)

  • Name
    offset
    Type
    integer
    Description

    Pagination offset (default: 0)

Get Marketplace

GET /marketplaces/{marketplace_id}

Returns detailed information about a specific marketplace.

Create Marketplace

POST /marketplaces

Creates a new marketplace.

Request Body

{
  "platform_id": "platform_123456",
  "name": "Premium Art Gallery",
  "description": "Curated marketplace for premium digital art",
  "marketplace_type": "NFTMarketplace",
  "fee_basis_points": 250,
  "categories": ["art", "photography", "illustration"],
  "features": {
    "supports_nft_listings": true,
    "supports_auctions": true,
    "supports_token_gating": true
  }
}

Vendor Endpoints

Endpoints for managing vendors within marketplaces.

List Vendors

GET /marketplaces/{marketplace_id}/vendors

Returns a list of vendors in a marketplace.

Get Vendor

GET /vendors/{vendor_id}

Returns detailed information about a specific vendor.

Register Vendor

POST /marketplaces/{marketplace_id}/vendors

Registers a new vendor in a marketplace.

Request Body

{
  "name": "Digital Creations Studio",
  "description": "Premium digital art and collectibles by independent artists",
  "contact_email": "contact@digitalcreations.example",
  "categories": ["art", "digital", "collectibles"],
  "store_metadata": {
    "logo_url": "https://example.com/logo.png",
    "banner_url": "https://example.com/banner.png",
    "social_links": {
      "twitter": "https://twitter.com/digitalcreations",
      "instagram": "https://instagram.com/digitalcreations"
    }
  }
}

Product Endpoints

Endpoints for managing products within marketplaces.

List Products

GET /marketplaces/{marketplace_id}/products

Returns a list of products in a marketplace.

Query Parameters

  • Name
    vendor_id
    Type
    string
    Description

    Filter by vendor ID

  • Name
    category
    Type
    string
    Description

    Filter by category

  • Name
    price_min
    Type
    integer
    Description

    Minimum price in lamports

  • Name
    price_max
    Type
    integer
    Description

    Maximum price in lamports

  • Name
    sort
    Type
    string
    Description

    Field to sort by (created_at, price, etc.)

  • Name
    limit
    Type
    integer
    Description

    Number of results per page (default: 20, max: 100)

Get Product

GET /products/{product_id}

Returns detailed information about a specific product.

Create Product

POST /marketplaces/{marketplace_id}/products

Creates a new product in a marketplace.

Request Body

{
  "vendor_id": "vendor_123456",
  "name": "Premium Digital Art Tutorial",
  "description": "A comprehensive guide to creating premium digital art with professional techniques",
  "price": 500000000,
  "quantity": 1000,
  "image_url": "https://example.com/tutorial-cover.png",
  "encrypted_content_uri": "https://example.com/encrypted/tutorial.pdf",
  "lit_condition": {
    "condition_id": "condition_789012",
    "content_hash": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
    "encrypted_symmetric_key": "EncryptedKey..."
  },
  "metadata": {
    "category": "education",
    "tags": ["art", "tutorial", "digital", "professional"],
    "file_type": "application/pdf",
    "size_bytes": 15728640,
    "attributes": [
      { "trait_type": "pages", "value": "42" },
      { "trait_type": "difficulty", "value": "intermediate" },
      { "trait_type": "includes_source_files", "value": "true" }
    ]
  }
}

Purchase Product

POST /products/{product_id}/purchase

Initiates a purchase for a product.

AI Module Endpoints

Endpoints for AI features.

Search Products

GET /ai/search

Performs a natural language search for products.

Query Parameters

  • Name
    marketplace_id
    Type
    string
    Description

    Marketplace to search in

  • Name
    query
    Type
    string
    Description

    Natural language search query

  • Name
    max_results
    Type
    integer
    Description

    Maximum number of results to return

Generate Product Description

POST /ai/generate-description

Generates a product description using AI.

Request Body

{
  "product_name": "Cosmic Horizons Collection",
  "product_type": "Digital Art",
  "key_features": [
    "4K resolution artwork",
    "Limited edition of 100",
    "Space-themed visuals"
  ],
  "target_audience": "Art collectors",
  "tone": "professional",
  "length": "medium"
}

Webhooks

The Cart.fun API supports webhooks for real-time event notifications.

Configure Webhooks

POST /webhooks

Configures a new webhook endpoint.

Request Body

{
  "url": "https://your-app.example/webhooks/cart-fun",
  "events": ["product.created", "product.purchased", "vendor.registered"],
  "secret": "your-signing-secret"
}

Webhook Event Types

  • Name
    product.created
    Type
    event
    Description

    Triggered when a new product is created

  • Name
    product.updated
    Type
    event
    Description

    Triggered when a product is updated

  • Name
    product.purchased
    Type
    event
    Description

    Triggered when a product is purchased

  • Name
    vendor.registered
    Type
    event
    Description

    Triggered when a new vendor registers

  • Name
    marketplace.created
    Type
    event
    Description

    Triggered when a new marketplace is created

Webhook Payload Format

{
  "event": "product.purchased",
  "created_at": "2023-06-15T16:45:30Z",
  "data": {
    "product_id": "product_123456",
    "buyer": "H8RW2grSWGLwzXBGxMQRP9Xz6xwsZ4vhUwVJm2FkVBXz",
    "price": 500000000,
    "purchase_id": "purchase_789012",
    "timestamp": "2023-06-15T16:45:25Z"
  }
}

SDK Integration

While this API reference documents the REST API endpoints, for most applications we recommend using our TypeScript SDK for a more streamlined development experience.

import { CartProtocol, NetworkType } from '@cartdotfun/sdk'

const cartProtocol = new CartProtocol({
  connection,
  wallet,
  network: NetworkType.Devnet,
})

// SDK usage is more concise than direct API calls
const { transaction, marketplaceId } =
  await cartProtocol.marketplace.createMarketplace({
    platformId,
    name: 'Premium Art Gallery',
    description: 'Curated digital art marketplace',
    feeBasisPoints: 250,
  })

For complete SDK documentation, see the TypeScript SDK guide.

Resources

API Status Dashboard

Check current API operational status

API Playground

Interactive API testing environment

Integration Tutorials

Step-by-step integration guides

GitHub Repository

API client libraries and examples

Was this page helpful?