Gvnr

Gvnr Account API

The Account API from Gvnr — 7 operation(s) for account.

GitHub OpenAPI

Operations 9

POST /v1/account Provision account #
GET /v1/account/balance Get governance-operation quota #
POST /v1/account/topup-verify Verify on-chain USDC payment and credit account (any amount) #
POST /v1/account/topup-verify/{pack} Verify on-chain USDC payment (back-compat alias) #
GET /v1/account/notification-email Get the configured notification email (used by request_approval) #
POST /v1/account/notification-email Set the email Gvnr notifies when request_approval fires #
DELETE /v1/account/notification-email Clear the configured notification email (right-to-erasure) #
POST /v1/account/topup x402-gated pay-as-you-go top-up — name your own USD amount; pays on-chain via… #
POST /v1/account/topup/{pack} x402-gated machine credit top-up — pays on-chain via the x402 protocol and… #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/gvnr-dev/openapi/gvnr-dev-account-api-openapi.yml

Other Resources

🔗
APIsJSON
https://artifacts.apis.io/gvnr-dev/apis.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/gvnr-dev:gvnr-dev-account-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

gvnr-dev-account-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Gvnr Account API
  version: 1.8.1
  description: Budget & cost control for AI agents — per-agent spend caps, rate limits, idempotency, post-call reconciliation, and human approval bridges, enforced before each call.
servers:
- url: https://gvnr.dev
tags:
- name: Account
paths:
  /v1/account:
    post:
      summary: Provision account
      responses:
        '201':
          description: Account created — returns api_key (use as Bearer token) and account_id
          content:
            application/json:
              schema:
                type: object
                required:
                - api_key
                - account_id
                properties:
                  api_key:
                    type: string
                    description: Bearer token for subsequent requests; format `bg_...`
                  account_id:
                    type: string
                    description: Stable account identifier
        '429':
          description: Rate limited (account provisioning is per-IP capped)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: postV1Account
      x-operation-id-source: derived
  /v1/account/balance:
    get:
      summary: Get governance-operation quota
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Remaining governance operations on the account
          content:
            application/json:
              schema:
                type: object
                required:
                - operations_remaining
                properties:
                  operations_remaining:
                    type: integer
                    description: Governance operations remaining (one budget_clear = one op)
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: getV1AccountBalance
      x-operation-id-source: derived
  /v1/account/topup-verify:
    post:
      summary: Verify on-chain USDC payment and credit account (any amount)
      description: 'Pay-as-you-go: submit a Base USDC transaction hash; ops are credited proportional to however much USDC actually arrived at the receiving address (1,000 ops per $1). Any amount works — nothing is rejected or wasted.'
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tx_hash:
                  type: string
                  description: Base mainnet USDC transaction hash (0x-prefixed, 64 hex chars)
              required:
              - tx_hash
      responses:
        '200':
          description: Credits applied (or already_credited=true if tx was previously verified)
          content:
            application/json:
              schema:
                type: object
                required:
                - operations_remaining
                properties:
                  operations_remaining:
                    type: integer
                    description: Governance operations remaining after credit
                  credited_ops:
                    type: integer
                    description: Governance operations granted (floor(usd × 1000))
                  credited_usd:
                    type: number
                    description: USD value of USDC received on-chain
                  already_credited:
                    type: boolean
                    description: True if this tx_hash was previously verified (idempotent replay)
        default:
          description: Error (invalid_tx_hash, misconfigured_network, on-chain verification failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: postV1AccountTopupVerify
      x-operation-id-source: derived
  /v1/account/topup-verify/{pack}:
    post:
      summary: Verify on-chain USDC payment (back-compat alias)
      description: Back-compat alias for POST /v1/account/topup-verify. The {pack} segment is ignored; ops are credited proportional to the actual USDC received.
      security:
      - bearerAuth: []
      parameters:
      - name: pack
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tx_hash:
                  type: string
                  description: Base mainnet USDC transaction hash (0x-prefixed, 64 hex chars)
              required:
              - tx_hash
      responses:
        '200':
          description: Credits applied (or already_credited=true if tx was previously verified)
          content:
            application/json:
              schema:
                type: object
                required:
                - operations_remaining
                properties:
                  operations_remaining:
                    type: integer
                    description: Governance operations remaining after credit
                  credited_ops:
                    type: integer
                    description: Governance operations granted (floor(usd × 1000))
                  credited_usd:
                    type: number
                    description: USD value of USDC received on-chain
                  already_credited:
                    type: boolean
                    description: True if this tx_hash was previously verified (idempotent replay)
        default:
          description: Error (invalid_tx_hash, misconfigured_network, on-chain verification failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: postV1AccountTopupVerifyByPack
      x-operation-id-source: derived
  /v1/account/notification-email:
    get:
      summary: Get the configured notification email (used by request_approval)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Returns the configured email (null if unset)
          content:
            application/json:
              schema:
                type: object
                required:
                - notification_email
                properties:
                  notification_email:
                    type:
                    - string
                    - 'null'
                    format: email
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: getV1AccountNotificationEmail
      x-operation-id-source: derived
    post:
      summary: Set the email Gvnr notifies when request_approval fires
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
              required:
              - email
      responses:
        '200':
          description: Email stored
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - notification_email
                properties:
                  ok:
                    type: boolean
                    enum:
                    - true
                  notification_email:
                    type: string
                    format: email
        default:
          description: Error (invalid_email)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: postV1AccountNotificationEmail
      x-operation-id-source: derived
    delete:
      summary: Clear the configured notification email (right-to-erasure)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Email cleared (or was already unset — idempotent)
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                properties:
                  ok:
                    type: boolean
                    enum:
                    - true
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: deleteV1AccountNotificationEmail
      x-operation-id-source: derived
  /v1/account/topup:
    post:
      summary: x402-gated pay-as-you-go top-up — name your own USD amount; pays on-chain via…
      description: 'Pay-as-you-go: pass ?usd= (min $1, max $100). Returns 402 Payment Required with x402 headers quoting exactly that amount if no payment is present; pair with an x402 client which signs payment and re-requests automatically. Credits floor(usd × 1000) governance ops. For fixed preset amounts, use POST /v1/account/topup/{pack} instead.'
      security:
      - bearerAuth: []
      parameters:
      - name: usd
        in: query
        required: true
        schema:
          type: number
          minimum: 1
          maximum: 100
        description: Top-up amount in USD (canonicalized to whole cents)
      responses:
        '200':
          description: Payment verified, credits applied
          content:
            application/json:
              schema:
                type: object
                required:
                - operations_remaining
                - credited_ops
                - credited_usd
                properties:
                  operations_remaining:
                    type: integer
                    description: Governance operations remaining after credit
                  credited_ops:
                    type: integer
                    description: Governance operations granted (floor(usd × 1000))
                  credited_usd:
                    type: number
                    description: USD amount credited (the quoted, verified amount)
        '400':
          description: Error (invalid_amount, below_minimum, above_maximum)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required — x402 headers contain the payment instructions (network, asset, amount, payto address)
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: postV1AccountTopup
      x-operation-id-source: derived
  /v1/account/topup/{pack}:
    post:
      summary: x402-gated machine credit top-up — pays on-chain via the x402 protocol and…
      description: Returns 402 Payment Required with x402 headers if no payment is present. Pair with an x402 client (e.g. x402-fetch from Coinbase) which signs payment and re-requests automatically.
      security:
      - bearerAuth: []
      parameters:
      - name: pack
        in: path
        required: true
        schema:
          type: string
          enum:
          - starter
          - growth
          - studio
      responses:
        '200':
          description: Payment verified, credits applied
          content:
            application/json:
              schema:
                type: object
                required:
                - operations_remaining
                - pack
                properties:
                  operations_remaining:
                    type: integer
                    description: Governance operations remaining after credit
                  pack:
                    type: string
                    enum:
                    - starter
                    - growth
                    - studio
                  credited_ops:
                    type: integer
                    description: Governance operations granted by this pack
        '402':
          description: Payment Required — x402 headers contain the payment instructions (network, asset, amount, payto address)
        default:
          description: Error (invalid_pack, misconfigured_network)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Account
      operationId: postV1AccountTopupByPack
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Stable machine-readable error code (e.g. "invalid_params", "rate_limited", "not_found")
        required:
          type: array
          items:
            type: string
          description: Names/descriptors of required fields when error is "invalid_params"
        hint:
          type: string
          description: Human-readable guidance for resolving the error
        detail:
          type: string
          description: Additional context for the error
        valid:
          type: array
          items:
            type: string
          description: Allowed values when input was rejected as out-of-set
        valid_channels:
          type: array
          items:
            type: string
          description: Allowed notification channels (for approval requests)
        retryable:
          type: boolean
          description: Whether retrying the same request can succeed. false = fix input / auth / config first, or terminal. Omitted when retryability is already implied by required/valid (fix the input) or retry_after_ms (wait, then retry).
        retry_after_ms:
          type: integer
          description: Milliseconds to wait before retrying — present on rate_limited (429). Matches the runtime rate_check field.
        limit:
          type: string
          description: Description of the limit that was hit
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from POST /v1/account