payments.initiate

Initiate a payment inside the agent vault envelope. An amount at or above the step-up threshold can create a pending payment and return an approval URL if other policy checks pass. The configured worker handles execution. Track the pending payment through settlement; an accepted request is not proof that funds moved.

Metadata

Field	Value
Name	`payments.initiate`
Category	`write`
Required scope	`payments:initiate`
Idempotency key required	yes

Annotations

Annotation	Value
Title	Initiate Payment
Read-only	no
Destructive	yes
Idempotent	yes
Open-world	no
Requires human approval	yes (step-up)

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "counterparty": {
      "type": "object",
      "properties": {
        "address": {
          "type": "string",
          "minLength": 1
        },
        "chain": {
          "type": "string",
          "enum": [
            "eth",
            "base",
            "arb",
            "op",
            "polygon",
            "sol"
          ]
        },
        "token": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "address",
        "chain",
        "token"
      ],
      "additionalProperties": false
    },
    "amount_cents": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "currency": {
      "type": "string",
      "minLength": 1,
      "maxLength": 8
    },
    "memo": {
      "type": "string",
      "maxLength": 280
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    },
    "mcc": {
      "type": "string",
      "minLength": 4,
      "maxLength": 4
    },
    "geo": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    }
  },
  "required": [
    "counterparty",
    "amount_cents",
    "currency",
    "idempotency_key"
  ],
  "additionalProperties": false
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "accepted",
        "pending_step_up"
      ]
    },
    "pending_payment_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "policy_version": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "risk_verdict": {
      "type": "string",
      "enum": [
        "allow",
        "allow_with_step_up"
      ]
    },
    "step_up_url": {
      "type": "string",
      "format": "uri"
    },
    "enqueued_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    }
  },
  "required": [
    "kind",
    "pending_payment_id",
    "policy_version",
    "risk_verdict",
    "enqueued_at"
  ],
  "additionalProperties": false
}

Auth

Caller’s grant must include the payments:initiate scope. Grants whose scope set is a superset of the required scope are accepted.

Request examples

curl -X POST https://mcp.glide.co/mcp/write \
  -H "Authorization: Bearer $GLIDE_GRANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "payments.initiate",
    "params": {
      "counterparty": {
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "chain": "base",
        "token": "USDC"
      },
      "amount_cents": 75000,
      "currency": "USD",
      "memo": "Invoice #INV-2026-0042 — software license renewal",
      "idempotency_key": "inv-2026-0042-payment-attempt-001"
    }
  }'

import { GlideClient } from './glide-client';

const client = new GlideClient({ grantToken: process.env.GLIDE_GRANT_TOKEN! });

const result = await client.call('write', 'payments.initiate', {
  counterparty: {
    address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
    chain: 'base',
    token: 'USDC',
  },
  amount_cents: 75000,
  currency: 'USD',
  memo: 'Invoice #INV-2026-0042 — software license renewal',
  idempotency_key: 'inv-2026-0042-payment-attempt-001',
});

console.log(result);

from glide_client import GlideClient
import os

client = GlideClient(grant_token=os.environ["GLIDE_GRANT_TOKEN"])

result = client.call("write", "payments.initiate", {
    "counterparty": {
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "chain": "base",
        "token": "USDC",
    },
    "amount_cents": 75000,
    "currency": "USD",
    "memo": "Invoice #INV-2026-0042 — software license renewal",
    "idempotency_key": "inv-2026-0042-payment-attempt-001",
})

print(result)

Response examples

Success — payment accepted and queued for broadcast:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "kind": "accepted",
    "pending_payment_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "policy_version": 3,
    "risk_verdict": "allow",
    "enqueued_at": "2026-05-04T12:00:00Z"
  }
}

Step-up required (amount exceeds step_up_amount_cents in the envelope):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32003,
    "message": "amount 750000 requires step-up approval",
    "data": {
      "reason_id": "step_up_required",
      "step_up_url": "https://app.glide.co/step-up/e5f6a7b8-c9d0-1234-efab-345678901234?sigil=tok_abc123"
    }
  }
}

Policy denied — daily cap exceeded:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "daily spend cap of 100000 cents would be exceeded by this payment",
    "data": { "reason_id": "daily_cap_exceeded" }
  }
}

Errors

Code	Name	Cause	Remediation
`-32600`	Invalid request	Malformed JSON-RPC envelope	Check `method`, `jsonrpc`, and `id` fields
`-32602`	Invalid params	Missing required field, chain not in enum, or `idempotency_key` too short	Validate against the input schema before calling
`-32001`	Unauthorized	Missing/expired grant token	Refresh via `agent.grant.refresh`
`-32002`	Policy denied	Amount exceeds per-tx / daily / lifetime cap; counterparty not on allowlist; chain blocked; MCC blocked; geo blocked; sanctions screen hit	Run `payments.simulate` first to identify the blocking axis
`-32003`	Step-up required	Amount is at or above `step_up_amount_cents` in the policy envelope	Open the approval URL for the existing action; see the flow below
`-32004`	Rate limited	Too many initiate calls in a short window	Back off by `retry_after_seconds` in the error `data`
`-32005`	Vault contention	Another payment is being broadcast from the same vault	Retry after the in-flight broadcast completes
`-32603`	Internal error	Server-side error during enqueueing	Retry with the same `idempotency_key`; the call is idempotent

Step-up flow

When the amount is at or above the envelope’s step_up_amount_cents threshold, the server returns -32003 with data.step_up_url. The pending payment or vault proposal already exists. Open that URL for the principal to review and approve the existing action. The reference client returns a StepUpRequired result for this response. Check for it before reading payment fields. An accepted response means the action was enqueued; check its recorded status before treating it as settled. payments.initiate has no step_up_sigil input or client sigil option. Do not create another payment or change the idempotency key to complete approval. Follow the approval URL and monitor the existing action in the audit feed. See Step-up approvals for the approval model and API clients for handling the response.

Overview

Skills

Controls

Runtimes

API reference

payments.initiate

Metadata

Annotations

Input schema

Output schema

Auth

Request examples

Response examples

Errors

Step-up flow

​Metadata

​Annotations

​Input schema

​Output schema

​Auth

​Request examples

​Response examples

​Errors

​Step-up flow

Metadata

Annotations

Input schema

Output schema

Auth

Request examples

Response examples

Errors

Step-up flow