> ## Documentation Index > Fetch the complete documentation index at: https://paymanai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # The canonical payman_money_task tool definition > The exact object a developer pastes into their agent's `tools` array, plus the four documented result shapes and the wire conditions that produce them. ## OpenAPI ````yaml /api-reference/openapi.yaml get /connect/tool-definition openapi: 3.0.3 info: title: Payman Connect API version: 0.1.0 description: >- The HTTP contract behind Payman Connect: exchange a customer's consent for a grant, send actions against the accounts it reaches, and follow an approval to its receipt. Every call carries your app key, and every call after the exchange carries the grant. Non-2xx responses share one `ApiError` envelope. Most integrations never write these calls: the SDK speaks them for you. servers: - url: https://api.paygent.payman.ai description: Production - url: http://localhost:8891 description: A local stack security: - bearerAuth: [] tags: - name: Connect description: >- Third-party access. A registered app presents its app key together with a grant token its customer consented to; the pair reaches exactly the one deployment the grant names, and nothing else on this API. paths: /connect/tool-definition: get: tags: - Connect summary: The canonical payman_money_task tool definition description: >- The exact object a developer pastes into their agent's `tools` array, plus the four documented result shapes and the wire conditions that produce them. operationId: getConnectToolDefinition responses: '200': description: The tool definition and its result shapes content: application/json: schema: $ref: '#/components/schemas/ConnectToolDefinition' security: [] components: schemas: ConnectToolDefinition: type: object required: - version - tool - resultStatuses - results - wireMapping - approvalSignal - notes description: >- The canonical `payman_money_task` contract: the tool object to paste, the result shapes to switch on, the wire conditions that produce them, and the standing rules for the app. properties: version: type: string example: '2026-08-09' description: >- The date this contract was settled. Deliberately not the server's version — the tool is older and slower-moving than the build that happens to be serving it, and tying the two would announce a change on every unrelated release. tool: $ref: '#/components/schemas/ConnectToolSpec' resultStatuses: type: array items: $ref: '#/components/schemas/ConnectToolResultStatus' description: >- The discriminator's domain, listed once so a consumer can switch on it. results: type: array items: $ref: '#/components/schemas/ConnectToolResultSpec' wireMapping: type: array items: $ref: '#/components/schemas/ConnectToolWireMapping' approvalSignal: $ref: '#/components/schemas/ConnectApprovalSignal' notes: type: array items: type: string description: >- Standing rules for the app, none of which the model ever sees — where the credentials live, why `sessionId` is app-owned, and which identifiers stay in the HTTP layer. ConnectToolSpec: type: object required: - name - description - input_schema description: >- The paste-ready object, in the shape a tool-calling API wants: `name`, `description`, `input_schema`. snake_case here is not a slip — these are the wire names of the target API, and renaming them to match this server's camelCase would break the copy-paste this endpoint exists for. properties: name: type: string example: payman_money_task description: type: string description: >- The full tool description the model reads — when to call it, when not to, and how to speak about what comes back. input_schema: type: object additionalProperties: true description: >- JSON Schema for the tool's input. One required string, `instruction`, and `additionalProperties: false`. Everything else the API accepts is app-owned (`sessionId`), forbidden (the credentials), or nonexistent on this surface (`deploymentId`). ConnectToolResultStatus: type: string enum: - success - needs_connection - approval_required - error description: >- The four result shapes, and the domain of the result envelope's discriminator. ConnectToolResultSpec: type: object required: - status - when - fields - appAction - example properties: status: $ref: '#/components/schemas/ConnectToolResultStatus' when: type: string description: The observed wire condition that produces this shape. fields: type: object additionalProperties: $ref: '#/components/schemas/ConnectToolFieldSpec' appAction: type: string description: >- What the *app* — not the model — must do on receiving it. The two audiences are kept apart on purpose: `needs_connection` is where the app renders the connect button, and that is not something the model should be told to describe in a URL. example: type: object additionalProperties: true description: >- A complete, literal instance. Its keys are exactly `fields`' keys — a test asserts it, so an example cannot drift from the shape it is supposed to illustrate. ConnectToolWireMapping: type: object required: - observed - status description: How an observed HTTP response maps onto a result shape. properties: observed: type: string status: $ref: '#/components/schemas/ConnectToolResultStatus' note: type: string ConnectApprovalSignal: type: object required: - transport - fields - example - verify - handshake - fallback description: >- The `postMessage` the hosted approval page sends back to the window that opened it — payload, checks and fallbacks. properties: transport: type: string description: How it arrives, and to which origin it is sent. fields: type: object additionalProperties: $ref: '#/components/schemas/ConnectToolFieldSpec' example: type: object additionalProperties: true description: >- A complete, literal instance — the exact bytes to match. Its keys are exactly `fields`' keys. verify: type: array items: type: string description: >- What the app must check, in order, before acting on one. The origin check is first and is the whole security of the arrangement: a `message` event arrives from anything that can reach the window, so a listener that skipped it would let any page on the internet say "approved" and trigger a real payment. handshake: $ref: '#/components/schemas/ConnectApprovalHandshake' fallback: type: string description: What to do when the popup is blocked or the message is lost. ConnectToolFieldSpec: type: object required: - type - description description: One field of one result shape, as a developer needs to read it. properties: type: type: string description: JSON type, spelled as a union where the field is nullable. description: type: string ConnectApprovalHandshake: type: object required: - why - transport - fields - example - send - accepted - withoutAWindowHandle description: >- The `postMessage` the APP sends into the popup, which is what makes the popup's answer deliverable at all. properties: why: type: string description: Why an app has to send it, stated rather than implied. transport: type: string description: >- How it goes out, to which origin, and at what cadence. The interval is not decoration: the popup may still be loading, or part-way through a sign-in bounce, when the first one is posted. fields: type: object additionalProperties: $ref: '#/components/schemas/ConnectToolFieldSpec' example: type: object additionalProperties: true description: >- A complete, literal instance — the exact bytes to send. Its keys are exactly `fields`' keys. send: type: array items: type: string description: The steps the app performs, in order. accepted: type: string description: >- What Payman checks before adopting the origin a handshake arrived from — the opener relationship, a real cross-origin http(s) origin, and a `ref` matching the ticket already on screen. withoutAWindowHandle: type: string description: >- The one integration shape that cannot send it — a plain `target="_blank"` link — and the referrer policy that covers it. ````