@soledgic/ai

Pre-built Soledgic tools for the Vercel AI SDK. Give AI agents native access to platform payments, wallet balances, creator payouts, and checkout sessions — without writing any glue code.

Installation

npm install @soledgic/ai @soledgic/sdk ai zod

Usage

import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { soledgicTools } from '@soledgic/ai/vercel'

const result = await generateText({
  model: openai('gpt-4o'),
  // Read-only by default. Opt in to mutating tools explicitly:
  tools: soledgicTools({ apiKey: process.env.SOLEDGIC_API_KEY, allowWrites: true }),
  maxSteps: 5,
  prompt: 'Check if creator_maya is eligible for a payout and request one if she is.',
})

The model will automatically call checkPayoutEligibility and then requestPayout in sequence — no manual orchestration needed.

Guardrails (safe by default)

This package follows least privilege. The model only sees the tools you enable:

| Config | Default | Effect | | --- | --- | --- | | allowWrites | false | When false, only read tools are exposed (checkPayoutEligibility, listWallets, listWalletActivity, getApiStatus). The model cannot move money or mutate state. Set true to expose the write tools. | | allowLivePayouts | false | Even with allowWrites: true, requestPayout is blocked on a live key (slk_live_*) unless this is true. | | maxPayoutAmountCents | 5_000_000 ($50k) | requestPayout rejects amounts above this before calling the API. 0 disables the ceiling. | | maxCheckoutAmountCents | 10_000_000 ($100k) | createCheckoutSession rejects amounts above this. 0 disables the ceiling. | | requireWriteConfirmation | true | High-impact money tools require a per-call confirmation phrase (CONFIRM_CREATE_CHECKOUT_SESSION or CONFIRM_REQUEST_PAYOUT) before the API is called. Disable only behind your own human approval gate. |

const tools = soledgicTools({
  apiKey: process.env.SOLEDGIC_API_KEY,
  allowWrites: true,        // expose mutating tools
  allowLivePayouts: true,   // permit ACH payouts on a live key
  maxPayoutAmountCents: 2_000_000, // cap single payout at $20k
  requireWriteConfirmation: true,
})

Blocked calls return a structured { error, hint } to the model rather than throwing, so the agent can explain the limit instead of crashing the run.

Available tools

Read tools are always available. Write tools (marked ✍️) are only exposed when allowWrites: true.

| Tool | Write | Description | | --- | :---: | --- | | checkPayoutEligibility | | Check if a creator can receive a payout right now | | listWallets | | List wallet balances for a creator or user | | listWalletActivity | | List recent ledger entries for a wallet | | getApiStatus | | Check API health and verify the API key | | createParticipant | ✍️ | Create or update a creator account (idempotent) | | createCheckoutSession | ✍️ | Create a hosted payment page (bounded by maxCheckoutAmountCents) | | requestPayout | ✍️ | Initiate an ACH payout (bounded by maxPayoutAmountCents; live needs allowLivePayouts) | | createRefundRequest | ✍️ | Create a buyer-facing refund request | | completeSandboxCheckout | ✍️ | Complete a sandbox checkout (test keys only) |

createCheckoutSession requires confirm: "CONFIRM_CREATE_CHECKOUT_SESSION" on the tool call. requestPayout requires confirm: "CONFIRM_REQUEST_PAYOUT".

Example: full marketplace flow

import { generateText } from 'ai'
import { anthropic } from '@ai-sdk/anthropic'
import { soledgicTools } from '@soledgic/ai/vercel'

const tools = soledgicTools({ apiKey: process.env.SOLEDGIC_API_KEY, allowWrites: true })

// Onboard a creator and create a checkout in one agent call
const { text } = await generateText({
  model: anthropic('claude-sonnet-4-6'),
  tools,
  maxSteps: 10,
  prompt: `
    Onboard a creator with ID "creator_maya", name "Maya Chen", email "[email protected]",
    and a 90% revenue split. Then create a $50 checkout session for a product called
    "UX Course" with success URL https://example.com/success.
    Return the checkout URL.
  `,
})

console.log(text) // → "Here is the checkout URL: https://soledgic.com/pay/..."

Idempotency

• createParticipant — idempotent by externalCreatorId
• requestPayout — pass a stable referenceId; same value on retry won't duplicate
• createRefundRequest — pass a stable idempotencyKey
• completeSandboxCheckout — pass a stable idempotencyKey

Never generate a new ID on retry. Use the same one from the original call.

Sandbox

Use test keys (slk_test_*) for development. completeSandboxCheckout simulates a successful payment without contacting a real processor — use it to test your full agent flow end to end.

const tools = soledgicTools({ apiKey: 'slk_test_your_key', allowWrites: true })

Get a free test key at soledgic.com/signup.

Security

This package makes HTTPS requests to api.soledgic.com only when a tool is invoked. It does not perform background calls, telemetry, or analytics.

Never expose your API key to the browser. Always call these tools from a server-side environment.