Documentation v1.24
Last updated 2026-08-20 Give feedback

Getting Started

Install the MagicPay skill, let `magicpay setup next` guide account connection, then top up MagicCard before the first low-risk payment session.

Get Started With UI

Use this path when you want to set up the human control surface first. The UI lets you manage MagicCard state, review sessions, respond to requests, create UI-connected agent prompts, and choose the platform where approvals should arrive.

  1. Create an account with email, Apple, or Google. Email signup uses an OTP.
  2. Create or link the Mercuryo payment account for the same email.
  3. Complete identity verification (KYC) in the Mercuryo verification flow opened from MagicPay.
  4. Top up the MagicCard balance. Crypto top-up is available now; fiat top-up depends on the active provider route.
  5. Open the Web app, mobile app, ChatGPT app, Claude app, or Telegram miniapp and choose the request channels you want to use.
  6. Create an agent from the UI when you want MagicPay to generate a setup-token prompt for that specific agent.
  7. Add useful Memory such as delivery addresses, logins, or passport details from the UI before a session needs them.

Get Started With The Agent

Use this path when you already know which agent runtime should pay for you. The agent setup flow installs the MagicPay skill, asks `magicpay setup next` for the exact next step, and then relies on requests whenever user approval or Memory data is needed.

  1. Send the agent Set up MagicPay from https://magiccard.ai/skill.md or use the platform-specific prompt shown by the landing page.
  2. The skill installs or repairs the MagicPay CLI and verifies that magicpay --help includes setup next.
  3. The skill runs magicpay setup next --intent landing --platform <runtime> --agent-name "<runtime> Agent" --api-url https://durcottggsiesxxqzvbb.supabase.co/functions/v1/api --env production and follows the returned instructions exactly.
  4. If setup asks for email and OTP, provide them only through the setup flow. If an existing connection is found, choose reuse or another email explicitly.
  5. After setup succeeds, let the skill run magicpay status and generate a hosted MagicCard top-up link when needed.
  6. Ask for a small, specific first task with a clear success condition, such as a low-risk checkout or a page you already trust.
  7. Let the agent create the payment session and wait for MagicPay requests when approval, choice, login, identity data, or payment execution is required.
  8. Approve or deny requests in whichever MagicPay app you prefer.
  9. Review the session events after the run and save any reusable Memory items or preferences that make the next session smoother.

What Both Paths Need

Both paths lead to the same operating model: the user owns payment authority, MagicPay owns Memory request handling, and the agent continues only after the required approvals or protected actions complete.

  • A user account with a linked Mercuryo payment account.
  • Completed KYC for the supported region.
  • A funded MagicCard balance.
  • At least one enabled request channel for approvals and confirmations.
  • An installed MagicPay skill plus a CLI whose help output includes `setup next`.
  • A constrained first purchase that is easy to verify.
MagicPay public documentation.