{ "openapi": "3.0.1", "servers": [ { "url": "https://staging.crossmint.com/api", "description": "Staging environment (testnets)" }, { "url": "https://www.crossmint.com/api", "description": "Production environment (mainnets)" } ], "info": { "description": "N/A\n", "version": "1.0.0", "title": "Headless Checkout", "contact": { "name": "Crossmint Headless Checkout APIs", "url": "https://www.crossmint.com", "email": "support@crossmint.com" } }, "tags": [ { "name": "Headless Checkout", "description": "APIs to use the headless checkout" } ], "paths": { "/2022-06-09/orders": { "post": { "summary": "Create Order", "description": "Creates a new order that can be used to complete a headless checkout.\n\n**API scope required**: `orders.create`\n", "operationId": "create-order", "security": [ { "apiKey": [] } ], "tags": [ "Headless" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "payment", "lineItems" ], "properties": { "recipient": { "$ref": "#/components/schemas/Recipient" }, "locale": { "$ref": "#/components/schemas/Locale" }, "payment": { "$ref": "#/components/schemas/Payment" }, "lineItems": { "$ref": "#/components/schemas/LineItems" }, "state": { "type": "string", "enum": [ "draft", "create" ], "default": "create", "description": "Determines whether an order is officially created or whether it simply returns what an order would look like. Use `draft` to review results prior to committing. Draft orders are not currently persisted and will not be queryable via APIs. Use `create` (default) to place the order and proceed to payment/fulfillment." } } } } } }, "responses": { "201": { "description": "Order successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } } }, "400": { "description": "Invalid arguments, please make sure you're following the api specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/400Response" }, "examples": { "limits:single-purchase.exceeded": { "description": "Purchase limit exceeded", "value": { "error": true, "message": "Purchase limit exceeded. Transaction amount (150) exceeds the maximum allowed single purchase limit of 100.", "code": "limits:single-purchase.exceeded", "parameters": { "amount": "150", "limit": "100" } } }, "limits:daily-transaction.exceeded": { "description": "Daily transaction limit reached", "value": { "error": true, "message": "Daily transaction limit reached. You have exceeded the daily transaction limit of 1000. Your limit will reset in 8 hours. You have 0 left to spend today.", "code": "limits:daily-transaction.exceeded", "parameters": { "limit": "1000", "hoursUntilReset": "8", "remainingAmount": "0" } } } } } } }, "403": { "description": "Forbidden error, please ensure the credentials are correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403Response" } } } }, "404": { "description": "Not found error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Response" } } } }, "503": { "description": "Please try again in a few minutes. If the issue still persists, contact Crossmint support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/503Response" } } } }, "524": { "description": "A timeout occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/524Response" } } } } } }, "get": { "summary": "List Orders", "description": "Returns a paginated list of orders for your project, sorted by creation date (newest first by default). Use the `nextCursor` or `previousCursor` returned in the response to navigate between pages.\n\nOptional filters accept comma-separated values and repeated query parameters (maximum 20 terms per filter). Keep the same filter params when following cursors.\n\n**API scope required**: `orders.read`\n", "operationId": "list-orders", "security": [ { "apiKey": [] } ], "tags": [ "Headless" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response's `nextCursor` or `previousCursor`. Omit on the first request.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of orders to return. Minimum 1, maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "example": 30 }, { "name": "sort", "in": "query", "required": false, "description": "Sort direction applied to `createdAt`.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "paymentStatus", "in": "query", "required": false, "description": "Comma-separated list of payment statuses. Orders matching any value are returned. Maximum 20 terms per parameter. Keep filter params stable when paginating with cursors.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "quote-phase", "in-progress", "succeeded", "declined", "expired", "refunded" ] }, "maxItems": 20 }, "style": "form", "explode": false }, { "name": "deliveryStatus", "in": "query", "required": false, "description": "Comma-separated list of delivery statuses. Orders matching any value are returned. Maximum 20 terms per parameter. Keep filter params stable when paginating with cursors.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "not-started", "in-progress", "partial-delivery", "delivered", "failed" ] }, "maxItems": 20 }, "style": "form", "explode": false }, { "name": "paymentMethod", "in": "query", "required": false, "description": "Comma-separated list of currencies matched against `payment.totalPaid.currency`. The `fiat` value matches all fiat payment methods. Maximum 20 terms per parameter.", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "style": "form", "explode": false, "example": "usdc,fiat" }, { "name": "recipientAddress", "in": "query", "required": false, "description": "Exact match on buyer wallet address (`buyer.mintTo`). Supports EVM and Solana addresses. Maximum 20 terms per parameter.", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "style": "form", "explode": false }, { "name": "orderId", "in": "query", "required": false, "description": "Exact match on order ID (`orderIdentifier`). Maximum 20 terms per parameter.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Orders retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrdersResponse" } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/400Response" } } } }, "403": { "description": "Forbidden. Ensure your API key has the `orders.read` scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403Response" } } } } } } }, "/2022-06-09/orders/{orderId}": { "get": { "summary": "Get Order", "description": "Get specific order by ID.\n\n**Authentication**: Use either a server-side API key with `orders.read` scope, or the `clientSecret` from order creation as an authorization header.\n", "operationId": "get-order", "security": [ { "apiKey": [] }, { "orderClientSecret": [] } ], "tags": [ "Headless" ], "parameters": [ { "$ref": "#/components/parameters/orderId" } ], "responses": { "200": { "description": "Order successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderObject" } } } }, "400": { "description": "Invalid arguments, please make sure you're following the api specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/400Response" } } } }, "403": { "description": "Forbidden error, please ensure the credentials are correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403Response" } } } }, "404": { "description": "Not found error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Response" } } } }, "503": { "description": "Please try again in a few minutes. If the issue still persists, contact Crossmint support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/503Response" } } } }, "524": { "description": "A timeout occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/524Response" } } } } } }, "patch": { "summary": "Edit Order", "description": "Edit an existing order. You can update the recipient, the payment method, and/or the locale.\n\n**API scope required**: `orders.update`\n", "operationId": "edit-order", "security": [ { "apiKey": [] }, { "orderClientSecret": [] } ], "tags": [ "Headless" ], "parameters": [ { "$ref": "#/components/parameters/orderId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDTO" } } } }, "responses": { "200": { "description": "Order successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderObject" } } } }, "400": { "description": "Invalid arguments, please make sure you're following the api specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/400Response" } } } }, "403": { "description": "Forbidden error, please ensure the credentials are correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403Response" } } } }, "404": { "description": "Not found error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Response" } } } }, "503": { "description": "Please try again in a few minutes. If the issue still persists, contact Crossmint support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/503Response" } } } }, "524": { "description": "A timeout occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/524Response" } } } } } } }, "/2022-06-09/orders/{orderId}/payment": { "post": { "summary": "Process Payment", "description": "Process payment for an order using a crypto transaction ID.\n\n**Authentication**: Use either a server-side API key with `orders.update` scope, the `clientSecret` from order creation as an authorization header, or a JWT token with `orders.create` scope.\n", "operationId": "process-payment", "security": [ { "apiKey": [] }, { "orderClientSecret": [] } ], "tags": [ "Headless" ], "parameters": [ { "$ref": "#/components/parameters/orderId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessPaymentInput" } } } }, "responses": { "200": { "description": "Payment processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderObject" } } } }, "400": { "description": "Invalid arguments, please make sure you're following the api specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/400Response" } } } }, "403": { "description": "Forbidden error, please ensure the credentials are correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403Response" } } } }, "404": { "description": "Not found error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Response" } } } }, "503": { "description": "Please try again in a few minutes. If the issue still persists, contact Crossmint support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/503Response" } } } }, "524": { "description": "A timeout occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/524Response" } } } } } } }, "/v1-alpha2/tokens/{tokenLocator}": { "get": { "summary": "Check Supported Tokens", "description": "Get a token and its available features by its locator. This endpoint allows you to check if a specific token is supported by Crossmint and what features are available for it.\n\n**API scope required**: `orders.create`\n", "operationId": "check-token-support", "security": [ { "apiKey": [] }, { "clientApiKey": [] } ], "tags": [ "Headless" ], "parameters": [ { "$ref": "#/components/parameters/tokenLocator" } ], "responses": { "200": { "description": "The token has been successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportedTokenResponse" } } } }, "400": { "description": "Invalid arguments, please make sure you're following the api specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/400Response" } } } }, "403": { "description": "Forbidden error, please ensure the credentials are correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403Response" } } } }, "404": { "description": "Not found error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/404Response" } } } }, "503": { "description": "Please try again in a few minutes. If the issue still persists, contact Crossmint support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/503Response" } } } }, "524": { "description": "A timeout occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/524Response" } } } } } } }, "/v1-alpha2/tokens": { "get": { "summary": "Get All Tokens", "description": "Get a paginated list of all supported tokens available for checkout. Use this to discover which tokens your users can purchase through Crossmint.\n\n**API scope required**: `tokens.read`\n\n**Rate limit**: 5 requests per minute\n", "operationId": "get-all-tokens", "security": [ { "apiKey": [] } ], "tags": [ "Headless" ], "parameters": [ { "name": "chains", "in": "query", "description": "Filter tokens by blockchain. Provide a comma-separated list of chain names (e.g., `solana,base`).", "required": false, "schema": { "type": "string" }, "example": "solana,base" }, { "name": "tokenClasses", "in": "query", "description": "Filter tokens by category. Provide a comma-separated list of token classes. When omitted, returns all discoverable tokens.", "required": false, "schema": { "type": "string", "enum": ["memecoin", "onramp", "memecoin,onramp"] }, "example": "memecoin" }, { "name": "cursor", "in": "query", "description": "Cursor for pagination. Use the `nextCursor` or `previousCursor` value from a previous response to navigate between pages.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of tokens to return per page. Defaults to 30, maximum is 100.", "required": false, "schema": { "type": "string", "default": "30" }, "example": "30" } ], "responses": { "200": { "description": "A paginated list of supported tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllTokensResponse" } } } }, "400": { "description": "Invalid arguments, please make sure you're following the api specification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/400Response" } } } }, "403": { "description": "Forbidden error, please ensure the credentials are correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/403Response" } } } }, "503": { "description": "Please try again in a few minutes. If the issue still persists, contact Crossmint support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/503Response" } } } }, "524": { "description": "A timeout occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/524Response" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "name": "X-API-KEY", "in": "header" }, "clientApiKey": { "type": "apiKey", "name": "X-API-KEY", "in": "header", "description": "Client API key for public-facing operations" }, "orderClientSecret": { "type": "apiKey", "name": "Authorization", "in": "header" } }, "parameters": { "orderId": { "name": "orderId", "in": "path", "description": "This is the identifier for the order with UUID format.\n\n**Example:** `9c82ef99-617f-497d-9abb-fd355291681b`\n", "required": true, "schema": { "type": "string" } }, "tokenLocator": { "name": "tokenLocator", "in": "path", "description": "A unique identifier used to locate a specific fungible token on a blockchain. Memecoin checkout supports the Solana and Base networks. Format: `:` (e.g. `base:0xa4a2e2ca3fbfe21aed83471d28b6f65a233c6e00`).", "required": true, "schema": { "type": "string", "pattern": "^solana:[1-9A-HJ-NP-Za-km-z]{32,44}$" }, "example": "solana:6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN" } }, "schemas": { "OrderDTO": { "type": "object", "additionalProperties": false, "properties": { "recipient": { "$ref": "#/components/schemas/Recipient" }, "locale": { "$ref": "#/components/schemas/Locale" }, "payment": { "$ref": "#/components/schemas/Payment" } } }, "Recipient": { "oneOf": [ { "type": "object", "title": "Email", "properties": { "email": { "type": "string", "format": "email" }, "physicalAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the recipient" }, "line1": { "type": "string", "description": "Street address, P.O. box, company name, c/o" }, "line2": { "type": "string", "description": "Apartment, suite, unit, building, floor, etc." }, "city": { "type": "string", "description": "City, district, suburb, town, or village" }, "state": { "type": "string", "description": "State, county, province, or region. Required for US addresses." }, "postalCode": { "type": "string", "description": "ZIP or postal code" }, "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2). Currently only US is supported." } }, "required": [ "name", "line1", "city", "postalCode", "country" ], "description": "Physical shipping address for the recipient. Required when purchasing physical products." } }, "required": [ "email" ], "additionalProperties": false, "description": "Recipient of the items being purchased. Crossmint will create a custodial wallet address for the user on the fly, that they can later log in to. If no recipient is passed, an order will be created with the status 'requires-recipient', until you pass one." }, { "type": "object", "title": "Wallet", "properties": { "walletAddress": { "type": "string" }, "physicalAddress": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the recipient" }, "line1": { "type": "string", "description": "Street address, P.O. box, company name, c/o" }, "line2": { "type": "string", "description": "Apartment, suite, unit, building, floor, etc." }, "city": { "type": "string", "description": "City, district, suburb, town, or village" }, "state": { "type": "string", "description": "State, county, province, or region. Required for US addresses." }, "postalCode": { "type": "string", "description": "ZIP or postal code" }, "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2). Currently only US is supported." } }, "required": [ "name", "line1", "city", "postalCode", "country" ], "description": "Physical shipping address for the recipient. Required when purchasing physical products." } }, "required": [ "walletAddress" ], "additionalProperties": false, "description": "Recipient of the items being purchased. If specifying a recipient by wallet address, ensure the address is valid for the chain your **collection** is on, which may differ from the chain the payment is performed on." } ] }, "Locale": { "default": "en-US", "type": "string", "enum": [ "en-US", "es-ES", "fr-FR", "it-IT", "ko-KR", "pt-PT", "ja-JP", "zh-CN", "zh-TW", "de-DE", "ru-RU", "tr-TR", "uk-UA", "th-TH", "vi-VN", "Klingon" ], "example": "en-US", "description": "Locale for the checkout, in IETF BCP 47. It impacts the email receipt language. Ensure your UI is set to the same language as specified here. Throws an error if passed an invalid language." }, "Payment": { "discriminator": { "propertyName": "method" }, "oneOf": [ { "type": "object", "title": "EVM", "additionalProperties": false, "properties": { "receiptEmail": { "type": "string", "format": "email", "description": "Email that the receipt will be sent to." }, "method": { "type": "string", "enum": [ "arbitrum-sepolia", "base-sepolia", "ethereum-sepolia", "optimism-sepolia", "arbitrum", "bsc", "ethereum", "optimism" ] }, "currency": { "type": "string", "enum": [ "eth", "usdc", "degen", "brett", "toshi", "usdxm", "credit" ] }, "payerAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "An EVM wallet address." } }, "required": [ "method", "currency" ] }, { "type": "object", "title": "Solana", "additionalProperties": false, "properties": { "receiptEmail": { "type": "string", "format": "email", "description": "Email that the receipt will be sent to." }, "method": { "type": "string", "enum": [ "solana" ] }, "currency": { "type": "string", "enum": [ "sol", "usdc", "bonk" ] }, "payerAddress": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "A Solana public key." } }, "required": [ "method", "currency" ] }, { "type": "object", "title": "Fiat", "additionalProperties": false, "properties": { "receiptEmail": { "type": "string", "format": "email", "description": "Email that the receipt will be sent to." }, "method": { "type": "string", "enum": [ "card" ] }, "currency": { "default": "usd", "type": "string", "enum": [ "usd", "eur", "aud", "gbp", "jpy", "sgd", "hkd", "krw", "inr", "vnd" ] } }, "required": [ "method" ] } ] }, "LineItems": { "oneOf": [ { "type": "object", "title": "Single Line Item - Collection Locator", "additionalProperties": false, "properties": { "collectionLocator": { "description": "The collection locator of the line item. For example: `crossmint:`. These fields can be retrieved from the Crossmint console.", "type": "string", "example": "crossmint:" }, "callData": { "type": "object", "additionalProperties": {}, "description": "Information that you pass to your contract mint function.", "properties": { "totalPrice": { "description": "The total price of the line item. It must be the same as the contract expects to receive. Read /docs.crossmint.com/payments/advanced/component-properties#mintconfig", "type": "string" } } } }, "required": [ "collectionLocator" ] }, { "type": "object", "title": "Single Line Item - Currency Locator", "additionalProperties": false, "properties": { "currencyLocator": { "type": "string", "description": "Locator for an offramp (fiat payout) order. Format: `fiat:` (e.g. `fiat:usd`).", "example": "fiat:usd" }, "executionParameters": { "type": "object", "description": "Parameters controlling how the offramp payout is executed.", "properties": { "mode": { "type": "string", "enum": ["exact-in"], "description": "Execution mode. Offramp supports `exact-in` (spend an exact USDC amount)." }, "amount": { "type": "string", "description": "The USDC amount to convert and pay out, as a decimal string." } }, "required": ["mode", "amount"] } }, "required": [ "currencyLocator", "executionParameters" ] }, { "type": "object", "title": "Single Line Item - Product Locator", "additionalProperties": false, "properties": { "productLocator": { "description": "The product locator for physical products. For Amazon products, use format `amazon:` (e.g. `amazon:B01DFKC2SO`) or `amazon:` (e.g. `amazon:https://www.amazon.com/dp/B01DFKC2SO`).", "type": "string", "example": "amazon:B01DFKC2SO" } }, "required": [ "productLocator" ] }, { "type": "object", "title": "Single Line Item - Token Locator", "additionalProperties": false, "properties": { "tokenLocator": { "description": "The token locator of the line item. For EVM chains use format `::` (e.g. `ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897:1234`). For Solana use format `solana:` (e.g. `solana:7nE9XwXs3XgpH8rnXMFvQYWZTXUFJyZC4rZ5CPX4X4p5`).", "type": "string", "pattern": "^(ethereum|polygon|optimism|arbitrum|base|zora|avalanche|bsc):[0-9a-fA-F]{40}:\\d+$|^solana:[1-9A-HJ-NP-Za-km-z]{32,44}$" }, "callData": { "type": "object", "additionalProperties": {}, "description": "Information that you pass to your contract mint function.", "properties": { "totalPrice": { "description": "The total price of the line item. It must be the same as the contract expects to receive. Read /docs.crossmint.com/payments/advanced/component-properties#mintconfig", "type": "string" } } }, "executionParameters": { "type": "object", "description": "Parameters for executing the purchase of fungible tokens like memecoins.", "properties": { "mode": { "type": "string", "enum": [ "exact-in" ], "description": "The execution method for the order. 'exact-in' is used for buying fungible tokens like memecoins, specifying the exact amount to spend." }, "amount": { "type": "string", "description": "The amount in USD to spend on the token purchase." }, "maxSlippageBps": { "type": "string", "description": "Optional slippage tolerance in basis points (e.g., '500' for 5%). If not provided, default slippage will be applied." } }, "required": [ "mode", "amount" ] } }, "required": [ "tokenLocator" ] }, { "type": "array", "title": "Multiple Line Items - Collection Locators", "items": { "type": "object", "additionalProperties": false, "properties": { "collectionLocator": { "description": "The collection locator of the line item. For example: `crossmint:`. These fields can be retrieved from the Crossmint console.", "type": "string", "example": "crossmint:" }, "callData": { "type": "object", "additionalProperties": {}, "description": "Information that you pass to your contract mint function.", "properties": { "totalPrice": { "description": "The total price of the line item. It must be the same as the contract expects to receive. Read /docs.crossmint.com/payments/advanced/component-properties#mintconfig", "type": "string" } } } }, "required": [ "collectionLocator" ] } }, { "type": "array", "title": "Multiple Line Items - Token Locators", "items": { "type": "object", "additionalProperties": false, "properties": { "tokenLocator": { "description": "The token locator of the line item. For EVM chains use format `::` (e.g. `ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897:1234`). For Solana use format `solana:` (e.g. `solana:7nE9XwXs3XgpH8rnXMFvQYWZTXUFJyZC4rZ5CPX4X4p5`).", "type": "string", "pattern": "^(ethereum|polygon|optimism|arbitrum|base|zora|avalanche|bsc):[0-9a-fA-F]{40}:\\d+$|^solana:[1-9A-HJ-NP-Za-km-z]{32,44}$" }, "callData": { "type": "object", "additionalProperties": {}, "description": "Information that you pass to your contract mint function.", "properties": { "totalPrice": { "description": "The total price of the line item. It must be the same as the contract expects to receive. Read /docs.crossmint.com/payments/advanced/component-properties#mintconfig", "type": "string", "example": "0.0001" }, "quantityRange": { "type": "object", "description": "The estimated quantity range for memecoin purchases based on market conditions and slippage.", "properties": { "lowerBound": { "type": "string", "description": "The minimum quantity of tokens expected to be received based on current price and slippage.", "example": "0.0265905" }, "upperBound": { "type": "string", "description": "The maximum quantity of tokens expected to be received based on current price and slippage.", "example": "0.0293895" } } } } }, "executionParameters": { "type": "object", "description": "Parameters for executing the purchase of fungible tokens like memecoins.", "properties": { "mode": { "type": "string", "enum": [ "exact-in" ], "description": "The execution method for the order. 'exact-in' is used for buying fungible tokens like memecoins, specifying the exact amount to spend." }, "amount": { "type": "string", "description": "The amount in USD to spend on the token purchase." }, "maxSlippageBps": { "type": "string", "description": "Optional slippage tolerance in basis points (e.g., '500' for 5%). If not provided, default slippage will be applied." } }, "required": [ "mode", "amount" ] } }, "required": [ "tokenLocator" ] } } ] }, "CreateOrderResponse": { "type": "object", "properties": { "clientSecret": { "type": "string", "description": "A token exclusively scoped to a particular order, allowing for the reading or updating of that order.", "example": "_removed_" }, "order": { "$ref": "#/components/schemas/OrderObject" } } }, "ListOrdersResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Page of orders in the requested sort order.", "items": { "$ref": "#/components/schemas/OrderObject" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to fetch the next page. Absent when there are no more results." }, "previousCursor": { "type": "string", "nullable": true, "description": "Cursor to fetch the previous page. Absent on the first page." } } }, "OrderObject": { "type": "object", "properties": { "orderId": { "type": "string", "example": "b2959ca5-65e4-466a-bd26-1bd05cb4f837" }, "phase": { "type": "string", "example": "payment" }, "locale": { "type": "string", "example": "en-US" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string", "example": "polygon-amoy" }, "executionMode": { "type": "string", "enum": ["exact-out", "exact-in"], "description": "Execution mode for the line item. 'exact-out' is used for NFT purchases. 'exact-in' is used for token or memecoin purchases.", "example": "exact-out" }, "quantity": { "type": "number", "example": 1 }, "callData": { "type": "object", "properties": { "quantity": { "type": "number", "example": 1 }, "ADDITIONAL_PROPERTIES": { "type": "string", "example": "Your other mint function arguments" } } }, "executionParams": { "type": "object", "description": "Raw mint arguments for exact-in token or memecoin purchases. Only present when executionMode is 'exact-in'.", "additionalProperties": true }, "maxSlippageBps": { "type": "string", "description": "Slippage tolerance in basis points. Only present when executionMode is 'exact-in'.", "example": "50" }, "metadata": { "type": "object", "properties": { "name": { "type": "string", "example": "Headless Checkout Demo" }, "description": { "type": "string", "example": "NFT Description" }, "imageUrl": { "type": "string", "example": "https://cdn.io/image.png" } } }, "quote": { "type": "object", "properties": { "status": { "type": "string", "example": "valid" }, "charges": { "type": "object", "properties": { "unit": { "type": "object", "properties": { "amount": { "type": "string", "example": "0.0001" }, "currency": { "type": "string", "example": "eth" } } }, "salesTax": { "type": "object", "description": "Sales tax applied to physical product purchases", "properties": { "amount": { "type": "string", "example": "0.34" }, "currency": { "type": "string", "example": "usdc" } } }, "shipping": { "type": "object", "description": "Shipping costs for physical product purchases", "properties": { "amount": { "type": "string", "example": "0" }, "currency": { "type": "string", "example": "usdc" } } } } }, "totalPrice": { "type": "object", "properties": { "amount": { "type": "string", "example": "0.0001" }, "currency": { "type": "string", "example": "eth" } } } } }, "delivery": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "awaiting-payment", "in-progress", "completed", "failed" ], "description": "Status of the delivery. 'awaiting-payment': Initial state before payment is made. 'in-progress': Payment received, transaction submitted but not yet completed. 'completed': Successfully delivered with transaction ID and tokens. 'failed': Delivery failed, typically for refunded transactions.", "example": "awaiting-payment" }, "rail": { "type": "string", "enum": [ "rtp", "fednow", "ach-same-day", "ach-us", "wire", "sepa-instant", "sepa", "spei", "ach-credit" ], "description": "Bank rail the payout was routed over. Present on offramp orders once routing has resolved; immutable thereafter." }, "completedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the fiat payout reached its terminal success signal at the rail. Offramp orders only; present once the delivery is completed, and preserved if a completed payout is later returned. Approximate on delayed rails (ACH, standard SEPA).", "example": "2026-07-27T20:35:00.000Z" }, "recipient": { "type": "object", "properties": { "locator": { "type": "string", "example": "email::" }, "email": { "type": "string", "example": "testy@crossmint.com" }, "walletAddress": { "type": "string", "example": "0x1234abcd..." } } }, "txId": { "type": "string", "description": "The blockchain transaction ID. Only present when status is 'completed'.", "example": "0x2e69f11dae7869b92e3d5eaf4cadd50c48b5c6803d1232815f979d744521ad4c" }, "tokens": { "type": "array", "description": "Array of tokens delivered. Only present when status is 'completed'.", "items": { "type": "object", "properties": { "locator": { "type": "string", "description": "Universal token locator in the format chain:address:tokenId", "example": "polygon:0xE04Cf294985282Ddc088E6433c064cfB85eD9EdA:3" }, "contractAddress": { "type": "string", "description": "The contract address (EVM chains)", "example": "0xE04Cf294985282Ddc088E6433c064cfB85eD9EdA" }, "tokenId": { "type": "string", "description": "The token ID (EVM chains)", "example": "3" }, "mintHash": { "type": "string", "description": "The mint hash or address (Solana)", "example": "MintHashAbc123" }, "quantity": { "type": "string", "description": "The quantity of tokens delivered in smallest units (optional, only for fungible tokens in exact-in mode)", "example": "1500000" }, "symbol": { "type": "string", "description": "The token symbol (optional, only when quantity is present)", "example": "USDC" }, "decimals": { "type": "number", "description": "The number of decimals for the token (optional, only when quantity is present)", "example": 6 } } } } } } } } }, "quote": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "valid", "expired", "all-line-items-unavailable", "requires-physical-address" ], "description": "Status of the quote. 'requires-physical-address' indicates that a shipping address is required for physical products.", "example": "valid" }, "quotedAt": { "type": "string", "example": "2024-06-07T16:55:44.653Z" }, "expiresAt": { "type": "string", "example": "2024-06-07T17:55:44.653Z" }, "totalPrice": { "type": "object", "properties": { "amount": { "type": "string", "example": "0.0001375741" }, "currency": { "type": "string", "example": "eth" } } } } }, "payment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "requires-kyc", "failed-kyc", "manual-kyc", "awaiting-payment", "requires-recipient", "requires-crypto-payer-address", "failed", "in-progress", "completed" ], "description": "Status of the payment. View the status codes for more information.", "example": "awaiting-payment" }, "method": { "type": "string", "example": "base-sepolia" }, "currency": { "type": "string", "example": "eth" }, "preparation": { "type": "object", "properties": { "chain": { "type": "string", "example": "base-sepolia" }, "payerAddress": { "type": "string", "example": "0x1234abcd..." }, "serializedTransaction": { "type": "string", "example": "0x02f90....." } } }, "receiptEmail": { "type": "string", "description": "Email address that the receipt will be sent to.", "example": "user@example.com" }, "received": { "type": "object", "description": "Payment amount received. Present when payment is completed.", "properties": { "amount": { "type": "string", "example": "0.50" }, "currency": { "type": "string", "example": "usd" } } }, "refunded": { "type": "object", "description": "Refund amount and currency. Present when a refund was issued.", "properties": { "amount": { "type": "string", "example": "0.50" }, "currency": { "type": "string", "example": "usd" } } }, "failureReason": { "type": "object", "description": "Reason for payment failure. Present when payment status is 'failed'.", "properties": { "code": { "type": "string", "example": "payment-declined" }, "message": { "type": "string", "example": "The payment was declined by the issuer." } } } } } } }, "400Response": { "type": "object", "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "description": "Human-readable error message describing what went wrong" }, "code": { "type": "string", "description": "Machine-readable error code for programmatic handling", "enum": [ "single_purchase_exceeded", "daily_transaction_exceeded" ] }, "parameters": { "type": "object", "description": "Additional parameters providing context for the error", "properties": { "amount": { "type": "string", "description": "Transaction amount that caused the error" }, "limit": { "type": "string", "description": "The limit that was exceeded" }, "hoursUntilReset": { "type": "string", "description": "Hours until the limit resets" }, "remainingAmount": { "type": "string", "description": "Remaining amount available before hitting the limit" } } } } }, "403Response": { "type": "object", "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Malformed API key. / API key provided doesn't have required scopes." } } }, "404Response": { "type": "object", "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Not found" } } }, "503Response": { "type": "object", "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Please try again in a few minutes. If the issue still persists, contact Crossmint support." } } }, "524Response": { "type": "object", "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "A timeout occurred." } } }, "SupportedTokenResponse": { "type": "object", "title": "The requested token and its availability", "description": "Information regarding the token that was requested and its availability", "properties": { "token": { "type": "string", "description": "The token locator that was queried", "example": "solana:6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN" }, "available": { "type": "boolean", "description": "Whether the token is supported by Crossmint", "example": true }, "features": { "$ref": "#/components/schemas/TokenFeature" } }, "required": [ "token", "available", "features" ] }, "TokenFeature": { "type": "object", "title": "Token features", "description": "The features show if the token is supported for credit card payment.", "properties": { "creditCardPayment": { "type": "boolean", "description": "Whether credit card payment is available for this token", "example": true } }, "required": [ "creditCardPayment" ] }, "GetAllTokensResponse": { "type": "object", "title": "Paginated list of supported tokens", "description": "A paginated response containing a list of supported tokens and cursor for fetching the next page.", "properties": { "data": { "type": "array", "description": "Array of supported tokens", "items": { "$ref": "#/components/schemas/SupportedTokenResponse" } }, "nextCursor": { "type": "string", "description": "Cursor to fetch the next page of results. If not present, there are no more results.", "example": "eyJkYXRhIjp7ImlkIjoiNjk4MGI3NDk4Y2RlNzgwZjk2NWQ1M2RhIiwiY3JlYXRlZEF0IjoiMjAyNC0wMS0wMVQwMDowMDowMy4wMDBaIn0sImRpcmVjdGlvbiI6ImZvcndhcmQiLCJzb3J0T3JkZXIiOiJkZXNjIiwidmVyc2lvbiI6MX0=" }, "previousCursor": { "type": "string", "description": "Cursor to fetch the previous page of results. If not present, you're on the first page.", "example": "eyJkYXRhIjp7ImlkIjoiNjk4MGI3NDk4Y2RlNzgwZjk2NWQ1M2Q2IiwiY3JlYXRlZEF0IjoiMjAyNC0wMS0wMVQwMDowMDowMS4wMDBaIn0sImRpcmVjdGlvbiI6ImJhY2t3YXJkIiwic29ydE9yZGVyIjoiZGVzYyIsInZlcnNpb24iOjF9" } }, "required": [ "data" ] }, "ProcessPaymentInput": { "type": "object", "title": "Crypto Payment", "description": "Process payment using a crypto transaction ID. Use this when the user has already submitted a crypto transaction.", "properties": { "type": { "type": "string", "enum": [ "crypto-tx-id" ], "description": "The type of payment being processed", "example": "crypto-tx-id" }, "txId": { "type": "string", "description": "The transaction ID of the crypto payment", "example": "5UfgJ7vVFmH8K9YxLmNpQrStWvXyZaBcDeFgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLm" } }, "required": [ "type", "txId" ], "additionalProperties": false } } } }