Commerce guide

Agree on the price. Review the result. Approve the charge.

Commerce lets you run an AI inference task for an agreed fixed price and review the generated text before approving its charge. You reserve existing Pipe credits upfront. Completing the task alone does not charge those credits.

Open Commerce · See a concrete example

What does Commerce do for you?

Commerce adds a price agreement and a separate payment approval step to a single AI inference task. The quote ties your prompt, chosen model and output limit to a fixed price. The result and financial record stay attached to that agreement.

• Know the price before you run: review the full quoted task price before reserving credits or starting inference.
• Keep control of the charge: read the output before deciding to approve payment. Running the task and approving its charge are separate actions.
• Keep records you can check: download signed records that link the agreed terms, returned result and approved charge.

The current release supports one plain-text prompt and generated text per task, using prepaid Pipe credits. It works without a wallet or a Solana transaction, so there is no need to wait for Solana v1. Wallet escrow and ZK billing are not included in this release.

Example: review an announcement draft before approving its charge

You want an AI model to turn a short product brief into an announcement draft. Suppose you have 10 available Pipe credits and the quote is 1 credit. These amounts are illustrative; always use the price in your quote.

1. Get a quote. Review the model, output limit, price and deadlines. Getting or accepting the quote spends nothing. 10 credits available · 0 held · 0 charged.
2. Reserve 1 credit and start. The held credit cannot be spent elsewhere. The hold is not a final charge. 9 credits available · 1 held · 0 charged.
3. Read the draft. Completion does not approve payment. 9 credits available · 1 held · 0 charged.
4. Approve the charge. Confirm the specific result and 1-credit charge. Pipe converts the hold into payment; it does not charge another credit on top. 9 credits available · 0 held · 1 charged.

If you choose not to approve, leave the result unapproved and request release when eligible under the agreement's state and deadlines. A full release restores the 10 available credits. This release flow cannot reverse an already approved charge.

After approval, export the signed agreement, usage receipt and approved settlement record. Signature checks help detect changes and compare the signer with a trusted key. They do not tell you whether the draft is accurate or useful.

When should you use Commerce?

Use Commerce for a person reviewing a draft or summary before approving its charge, an application with an explicit payment approval step, or an AI agent running and tracking an already accepted, funded agreement through A2A. Approve its charge separately through Commerce.

For routine chat or streaming calls with normal usage billing, use the standard inference API. Commerce adds quote, reservation and approval steps for workflows that need those controls. It does not change billing for your other API calls.

Try it in the dashboard

Sign in with an eligible personal Pipe account and add prepaid credits if needed. Open Commerce, choose an available model, enter a short text prompt and request a quote. Follow the separate steps to accept, reserve, start, review and approve. You can read this guide without signing in.

Authentication

Use a personal-account API key with Authorization: Bearer $PIPE_API_KEY for the financial workflow. Dashboard requests use the existing Bearer session. Project-scoped keys cannot use this payment profile.

Discover capabilities

GET https://api.pipenetwork.ai/v1/commerce/capabilities reports supported funding modes, assets, acceptance modes, verification profiles and blockers. Read financial_operations_enabled and admission.allowed before selecting a financial workflow.

Inspect prepaid credit

GET https://api.pipenetwork.ai/v1/commerce/ledger reports the authenticated account in api_credit_micro_v1. One credit is 1,000,000 microcredits. Amounts are decimal strings; use integer arithmetic. inspection.ready does not reserve credit or guarantee future eligibility.

Run a prepaid task through the API

Use the advertised prepaid_fixed_authenticated_v1 profile. Request a fixed-price quote, accept its digest, reserve existing credit and start the task. Review the returned artifact before explicitly approving its exact settlement_intent_digest. Completion never approves payment automatically.

Retries and refunds

Every mutation requires a saved Idempotency-Key. Retry the same command and body after an uncertain response. POST /v1/commerce/tasks/TASK_ID/cancellation requests cancellation; POST /v1/commerce/agreements/ID/refund-intents releases eligible uncharged credit. Deadlines and state checks apply.

Check signed records locally

The Commerce screen verifies canonical bytes, domain-separated SHA-256 digests and Ed25519 signatures on your device. Files are not uploaded. The limit is 1 MiB and 64 signed records.

Signing-key trust

Obtain the expected public key independently. A valid signature does not establish the signer's identity, payment, settlement, execution correctness or a zero-knowledge proof. Authority, chain and proof checks remain not_checked.

Download development sample JSON — no real account, funds, execution or settlement.

Open Commerce · API docs · x402 · Support