MARCO Connect SDK v2.6.1

The SDK

MARCO Connect is one embeddable SDK. It owns the widget, the wallet lifecycle, Passport discovery and creation, every state, the theme and size systems and accessibility. Your application subscribes to events and reads state — nothing else. Every Melega application and every external developer runs this exact runtime.

Install

One script. mount() returns the SDK instance.

html
<div id="marco-connect"></div>
<script src="https://marco.melega.ai/widgets/marco-connect.v2.1.js" defer></script>
<script>
  window.addEventListener("load", function () {
    var marco = window.MarcoConnect.mount("#marco-connect", {
      application: "Your App",
      theme: "dark",
      size: "standard"
    });

    marco.on("passportResolved", function (e) {
      console.log("passport", e.passport.passportNumber);
    });
  });
</script>

https://marco.melega.ai/widgets/marco-connect.v2.1.js

Methods

connect()Runs the wallet + Passport ceremony.
disconnect()Ends the session and clears state.
open()Expands the connected panel.
close()Collapses the connected panel.
refresh()Re-reads Passport and M-Credits.
getState()Readonly snapshot of the current state.
on(event, fn)Subscribe. Returns an unsubscribe function.
destroy()Unmounts the widget and drops listeners.

Events

Subscribe with on(event, fn). Every subscription returns its own unsubscribe function.

readyThe SDK mounted and read its first state.
connectA wallet session was established.
disconnectThe session ended.
passportResolvedAn existing Passport was found.
passportCreatedA Passport was issued automatically.
errorAny failure, with a stable code.
changeAny state transition.

State

State is readonly and never fabricated. Unknown remains unknown.

statusidle · loading · connecting · connected · disconnected · error
connectedSession present.
loadingFirst read in flight.
syncingBackground refresh in flight.
wallet{ address, chainId } or null.
passport{ passportNumber, publicPassportId, lifecycleStatus } or null.
mCredits{ available, currency, known }. Unknown stays unknown.
applicationThe configured host application name.
versionSDK semantic version.

Configuration

Configuration only. There are no runtime forks.

applicationHost application name.
themedark · light · silver · blue · orange · forest · purple · gold
sizecompact · standard · full · navbar · floating
signatureCommunity signature visibility.
languageBCP-47 tag. 2.0.0 ships en.
originPortal origin used for links and the handshake.

Themes

Blacktheme: "dark"
Whitetheme: "light"
Silvertheme: "silver"
Bluetheme: "blue"
Orangetheme: "orange"
Foresttheme: "forest"
Purpletheme: "purple"
Goldtheme: "gold"

Sizes

Compactsize: "compact"
Standardsize: "standard"
Full widthsize: "full"
Navbarsize: "navbar"
Floatingsize: "floating"
Iconsize: "icon"

Examples

These are not separate integrations. Each one mounts the same SDK runtime.

html
<div id="marco-connect"></div>
<script src="https://marco.melega.ai/widgets/marco-connect.v2.1.js" defer></script>
<script>
  window.addEventListener("load", function () {
    var marco = window.MarcoConnect.mount("#marco-connect", {
      application: "Your App",
      theme: "dark",
      size: "standard"
    });

    marco.on("passportResolved", function (e) {
      console.log("passport", e.passport.passportNumber);
    });
  });
</script>

MARCO Pay widget

MARCO Pay is the payment counterpart of MARCO Connect: the same typography, spacing, geometry, themes and animations. The customer sees a price, pays with MARCO and receives ecosystem rewards. The widget never calculates a reward, never resolves merchant ownership and never creates payment authority — the runtime does all three.

v1.0.2 · https://marco.melega.ai/widgets/marco-pay.v1.js

Installation

html
<marco-pay
  application="your-app-key"
  amount="8900"
  currency="EUR"
  item="Pro plan"
  theme="dark"
  size="standard"
></marco-pay>

<script src="https://marco.melega.ai/widgets/marco-pay.v1.js" defer></script>

States

Ⓜ PAYOne button on your page.
Payment previewAmount, merchant and reward.
ConfirmationConfirm payment.
CompletedReturn to the merchant.

Configuration

merchantMerchant display hint. Ownership is validated server-side.
applicationApplication key the payment originates from.
amountAmount in minor units, as a string.
currencyISO currency code. Default EUR.
marcoAmountMARCO amount in minor units. Optional.
itemProduct or service name shown in the preview.
themedark · light · silver · blue · orange · forest · purple · gold
sizecompact · standard · full · navbar · floating · icon
signatureCommunity signature visibility.
originPortal origin used for links and the quote endpoint.

Events

onReadyThe widget mounted.
onOpenThe customer opened the payment.
onPaymentCreatedA payment was created by the runtime.
onPaymentCompletedThe runtime reported a completed payment.
onRewardReceivedM-Credits were credited to the Passport.
onErrorAny failure, with a stable code.

Themes

Blacktheme: "dark"
Whitetheme: "light"
Silvertheme: "silver"
Bluetheme: "blue"
Orangetheme: "orange"
Foresttheme: "forest"
Purpletheme: "purple"
Goldtheme: "gold"

Examples

html
<marco-pay
  application="your-app-key"
  amount="8900"
  currency="EUR"
  item="Pro plan"
  theme="dark"
  size="standard"
></marco-pay>

<script src="https://marco.melega.ai/widgets/marco-pay.v1.js" defer></script>
js
const pay = window.MarcoPay.mount("#checkout", {
  application: "your-app-key",
  amount: "8900",
  currency: "EUR",
  item: "Pro plan",
  theme: "dark",
  size: "full",
});

pay.on("paymentCompleted", ({ receipt }) => {
  console.log("Paid", receipt.marcoAmountLabel, receipt.rewardLabel);
});
tsx
import { MarcoPay } from "@marco/pay-react";

<MarcoPay
  application="your-app-key"
  amount="8900"
  currency="EUR"
  item="Pro plan"
  theme="dark"
  size="full"
  onPaymentCompleted={(receipt) => console.log(receipt)}
/>;

Versioning

The SDK follows semantic versioning and exposes its version at window.MarcoConnect.version and on state.version. The v1 loader still works: it now delegates to this SDK.

Community Edition

Free forever. The expanded widget carries one discreet signature: “Powered by MARCO Passport”. Enterprise removes it.

Questions

Can I use my existing wallet provider?

Yes. MARCO Connect works with the browser wallets your users already have. It does not replace your wallet stack — it sits on top of it and adds identity.

Do users create an account?

No forms, no passwords. Connecting a wallet resolves an existing MARCO Passport or issues a new one automatically.

Does MARCO custody funds?

No. MARCO Connect never takes custody. Keys stay in the user's wallet and every transaction is signed by the user.

How do Ecosystem Rewards work?

On eligible purchases paid in MARCO, 5% is credited to the user in M-Credits and 1% to the Partner that brought the Passport into the ecosystem.

Can I customize MARCO Connect?

Community ships eight official themes and six sizes. Enterprise adds white-label, custom branding and advanced integrations.

What are M-Credits?

M-Credits are the native reward currency of the Melega Ecosystem. They are earned through eligible activity and spent across ecosystem applications.

How do I earn them?

Every eligible payment made in MARCO generates M-Credits: 5% to the user and 1% to the Partner that brought the Passport into the ecosystem.

Where can I spend them?

Across Melega Ecosystem applications as they activate — Space, featured projects, sponsored visibility, AI services, marketplaces and premium tools. Destinations are marked Coming Soon until they are live.

Do they expire?

M-Credits are ecosystem credits, not temporary coupons. Promotional grants can carry their own validity period, and any such condition is always stated when the grant is issued.

Can projects earn M-Credits?

Yes. A Partner earns 1% in M-Credits on eligible MARCO payments made by the users it brought into the ecosystem.

Why are they different from cashback?

Cashback belongs to one merchant. M-Credits belong to the whole ecosystem: earned in one application, spendable across the others.

Back to Grow with MARCO