> ## Documentation Index > Fetch the complete documentation index at: https://monid.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a hosted top-up checkout session > Creates a hosted Stripe checkout session and returns the session id and redirect URL. This is the funding path advertised by the `WALLET_INSUFFICIENT_FUNDS` 402 and by `GET /v1/wallet/balance` (`topup.stripe`): an agent creates the session and hands `url` to its human owner to pay. ## OpenAPI ````yaml https://monid.ai/openapi.json post /v1/wallet/topup/sessions openapi: 3.1.0 info: title: Monid API version: 0.1.0 description: >- Agentic payment platform for data — agents discover and buy data on demand. Authenticated `/v1/*` routes accept a Monid API key or Clerk JWT as a Bearer token. All errors return `{ code, message }`. List endpoints use cursor pagination; consult each operation schema for its last-page cursor encoding. servers: - url: https://api.monid.ai description: Production - url: https://monid.ai description: Public registry alias (public/v1 only) security: [] paths: /v1/wallet/topup/sessions: post: tags: - Wallet summary: Create a hosted top-up checkout session description: >- Creates a hosted Stripe checkout session and returns the session id and redirect URL. This is the funding path advertised by the `WALLET_INSUFFICIENT_FUNDS` 402 and by `GET /v1/wallet/balance` (`topup.stripe`): an agent creates the session and hands `url` to its human owner to pay. parameters: - $ref: '#/components/parameters/AgentModelHeader' - $ref: '#/components/parameters/AgentHarnessHeader' - $ref: '#/components/parameters/AgentSessionIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WalletTopupRequest' responses: '200': description: Checkout session created content: application/json: schema: $ref: '#/components/schemas/WalletTopupSessionResponse' '400': description: Bad request — input failed validation content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — caller has no workspace or no access content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Rate limited (errorCode `RATE_LIMITED`, message `Rate limited. Retry after Ns.`) — the `Retry-After` header carries whole seconds until the caller may retry; `RateLimit-Limit/-Remaining/-Reset` describe the binding limit as numbers only (also sent on allowed responses that matched a rule; responses that matched no rule, or an `unlimited` exemption, carry none of them). Applies to every authenticated `/v1` route (per API key / user / workspace); POST /v1/run additionally enforces per-provider/endpoint run limits. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- Wallet not ACTIVE (provisioning, failed, or being set up). Transient states include a Retry-After header (seconds). headers: Retry-After: description: Seconds to wait before retrying (present for transient states). schema: type: string content: application/json: schema: $ref: '#/components/schemas/WalletUnavailableError' security: - Bearer: - topups:create components: parameters: AgentModelHeader: name: X-Monid-Agent-Model in: header required: false description: >- Model driving the calling agent. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: claude-opus-5-5 AgentHarnessHeader: name: X-Monid-Agent-Harness in: header required: false description: >- Agent harness or client making the call (e.g. a coding agent, an agent framework). Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: claude-code AgentSessionIdHeader: name: X-Monid-Agent-Session-Id in: header required: false description: >- Caller-side session identifier, so the calls of one agent session (discover → inspect → run → polling) can be correlated. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: 01JABCDEF0123456789XYZ schemas: WalletTopupRequest: type: object properties: amount: type: number exclusiveMinimum: 0 description: Top-up amount in dollars (float). example: 25 currency: type: string enum: - USD description: Top-up currency (currently only USD). success_redirect: type: string description: >- Where to send the payer after a successful checkout. Must be on the Monid web-app origin. Defaults to the web-app wallet page, so an agent without a UI can omit it and hand the returned `url` to its owner. example: https://app.monid.ai/wallet?topup=success cancel_redirect: type: string description: >- Where to send the user if checkout is cancelled. Must be on the Monid web-app origin. example: https://app.monid.ai/wallet?topup=cancelled autoReload: type: boolean description: >- Opt in to auto-reload (with the service defaults) when this checkout completes. Opt-in ONLY: the system never enables auto-reload on the caller's behalf, so `false` and an omitted field are equivalent and record nothing. Ignored when auto-reload is already enabled on the wallet. analytics: type: object properties: gaClientId: type: string pattern: ^\d{1,32}\.\d{1,32}$ description: >- GA4 client id of the browser starting this checkout (`gtag('get', …, 'client_id')`). example: '1234567890.1700000000' gaSessionId: type: string pattern: ^\d{1,32}$ description: >- GA4 session id of that browser session (`gtag('get', …, 'session_id')`). example: '1700000000' required: - gaClientId description: >- Analytics attribution hand-off (web app only). Stored as Checkout metadata and forwarded on the server-side GA4 `purchase` event once the session is paid. Never affects the top-up itself; agents can omit it. required: - amount - currency WalletTopupSessionResponse: type: object properties: paymentProcessor: type: string description: Payment processor type (e.g. STRIPE). example: STRIPE sessionId: type: string description: Hosted checkout session id. example: cs_test_... url: type: string description: Hosted checkout redirect URL. example: https://checkout.stripe.com/c/pay/... required: - paymentProcessor - sessionId - url Error: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. example: 400 message: type: string description: Human-readable error description. example: Bad Request hints: type: object additionalProperties: anyOf: - type: string - type: object properties: kind: type: string enum: - command - discover - inspect - run - getRun - stop - releaseResource - topup command: type: string query: type: string provider: type: string endpoint: type: string runId: type: string resourceId: type: string stripe: type: string dashboard: type: string docs: type: string comment: type: string required: - kind description: >- Optional next actions, rendered for the calling client like run-response hints (e.g. the paid TinyFish version on a free-quota 429 — spending permission required). errorCode: type: string enum: - RATE_LIMITED - X402_WORKSPACE_RESOURCES - X402_WORKSPACE_ONLY - X402_ACCRUING_COST - X402_EXCEEDS_SETTLEMENT_WINDOW - X402_VALIDITY_WINDOW_TOO_SHORT - X402_UNBOUNDED_PRICE - X402_PROMOTION - INSUFFICIENT_SCOPE - WALLET_INSUFFICIENT_FUNDS - IDENTITY_PROVIDER_UNKNOWN - IDENTITY_LINK_REQUIRES_SESSION - IDENTITY_LINK_STATE_INVALID - IDENTITY_VERIFICATION_FAILED - IDENTITY_PROVIDER_UNAVAILABLE - IDENTITY_ALREADY_LINKED - IDENTITY_USER_ALREADY_LINKED - IDENTITY_LINK_RATE_LIMITED - IDENTITY_REQUIRED - PROMO_IDENTITY_REDEEMED - PROMO_REDEEM_REQUIRES_SESSION - PROMO_CODE_REDEEMED_BY_WORKSPACE - PROMO_CODE_REDEEMED_BY_USER description: >- OPTIONAL machine-readable discriminant from the documented `ApiErrorCode` registry. Absent on legacy errors; clients MUST treat unknown values as absent. required: - code - message WalletUnavailableError: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. example: 503 message: type: string description: Human-readable error description. example: Wallet is being provisioned. walletStatus: type: - string - 'null' description: >- Wallet provisioning status (e.g. PROVISIONING, FAILED). Null when the wallet does not exist yet. example: PROVISIONING required: - code - message securitySchemes: Bearer: type: http scheme: bearer description: >- Monid API key (`Authorization: Bearer mk_...`) or Clerk-issued JWT. Each operation lists the ONE scope an API key needs. `{resource}:*` grants every action on that resource; `*` grants everything; Clerk sessions hold `*`. Operations with an empty list need no scope. Scope catalog: `GET /v1/api-keys/scopes`. x-aep-authentication-method: api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.