> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/under-the-hood/life-of-a-call.md). # Life of a paid call Follow a paid tool call from discovery through local signing, result checks and payment collection. A paid call has two separate outcomes: the result your agent receives and the money eventually collected for it. This page follows the local `assay-mcp` path after you have enabled paid calls and funded escrow. ## How it works ```mermaid sequenceDiagram participant A as AI client participant L as Local assay-mcp participant S as Assay MCP server participant P as Provider and request verifier participant V as Assay result checks participant E as Escrow contract A->>L: Discover a tool and call it L->>S: Tool call S->>S: Check access, arguments and eligible providers S-->>L: Payment request for selected provider L->>L: Check guards and sign locally L->>S: Same call with signed payment S->>S: Validate payment and reserve funds S->>P: Mapped, signed provider request P->>P: Verify request before serving P-->>S: Result S->>V: Record result for checks S-->>L: Result and receipt, usually VERIFYING L-->>A: Result and receipt V->>V: Apply the tool's policy alt Refund or void V->>S: Release reservation, no collection else Settle the served call V->>S: Allow redemption S->>E: Submit signed payment E->>E: Move customer balance into payment hold alt Timely report upheld S->>E: Refund held payment to customer escrow else Hold ends without a blocking report S->>E: Collect held payment E-->>P: Provider share to payout wallet end end ``` ## One call, step by step 1. **Discover the tool.** Your agent reads the tool list or searches and reads a tool's full description. Discovery supplies its input shape and price. The URL and agent policy determine what it can find. 2. **Choose a provider.** Assay validates arguments and checks available providers against access, provider rules, contract compatibility and payment eligibility. On this paid path it offers a provider without calling that endpoint yet. 3. **Request payment permission.** Assay returns `PAYMENT_REQUIRED`. The request identifies the provider, amount, asset, network, escrow, call identity and payment sequence. No provider call or money reservation happens for this unsigned offer. 4. **Check and sign locally.** `assay-mcp` checks the request against the call it forwarded, a recent quote, its built-in payment configuration, your key permission and limits. It also checks the allowed paid URL, optional provider restriction and any required confirmation. It signs with the local payment key, then resends the same call with the same idempotency key. 5. **Reserve funds and call the provider.** Assay checks the signed payment against the call it computes itself. The retry stays with the offered provider and contract version. It reserves the amount before making the mapped provider request. Normal provider requests carry an Assay request signature; stored authentication headers are attached for their configured origin. 6. **Authenticate and serve.** In a signature-protected setup, the provider's verifier checks the signature, body digest, time window and one-time nonce before the handler runs. The provider returns its data. Assay classifies the response and maps it into the tool's promised shape. 7. **Return the result and check it.** A usable mapped data result is durably recorded for asynchronous checks. The initial receipt normally says `VERIFYING`: the price is held, not yet a final charge. A provider-attributed output shape violation can be refunded immediately. Request or system errors are voided rather than treated as data-quality failures. 8. **Apply the verdict.** An enforcing failure releases the reservation and records a provider strike. A misapplied check voids the payment without a strike. A settling decision permits the signed payment to be submitted on chain; the contract moves funds from the customer balance into a payment hold. 9. **Collect or refund.** The on-chain hold normally lasts one hour from redemption. Assay waits to collect while a qualifying customer report is open and refunds an upheld report while the held-payment refund remains possible. Otherwise collection pays the provider share and platform fee. Use the receipt's filing deadline: the guaranteed reporting window ends before collection becomes eligible. ## Details that affect integrations | Situation | What it means | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | Result received while checking | You have data, but its final charge is still unresolved. Read the receipt status. | | Served call marked `SETTLED` | The service decision is complete. On-chain redemption and provider collection may still be pending. | | Payment cannot be collected before its signing window lapses | A served call can become owed. Paid calls stop until the debt is settled; free calls remain available. | | Network timeout | It does not establish whether the provider ran or payment happened. Reuse the logical operation's idempotency key. | | Provider is no longer eligible on the signed retry | Assay refuses that payment rather than silently paying another provider. | The diagram shows a signed paid call to a signature-protected provider. Free calls and API-key-only endpoints take different paths. Read [How paying works](/developers/use-tools-get-started/how-paying-works.md) for payment setup, [Retries and idempotency](/developers/use-tools-advanced/retries-and-idempotency.md) for uncertain outcomes, and [API key or signature](/developers/list-your-api-get-started/api-key-or-signature.md) for provider authentication. ## Go further * [Access policy](/developers/use-tools-advanced/access-policy.md) * [Spending limits](/developers/use-tools-get-started/spending-limits.md) ## Next * [How calls are verified](/developers/under-the-hood/verification.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.goassay.ai/developers/under-the-hood/life-of-a-call.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.