{"openapi":"3.1.0","info":{"title":"Sollection Assistant Actions","version":"1.0.0","description":"Action-safe API for Sollection assistant integrations. AI assistants, LLMs, agents, and automation clients can create invoice intents and read intent/final invoice status, but cannot access wallets or bypass recipient wallet approval."},"servers":[{"url":"https://sollection.xyz"}],"security":[{"gptActionBearerAuth":[]}],"components":{"securitySchemes":{"gptActionBearerAuth":{"type":"http","scheme":"bearer","description":"Dedicated platform-level assistant action API key from SOLLECTION_GPT_ACTION_API_KEY. This is not a merchant API key."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"assistantHint":{"type":"string"}},"required":["message"]}}},"InvoiceIntentCreateRequest":{"type":"object","required":["recipientWallet","lineItems","tokenSymbol"],"properties":{"recipientWallet":{"type":"string","description":"Recipient Solana wallet that must sign on Sollection before a payable invoice exists."},"tokenSymbol":{"type":"string","enum":["USDC","USDT"],"description":"Payment token symbol. Use USDC or USDT."},"tokenMint":{"type":"string","description":"Optional. Only supported mainnet-beta USDC or USDT mint addresses are accepted."},"token":{"type":"string","description":"Backward-compatible token field. Use USDC, USDT, or a supported mainnet-beta mint."},"lineItems":{"type":"array","minItems":1,"items":{"type":"object","required":["description","amount"],"properties":{"description":{"type":"string","example":"Website redesign milestone"},"amount":{"type":"string","example":"250"},"quantity":{"type":"integer","minimum":1,"default":1}}},"description":"Preferred itemized invoice input."},"amount":{"type":"string","description":"Fallback single-line amount. Use with description when lineItems are not supplied."},"description":{"type":"string","description":"Fallback single-line description. Use with amount when lineItems are not supplied."},"customerName":{"type":"string"},"customerEmail":{"type":"string"},"dueDate":{"type":"string","description":"Optional YYYY-MM-DD due date."},"memo":{"type":"string"},"cluster":{"type":"string","enum":["mainnet-beta"],"description":"Solana cluster. Sollection invoice intents currently use mainnet-beta only."}}},"InvoiceIntentCreateResponse":{"type":"object","properties":{"intentId":{"type":"string","example":"intent_abc123"},"status":{"type":"string","enum":["SIGNATURE_REQUIRED"]},"authMode":{"type":"string","enum":["WALLET_APPROVAL"]},"messageForAssistant":{"type":"string"},"preview":{"type":"object","properties":{"customerName":{"type":["string","null"],"example":"PT Maju Jaya"},"customerEmail":{"type":["string","null"],"example":"ap@maju.example"},"subtotal":{"type":"string","example":"250"},"token":{"type":"string","example":"USDC","description":"Backward-compatible token display field."},"tokenSymbol":{"type":"string","example":"USDC"},"tokenMint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"tokenName":{"type":"string","example":"USD Coin"},"tokenType":{"type":"string","enum":["spl"],"example":"spl"},"tokenDecimals":{"type":"integer","example":6},"cluster":{"type":"string","enum":["mainnet-beta"],"example":"mainnet-beta"},"platformFee":{"type":"string","example":"0.625"},"netToRecipient":{"type":"string","example":"249.375"},"recipientWallet":{"type":"string","example":"9xQeWvG816bUx9EPfVRZcM9tixq8r8L7kDDk5T7b1K2a"},"dueDate":{"type":["string","null"],"example":"2026-07-20"},"memo":{"type":["string","null"]},"lineItems":{"type":"array","items":{"type":"object","required":["description","amount"],"properties":{"description":{"type":"string","example":"Website redesign milestone"},"amount":{"type":"string","example":"250"},"quantity":{"type":"integer","minimum":1,"default":1}}}}}},"requiredActions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["WALLET_SIGNATURE_REQUIRED"]},"walletSignUrl":{"type":"string","example":"https://sollection.xyz/sign/invoice-intent/intent_abc123"},"instruction":{"type":"string"}}}},"finalInvoice":{"type":"null"}}},"InvoiceIntentStatusResponse":{"type":"object","properties":{"intentId":{"type":"string","example":"intent_abc123"},"status":{"type":"string","enum":["SIGNATURE_REQUIRED","CONFIRMED","EXPIRED"]},"messageForAssistant":{"type":"string"},"walletSignUrl":{"type":"string"},"finalInvoice":{"type":["object","null"],"properties":{"invoiceId":{"type":"string","example":"inv_abc123"},"status":{"type":"string","enum":["OPEN","PAID","CANCELLED"]},"payUrl":{"type":"string","example":"https://sollection.xyz/pay/pay_abc123"},"x402Url":{"type":"string","example":"https://sollection.xyz/api/x402/pay/pay_abc123"},"statusUrl":{"type":"string","example":"https://sollection.xyz/invoice/inv_abc123/status"},"amount":{"type":"string","example":"250"},"tokenSymbol":{"type":"string","enum":["USDC","USDT"],"example":"USDC"},"tokenName":{"type":"string","example":"USD Coin"},"tokenMint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"tokenType":{"type":"string","enum":["spl"],"example":"spl"},"tokenDecimals":{"type":"integer","example":6},"cluster":{"type":"string","enum":["mainnet-beta"],"example":"mainnet-beta"}}}}},"FinalInvoiceStatusResponse":{"type":"object","properties":{"invoiceId":{"type":"string","example":"inv_abc123"},"status":{"type":"string","enum":["OPEN","PAID","CANCELLED"]},"payUrl":{"type":"string"},"x402Url":{"type":"string"},"statusUrl":{"type":"string"},"amount":{"type":"string"},"token":{"type":"object","properties":{"symbol":{"type":"string","enum":["USDC","USDT"],"example":"USDC"},"name":{"type":"string","example":"USD Coin"},"mint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"type":{"type":"string","enum":["spl"],"example":"spl"},"decimals":{"type":"integer","example":6},"cluster":{"type":"string","enum":["mainnet-beta"],"example":"mainnet-beta"}}},"tokenSymbol":{"type":"string","enum":["USDC","USDT"]},"tokenName":{"type":"string"},"tokenMint":{"type":"string"},"tokenType":{"type":"string","enum":["spl"]},"tokenDecimals":{"type":"integer"},"cluster":{"type":"string","enum":["mainnet-beta"]}}}}},"paths":{"/api/v1/invoice-intents":{"post":{"operationId":"createInvoiceIntent","summary":"Create invoice intent","description":"Creates a non-payable invoice intent using USDC or USDT on Solana mainnet-beta. Returns preview and walletSignUrl. Final invoice links appear only after wallet approval.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceIntentCreateRequest"}}}},"responses":{"201":{"description":"Invoice intent draft requiring wallet approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceIntentCreateResponse"}}}},"400":{"description":"Validation error with assistantHint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/invoice-intents/{intentId}":{"get":{"operationId":"getInvoiceIntent","summary":"Get invoice intent","description":"Checks an invoice intent. If wallet approval is pending, returns walletSignUrl. If approved, returns finalInvoice with payUrl, x402Url, and statusUrl.","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice intent status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceIntentStatusResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/invoices/{invoiceId}":{"get":{"operationId":"getInvoiceStatus","summary":"Get invoice status","description":"Returns public-safe final invoice status and payment links after wallet approval. Only final invoices can include payUrl, x402Url, and statusUrl.","parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Final invoice status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalInvoiceStatusResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}