OPENADS AGENT GUIDE
2026-10-12 / advertiser agents

Prepare a real campaign, obtain approval, and return its actual status.
This guide is not payment authorization.

Before starting
- Production agent real-payment verification covers Website Ads on Arc
  (chain_id 5042) and Website Ads Center Popup (300X250) on Base (8453).
  Base verification includes exact-shortfall funding, campaign/channel ACTIVE,
  owner dashboard and performance API reads, and retry without another payment.
  Confirm the format and budget with the user. Other Base Website Ads formats
  and Share/Earn agent paid activation are not covered by these checks.
- Read ./openapi.json relative to this document. API origin:
  https://api.openads.world (not the HTML page's origin).
- Set up document reading, authenticated HTTP requests and an advertiser-owned
  wallet integration. Help the user complete any missing setup before proceeding.
- For payment inside the agent, use a connected EOA transaction-signing tool.
  The SDK needs getSigner(chainId), a provider and signTransaction; see the
  primary setup in ./integration.txt. Do not assume a chat has a wallet tool.
- Wallet signing options, reviewed payment addresses, input limits and exact
  HTTP/payment rules: ./integration.txt.
  Read it before configuring a client or implementing direct API calls.
- Use the documented production APIs and preserve their authentication,
  approval and retry rules. Do not substitute a different payment flow.

1. Collect the details
Ask for all missing details together: destination URL, campaign name, ad
title/message, actual image files, channel/format, budget per channel/format,
payment network and advertiser wallet. Do not choose budgets or networks for
the user. Suggested copy must be reviewed before launch.

2. Prepare without payment
Use one stable operation_id and a private journal for this wallet. Preserve
input, campaign IDs/versions and transaction records for retries.
With the optional SDK, call prepare_campaign(input): login, read current policy,
create draft, upload images, save and submit review. It makes no USDC approval
or deposit. The exact input and draft rules are in ./sdk/plan.mjs.
Continue only when ready is true and every selected format has approved review.
If using direct HTTP, follow the sequence in ./integration.txt.

3. Get approval
Show the actual ad, destination, formats, network, current unit prices and
budget per format/total. Obtain approval for this exact campaign and maximum
budget before launching. For SDK transaction signing, also obtain approval for
the per-transaction execution-gas cap. For browser payment, have the user
review and approve actual gas in their wallet before each transaction.
The preparation preview does not provide live balance, funding shortfall or
gas estimates. Label these unavailable until the API/wallet supplies them.
review-launch determines the existing balance applied and additional USDC.
It can activate a campaign using existing funds, so it also requires approval.
Estimate actual transaction gas through the wallet before payment signing.
If costs exceed approval or remain outside its scope, ask again or stop.
A prepared_hash checks integrity; it does not prove user consent. The caller
must obtain consent or enforce an existing wallet policy covering these actions.
Never request private keys or seed phrases in chat.

4. Launch and fund only the shortfall
With the SDK, call launch_campaign({operation_id, approval}). Approval includes
prepared_hash and max_budget_usdc. Transaction-signing adapters also require
max_transaction_gas_wei; browser-wallet mode reviews actual gas in the wallet.
The client checks the campaign and policy before its initial launch request,
then matches the funding response to reviewed USDC/Vault configuration.
With browserCampaignAgent, COMPLETE_PAYMENT_IN_BROWSER returns the same
campaign's launch_url and actual payment breakdown. Open the link with the
same wallet and have the user press Continue and confirm the wallet transactions.
Do not create another campaign or send a second SDK deposit. Read the campaign
after payment to confirm activation. The SDK never broadcasts in this mode.
Use existing advertiser funds first. If more funds are needed, approve only
the shortfall and deposit it into the advertising Vault. Zero shortfall means
no new USDC deposit. Wait for approval confirmation before sending a deposit.
When existing credit covers the budget, launch can complete without a new
transaction. Report credit allocated separately from new USDC deposited and gas.
Preserve signed bytes/hash/nonce before broadcast, and register the deposit
hash. Detailed signature and destination checks are in ./integration.txt.
Arc gas uses native USDC; Base gas uses ETH. Base L1 data fees are additional
and are not covered by the SDK's execution-gas cap.

5. Confirm the result
Call get_campaign({campaign_id}) or GET /api/v2/campaigns/{id}.
Only say live when effective_status is ACTIVE (SDK: status) AND every selected
surface/format is active. A receipt or accepted funding submission is not enough.
Campaign activation and funding status are separate facts. If the campaign
read omits current funding status, report it as unavailable; do not repeat an
old PENDING value or initiate another payment for an already ACTIVE campaign.
Return campaign ID, actual status, transaction hash if any and:
https://www.openads.world/my-campaigns.html?campaign=<id>
This opens the selected campaign in My Campaigns and requires the same owner's
wallet login. Never put session tokens in the URL.
For pending/error/partial activation, explain the actual state and next step.
Tell the user to open My Campaigns with the same advertiser wallet to view
channel results, budgets, spend and status, or to pause, resume or end a campaign.
For a performance update, use get_campaign_performance({campaign_id}) or GET
/api/v2/campaigns/{id}. The SDK read returns performance with campaign/channel
budgets, spend, committed remaining budget and results. It never submits a
funding transaction or changes the campaign. Reuse the same authenticated
session; read once when asked, without background polling.
Report Website Ads impressions/clicks, qualified Share clicks and completed
Earn visits only for selected channels. Amounts ending _micro are integer
micro-USDC strings: divide by 1,000,000 using exact decimal arithmetic.
null means unavailable, not zero. Remaining committed budget is advertising
credit in this campaign, not a cash refund. After ending, pending activity must
settle before unused credit can be allocated to another campaign on that network.
When SETTLED, committed remaining can be zero because credit is no longer held
by that campaign. Direct the user to All campaigns for available advertising credit.
Include the actual status and as_of when supplied. Do not claim purchases or
sign-ups on the destination site are measured. For management, direct the user
to Pause / Resume / End in My Campaigns; this SDK has no management commands.
Advertising deposits are non-refundable. Do not promise money back to the
wallet or describe advertising credit as a cash refund.

Recovery rules
- Complete denial and recovery instructions: ./errors.txt. Follow next_action
  and retryable from the existing API error envelope or the SDK's error.toJSON().
  A 503 setup/disabled-feature error is not automatically retryable.
- SDK errors: catch and report error.toJSON(), including next_action and exact
  shortfall details when present. For insufficient USDC/native gas, request
  funds on the selected chain and resume the same operation. For cancelled
  signatures, get consent before retrying. Do not expose raw wallet errors.
- A payment_error in a pending result is not success. Check its saved hash;
  an unknown submission must never trigger a newly signed replacement payment.
- Lost response or pending transaction: resume the SAME operation, idempotency
  keys, funding_ref and saved signed transaction. Do not create a second payment
  or delete the journal. Follow the client's next_action when supplied.
- Changed creative/version/pricing: stop new funding and obtain fresh approval.
  Resolve any already-signed payment before preparing a replacement operation.
- CAMPAIGN_ASSET_EXPIRED / PREPARE_NEW_CAMPAIGN: prepare a new campaign and get
  approval. Never automatically repay. Expiry rules are in ./integration.txt.
- Reverted transaction or closed/expired intent: report it; no automatic repayment.
- 429/503: honor Retry-After when supplied; otherwise use bounded backoff.
  Reuse the same operation after waiting; do not create another payment.
  No tight or endless polling. An active attempt may be checked every 10-30
  seconds for up to two minutes, then reported as pending for a later check.
- Missing tools, API, signer or reviewed payment config: name what is missing
  and stop. Do not invent success or bypass wallet confirmation.