K
Kifly
Developer Docs
Agent Integration

Autonomous payments with x402

Your agent pays a Kifly seller in USDC, or OUSD where offered, on Base mainnet (eip155:8453), from a wallet you hold, straight to the seller's wallet. Setting it up with one prompt: the quickstart.

  1. Build a cart: POST /api/agent/cart, then /api/agent/cart/{cart_id}/items and /api/agent/cart/{cart_id}/shipping-address.
  2. POST /api/agent/cart/{cart_id}/checkout with no payment. It answers 402 with a PAYMENT-REQUIRED header listing one requirement per coin.
  3. Sign one requirement with your wallet, using the official x402 client.
  4. Repeat the checkout call with the payment in a PAYMENT-SIGNATURE header (x402 v2), or X-Payment (v1, USDC only). It settles on Base and answers 200 with the receipt.

Get a credential. Paying needs one; prices and the 402 do not. Your agent requests a key with your email; you enter the code we send; done. No dashboard.

Platforms can register their signing domain once; their agents then pay by signing requests (Web Bot Auth). No per-agent key. See signing domains under Authentication.

curl -sS -X POST https://kifly.ai/api/agent/credentials -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"operator_email":"you@example.com","agent_name":"My agent"}'
curl -sS -X POST https://kifly.ai/api/agent/credentials/verify -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"request_id":"<from the first call>","code":"<the emailed code>"}'

The first call answers request_id and expires_at; the second answers key (shown once), key_id, operator_id and scopes. Send the key as Authorization: Bearer <key> on every paid request, and build the cart with it too. One product needs no cart: find it with GET /api/x402/browse and pay its kifly:x402BuyUrl the same way, with the address in an X-Ship-To header. A paid request with no key gets AGENT_CREDENTIAL_REQUIRED; a key whose operator is suspended gets AGENT_OPERATOR_SUSPENDED. Orders stay within max_cart_total_cents from Platform Limits.

curl -sS -i -X POST "https://kifly.ai/api/agent/cart/$CART_ID/checkout" \
  -H "Authorization: Bearer $KIFLY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{}'
npm install @x402/core@2.24.0 @x402/evm@2.24.0 viem@2.55.0
import type { LocalAccount } from "viem";
import { x402Client } from "@x402/core/client";
import { decodePaymentRequiredHeader, encodePaymentSignatureHeader } from "@x402/core/http";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

export async function payCart(cartId: string, account: LocalAccount) {
  const url = `https://kifly.ai/api/agent/cart/${cartId}/checkout`;
  const headers = { authorization: `Bearer ${process.env.KIFLY_API_KEY}`, "content-type": "application/json" };
  const challenge = await fetch(url, {
    method: "POST",
    headers: { ...headers, "idempotency-key": crypto.randomUUID() },
    body: "{}",
  });
  const required = decodePaymentRequiredHeader(challenge.headers.get("payment-required") ?? "");
  const client = new x402Client().setSpendControls({ maxAmountPerPayment: "$5" });
  registerExactEvmScheme(client, { signer: account, networks: ["eip155:8453"] });
  const signature = encodePaymentSignatureHeader(await client.createPaymentPayload(required));
  const paid = await fetch(url, {
    method: "POST",
    headers: { ...headers, "idempotency-key": crypto.randomUUID(), "payment-signature": signature },
    body: "{}",
  });
  return paid.json();
}

The receipt's fulfillment.status is confirmed, processing (paid, the seller is still recording it) or unconfirmed (paid; do not pay again). The x402 client signs nothing over its own spendControls cap, which you set; Kifly does not see it.

Does the seller take stablecoins? Its profile at https://kifly.ai/store/{handle}/.well-known/ucp lists ai.kifly.x402 under ucp.payment_handlers. The 402 is the final word: no PAYMENT-REQUIRED header means use the payment link and let the buyer confirm.

Retries. Every call needs an Idempotency-Key of 16 to 64 characters. Resend a payment with the same key and the same signature and you get the first answer back; a cart is paid once. Codes and fixes: Error Reference.

Security. You hold the wallet key; Kifly never sees it and stores no mandate. Each payment is a fresh signature for one amount and one payee, usable once. The Kifly connector in Claude and ChatGPT never pays: it returns a link the buyer confirms.