Project & developer guide

About PromptKiln

PromptKiln is an AI workbench with wallet sign-in, prepaid account credits and a receipt for every request.

Use the playground to shape a prompt or connect an application through scoped API keys. Both draw on the same account balance and capture the model price version, maximum reservation and measured usage.

Buy AI credits with native USDC. SOL and PKLN holders can convert externally to USDC, then complete checkout. PromptKiln does not execute swaps or accept direct SOL/PKLN treasury deposits. PKLN requires a configured, reviewed project mint.

This remains a development release. Production infrastructure, real provider billing evidence, payment configuration and independent review must be completed before collecting customer funds. PromptKiln is independent and makes no endorsement or investment-return claims.

What works today

Local fixtures and implemented integrations are separated from production activation.

Implemented

Durable inference, exact accounting, API keys, provider usage validation, finalized USDC verification and atomic account-credit purchases.

Recovery and refunds

Signed operator sessions can review uncertain requests, rescan eligible purchases and approve manual treasury refunds. Refund credit stays reserved until verified payment or pre-approval cancellation.

Still required for launch

Verified database backups and restore, a deployed worker, actual OpenAI usage comparison, verified RPC and treasury, user-signed payment/refund validation, monitoring, and independent payment review.

Disabled

Live collection, staking, cashback and redemption remain disabled. The legacy Anchor program is not used for account credits and remains an uncompiled draft.

Service health is a connectivity check, not proof that launch review is complete.

How credits work

AI credits are non-transferable units held in your PromptKiln account. There is no KCU mint or activation step in the account-credit design.

PKLN

The optional project token is a funding source through external conversion, not the service-credit unit. Its mint is not configured yet.

Available credits

Unused credits available for a new AI request. Each request temporarily moves its maximum budget into a reserved hold.

Held and spent

Held credits cannot be spent twice or refunded. Confirmed usage is charged once and the unused reservation returns to available credit.

Refund reservations

A purchase-refund request reserves unused credits until operator review. Approved refunds return native USDC to the original payer after manual treasury signing and finalized verification.

Test credits

Local fixtures have no value, cannot be refunded, and cannot become production credits.

1. Purchase: a unique reference binds a native-USDC payment to your account.
2. Verify: the worker checks finalized settlement and adds account credits exactly once.
3. Request: review the model price and maximum reservation before sending a prompt.
4. Settle: bill measured token usage and release the unused reservation.

Start locally

Run the website, local PostgreSQL and separate worker to explore the isolated test journey.

Choose Start local test, add 1,000 test credits in Fund credit, then submit a prompt in Playground. Funding adds directly to available credit. The fixture produces a labeled deterministic response and never calls a paid provider.

The fixture charges 0.104 test credits. Starting with 1,000 leaves 999.896 test credits. Review the receipt, key limits and ledger entries. No token transfer occurs.

pnpm.cmd install

# Terminal A
pnpm.cmd db:local

# Terminal B
pnpm.cmd db:migrate
pnpm.cmd worker

# Terminal C
pnpm.cmd dev

Test sessions require an explicit setting, a loopback origin and a non-production runtime.

Developer API

Applications submit budgeted text requests and read account-private receipts with scoped API keys.

Create a key with chat:write to submit requests and usage:read to read receipts. Choose an expiry and a lifetime spend limit, which includes both completed charges and outstanding reservations. The secret is displayed once and stored only as a digest.

Live models appear only after provider catalog access confirms a configured, priced model. Local test accounts use kiln-local-fixture instead.

curl http://127.0.0.1:3100/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: my-request-0001" \
  -H "Content-Type: application/json" \
  -d '{"model":"kiln-local-fixture","messages":[{"role":"user","content":"Hello"}],"max_tokens":256}'

POST /api/v1/chat/completions · chat:write

Returns HTTP 202, a request ID and maximum reservation. A separate worker dispatches the request.

GET /api/v1/usage/:requestId · usage:read

Poll for completed, failed or reconciliation status. Receipts include measured usage, captured rates and provider identifiers where available.

GET /api/v1/usage · usage:read

Lists the latest 100 account receipts and balances. Amounts are decimal strings of integer microcredits.

GET /api/v1/models · public

Lists configured, provider-confirmed live models. An empty catalog means no live model is available.

Retries and errors

Reuse the same idempotency key and body to recover a request. Conflicting bodies return 409; invalid keys 401; insufficient credit 402; missing scope 403; quota limits 429.

Bodies are limited to 64 KiB and output to 4,096 tokens. Inspect receipts before submitting a new request after a browser reload.

Pricing & billing

Review a maximum reservation before dispatch. Pay for measured usage using the captured model price version.

Local example: 40 input tokens and 32 output tokens at fixture rates cost 0.104 test credits, with no markup. This fixture is not a live model quote.

Usage & receipts shows the model, price version, provider identifiers, token counts, reservation and final charge. Service receipts are account records; purchase and refund receipts separately record finalized Solana evidence.

Credit denomination

1,000 AI credits represent $1 of listed service usage. One credit equals 1,000,000 microcredits. This is a service-pricing unit, not a token market price or general cash-redemption promise.

Model rates

Input, cached input and output have explicit rates. Reasoning tokens are included in output once. The playground shows configured rates and markup before dispatch.

Reservation

A conservative input bound and maximum output-token setting reserve a spending ceiling. Reserved credits are unavailable to concurrent requests and refunds.

Final charge

Exact integer arithmetic bills actual token counts, rounds upward at accounting boundaries and releases the remainder once.

Failures and uncertainty

A confirmed rejection releases the hold. Timeouts, malformed usage, interruptions and uncertain provider outcomes retain it for operator reconciliation. The worker never automatically retries an uncertain paid request.

Custody, privacy & recovery

Your Solana wallet holds tokens; PromptKiln holds the service-credit ledger. Treasury and operator actions are trust assumptions.

Connecting is read-only. Signing in proves ownership through a separate wallet action. A payment requires a deliberate wallet approval; no signing key is stored by the server. Swaps stay external.

Unused purchased credit can be submitted for manual refund review. The ledger reserves it, an operator approves, the treasury signs the exact native-USDC transfer, and the server verifies finality before retiring credit. Approved uncertain refunds remain reserved; do not send a second transfer.

Prompts are queued server-side and removed after terminal completion by default. Stored response text is cleared after 15 minutes unless retention is enabled. Unresolved work retains data for reconciliation. Prompts are never written on-chain; OpenAI also has its own data policy.

If a request remains queued, check worker health. Reconciliation requires operator review of provider evidence. Operators can release a hold without redispatching the request; any provider charge then becomes an operator expense.

Roadmap & launch requirements

The selected deployment uses Vercel for the website/API and a separate worker container with shared managed PostgreSQL.

Cashback and staking remain separate disabled features. The old KCU program is preserved as a legacy draft and is not a dependency of account credits.

Credentials belong in local or server environment files. Public configuration and missing launch inputs are listed in PRODUCTION.md and LAUNCH-CHECKLIST.md.

1. Verify PostgreSQL backups and restore, deploy the worker container, and configure operator wallets. The database schema and canonical HTTPS origin are configured.
2. Connect a funded OpenAI project and verify real usage charges and failure handling against captured receipts.
3. Configure the selected Solana network, RPC, verified native USDC mint, treasury wallet and canonical token account. PKLN requires its exact public mint.
4. Complete a user-signed devnet purchase and manual refund, duplicate verification, restart recovery, backup restore and monitoring checks.
5. Obtain independent payment/refund review, publish token and refund terms, then deliberately enable both payment release gates.