Apiosk Connect (Marketplace)

Apiosk Connect is the marketplace track. It lets a third-party marketplace plug its own merchants into the Apiosk payment rail without every merchant integrating the gateway directly. The marketplace owns the customer relationship; Apiosk provides embeddable onboarding, wallet verification, a per-call paywall, and the payout split. Connect is distinct from standalone publishing (see /guides/publishers). A merchant’s billable product is called a skill, and every paid skill call is split three ways: the merchant, the marketplace, and Apiosk’s 2% platform fee.

Connect skills are private. They are reachable only through their own charge_url and never appear in the public catalog (/v1/apis) or in agent discovery. The two tracks share the payment rail, not the catalog.

Keys

A marketplace mints two kinds of key from the portal:

Key	Prefix	Where it lives	Use
Secret key	`apk_live_`	server-side only	Register skills, read fees (server-to-server)
Publishable key	`apk_pub_`	safe to embed in a web page	Powers the “Connect with Apiosk” embed

The secret key is shown once at mint and stored only as a hash, it is never re-displayed. Keep apk_live_ keys server-side; only apk_pub_ keys are safe in client HTML.

1. Set up the marketplace

Create a marketplace in the portal and mint the keys. The first key mint activates the marketplace.

# Secret key (server-side)
curl -X POST https://gateway.apiosk.com/v1/marketplaces/{id}/api-keys \
  -H "Authorization: Bearer <portal-session>"

# Publishable key (embeddable)
curl -X POST https://gateway.apiosk.com/v1/marketplaces/{id}/publishable-keys \
  -H "Authorization: Bearer <portal-session>"

2. Onboard a merchant

There are two ways in. Both end at the same portal wizard and both produce a merchant you can name at checkout, they differ in who starts the flow.

Option A: a hosted onboarding link (server-to-server)

Mint a signed link with your secret key. external_seller_id is required: it is your own ID for this seller, and it is what you will use to name them later.

curl -X POST https://gateway.apiosk.com/v1/merchants/onboarding-link \
  -H "Authorization: Bearer apk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_seller_id": "northwind-research" }'

{ "url": "https://dashboard.apiosk.com/connect/onboard?token=...",
  "token": "...", "expires_at": "..." }

The link is good for 30 minutes. The portal exchanges the token via POST /v1/merchants/onboarding/verify, which upserts on (marketplace_id, external_seller_id), so re-minting a link for a seller you already onboarded resumes them rather than duplicating them. An expired or tampered token answers link_expired or invalid_link.

Option B: the “Connect with Apiosk” embed

Drop the embed on your own site. The publishable key identifies the marketplace; the embed opens a hosted, signed onboarding session in the Apiosk portal.

<script src="https://gateway.apiosk.com/embed.js"
        data-apiosk-key="apk_pub_..."
        data-apiosk-target="#apiosk-connect"></script>

The embed calls POST /v1/connect/embed/start, which validates the publishable key and returns a short-lived merchant session along with the new merchant_id:

{ "merchant_id": "6f1c8e2a-...", "marketplace_id": "...",
  "marketplace_name": "Acme Data Exchange", "session": "...", "status": "draft" }

Because a browser visitor has no ID you assigned, the embed derives one and namespaces it as embed:<ref>, so embed-created sellers can never collide with the IDs you mint yourself.

The wizard

Either way, the portal then walks the merchant through three steps:

Profile, POST /v1/merchants/profile saves display name and contact email.
Wallet, POST /v1/siwe/nonce then POST /v1/siwe/verify prove control of an EVM payout address via a Sign-In-With-Ethereum signature.
Activate, POST /v1/merchants/activate requires a verified wallet and flips the merchant to active.

A merchant can only earn once it is active and has a verified payout wallet. Skill creation and every charge re-check this, an unverified merchant’s skills cannot be charged. Activating without a verified wallet answers 409 wallet_required.

3. Learn when a merchant is ready

When a merchant activates, the gateway posts merchant.activated to your marketplace’s webhook URL. In the link flow this is how you learn the canonical merchant ID.

{ "event": "merchant.activated", "marketplace_id": "...",
  "merchant_id": "6f1c8e2a-...", "ts": 1753209600 }

Headers are x-apiosk-event and x-apiosk-signature, and delivery is retried up to three times.

This signature is a bare HMAC of the body, with no timestamp. The payment webhooks from pay.apiosk.com use a different, timestamped scheme, see /pay/webhooks. Do not share one verifier between them: each will reject the other’s events.

4. How you identify a merchant afterwards

A merchant is named by ID, never by display name. A name is not unique within a marketplace and it changes when a seller renames themselves. Two forms are accepted, and both are always scoped to your own marketplace, so no request can reach or discover another marketplace’s merchants:

Form	Example	Where you got it
Your own `external_seller_id`	`northwind-research`	you supplied it at onboarding
The Connect merchant UUID	`6f1c8e2a-...`	returned by the embed or the activation webhook

Store the ID against your own product listings. You will send it as merchant_id when publishing a skill, and as seller_id when creating a hosted checkout.

5. Publish a skill

With the merchant onboarded, register that merchant’s billable product server-to-server with your secret key. Include an Idempotency-Key so retries never create duplicates.

curl -X POST https://gateway.apiosk.com/v1/skills \
  -H "Authorization: Bearer apk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "6f1c8e2a-...",
    "external_skill_ref": "monthly-report",
    "name": "Monthly report",
    "price_amount": 1000000,
    "price_currency": "USDC"
  }'

The response returns the skill id and a charge_url. A skill snapshots the fee split and the merchant’s wallet at creation, so later config changes never silently re-price an existing product. Use PUT /v1/skills/{id} to change price or the active flag.

6. Charge a skill and split the payment

An agent calls the skill’s charge_url. Unpaid, it returns an x402 402 that advertises the gross price and the split; with a valid x-payment proof the gateway verifies and settles.

# 402 with the payment requirement + split breakdown
curl https://gateway.apiosk.com/v1/skills/{id}/charge

# Pay it
curl https://gateway.apiosk.com/v1/skills/{id}/charge \
  -H "x-payment: <x402-proof>"

The gross amount settles once to the platform wallet, then two payout legs are queued, the merchant (its net share) and the marketplace (its fee) - while Apiosk keeps its 2%. The three amounts always sum to the gross:

Party	Share
Merchant	gross − marketplace fee − 2%
Marketplace	its configured fee
Apiosk	2% platform fee

The skill charge settles once to the platform wallet and splits at payout time, there is no on-chain splitter contract to integrate. The hosted checkout described below works the other way round: it splits on-chain, at payment time.

Selling to humans instead: hosted checkout

A skill charge is an agent paying over x402. When the buyer is a person with a browser, use the hosted checkout at pay.apiosk.com instead: you create a checkout with the same apk_live_ key, redirect the buyer, and the buyer’s own wallet pays the merchant, you, and Apiosk in a single transaction.

curl -X POST https://pay.apiosk.com/v1/checkout \
  -H "Authorization: Bearer apk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "seller_id": "northwind-research", "amount": "12.50",
        "product_name": "Quick company lookup" }'

seller_id takes either merchant ID form from step 4. See /pay/overview.

Hosted checkout: /pay/overview
Naming a seller: /pay/sellers
Publishers (standalone): /guides/publishers
Payment model: /overview/payment-model
Boundaries: /guides/boundaries

​Apiosk Connect (Marketplace)

​Keys

​1. Set up the marketplace

​2. Onboard a merchant

​Option A: a hosted onboarding link (server-to-server)

​Option B: the “Connect with Apiosk” embed

​The wizard

​3. Learn when a merchant is ready

​4. How you identify a merchant afterwards

​5. Publish a skill

​6. Charge a skill and split the payment

​Selling to humans instead: hosted checkout

​Related links

Apiosk Connect (Marketplace)

Keys

1. Set up the marketplace

2. Onboard a merchant

Option A: a hosted onboarding link (server-to-server)

Option B: the “Connect with Apiosk” embed

The wizard

3. Learn when a merchant is ready

4. How you identify a merchant afterwards

5. Publish a skill

6. Charge a skill and split the payment

Selling to humans instead: hosted checkout

Related links