OpenAds · Agents

Create a campaign with your agent.

Share your ad details, review the campaign and approve the costs.

Start with your agent

Paste into your agent’s chat.

Channels & pricing

8 Oct reference

Website Ads

Minimum rates per 1,000 qualified impressions

Format	USDC
Icon 64 × 64	0.70
Top banner 320 × 50	1.00
Bottom banner 320 × 50	1.00
Popup 300 × 250	1.50

Budget per format must cover its chosen rate.

Share Ads

0.050 USDC per qualified click.

Minimum budget: 5 USDC per channel.

Earn Ads

0.025 USDC per completed visit.

Minimum budget: 5 USDC per channel.

Payment · USDC on Arc or Base. Gas is additional.

After launch

1
Open your campaign
Follow the link your agent returns. Sign in with the wallet that created the campaign.
2
Check results
View channel results, budget and spend. Or ask your agent: “How is my campaign performing?”
3
Manage your ads
Pause, resume or end your campaign in My Campaigns.

Developer reference

Production API available · Wallet setup required

Execution guide

Back to reference ↑

Relative file paths in this document resolve within /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.

API reference

Back to reference ↑

Advertiser API for campaign preparation, approved funding and result queries. prepare_campaign, launch_campaign and get_campaign are local client functions, not HTTP routes. Read instructions.txt and integration.txt for approval, payment and retry rules.

API origin · https://api.openads.world

Select an endpoint for its parameters, request body and responses. Schema references resolve in Shared definitions below.

GET/api/v2/auth/challenge

{
  "operationId": "createAuthChallenge",
  "tags": [
    "Auth"
  ],
  "security": [],
  "x-openads-feature-gates": [
    "V2_API_ENABLED"
  ],
  "parameters": [
    {
      "$ref": "#/components/parameters/WalletQuery"
    }
  ],
  "responses": {
    "200": {
      "description": "Five-minute wallet login challenge",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AuthChallenge"
          }
        }
      }
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  }
}

POST/api/v2/auth/session

{
  "operationId": "createAuthSession",
  "tags": [
    "Auth"
  ],
  "security": [],
  "x-openads-feature-gates": [
    "V2_API_ENABLED"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LoginRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "24-hour HTTP-only session",
      "headers": {
        "Set-Cookie": {
          "schema": {
            "type": "string"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Session"
          }
        }
      }
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  }
}

DELETE/api/v2/auth/session

{
  "operationId": "deleteAuthSession",
  "tags": [
    "Auth"
  ],
  "x-openads-feature-gates": [
    "V2_API_ENABLED"
  ],
  "responses": {
    "204": {
      "description": "Session revoked"
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  }
}

GET/api/v2/campaigns/policy

Small account-specific policy query only: pricing, selectable channels and active payment chains. No campaigns, ledger aggregation, chain RPC or funding recovery. Private/no-store; account 120/min and network 300/min.

{
  "operationId": "getCampaignPolicy",
  "tags": [
    "Advertise"
  ],
  "description": "Small account-specific policy query only: pricing, selectable channels and active payment chains. No campaigns, ledger aggregation, chain RPC or funding recovery. Private/no-store; account 120/min and network 300/min.",
  "x-openads-feature-gates": [
    "V2_API_ENABLED"
  ],
  "responses": {
    "200": {
      "description": "Current campaign preparation policy",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CampaignPolicy"
          }
        }
      }
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  }
}

POST/api/v2/campaigns

Campaign metadata body is limited to 32 KiB (images use the assets route). Network preparation limit 120/min, account preparation limit 60/min, draft creation limit 30/hour. Same idempotency key must be used on retries.

{
  "operationId": "createCampaignDraft",
  "tags": [
    "Advertise"
  ],
  "x-openads-feature-gates": [
    "V2_API_ENABLED",
    "V2_COMMANDS_ENABLED"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateCampaignRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Campaign draft",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CampaignView"
          }
        }
      }
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  },
  "description": "Campaign metadata body is limited to 32 KiB (images use the assets route). Network preparation limit 120/min, account preparation limit 60/min, draft creation limit 30/hour. Same idempotency key must be used on retries."
}

GET/api/v2/campaigns/{id}

{
  "operationId": "getCampaign",
  "tags": [
    "Advertise"
  ],
  "x-openads-feature-gates": [
    "V2_API_ENABLED"
  ],
  "parameters": [
    {
      "$ref": "#/components/parameters/ResourceId"
    }
  ],
  "responses": {
    "200": {
      "description": "Canonical Campaign view",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CampaignView"
          }
        }
      }
    },
    "404": {
      "$ref": "#/components/responses/Error"
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  }
}

POST/api/v2/campaigns/{id}/commands/{command}

Metadata body is limited to 32 KiB. save-draft and submit-review share preparation limits: network 120/min and account 60/min. Lifecycle commands keep their existing protections. Expired managed images prevent launch before funding.

{
  "operationId": "commandCampaign",
  "tags": [
    "Advertise"
  ],
  "x-openads-feature-gates": [
    "V2_API_ENABLED",
    "V2_COMMANDS_ENABLED"
  ],
  "parameters": [
    {
      "$ref": "#/components/parameters/ResourceId"
    },
    {
      "name": "command",
      "in": "path",
      "required": true,
      "schema": {
        "$ref": "#/components/schemas/CampaignCommand"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CampaignCommandRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated Campaign view or Review & Launch result",
      "content": {
        "application/json": {
          "schema": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CampaignView"
              },
              {
                "$ref": "#/components/schemas/ReviewLaunchResponse"
              }
            ]
          }
        }
      }
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  },
  "description": "Metadata body is limited to 32 KiB. save-draft and submit-review share preparation limits: network 120/min and account 60/min. Lifecycle commands keep their existing protections. Expired managed images prevent launch before funding."
}

POST/api/v2/assets

{
  "operationId": "uploadCampaignAsset",
  "tags": [
    "Advertise"
  ],
  "x-openads-feature-gates": [
    "V2_API_ENABLED",
    "V2_COMMANDS_ENABLED"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CampaignAssetUploadRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Content-addressed Campaign image",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CampaignAsset"
          }
        }
      }
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  }
}

POST/api/v2/funding/submissions

{
  "operationId": "recordFundingSubmission",
  "tags": [
    "Settlement"
  ],
  "x-openads-feature-gates": [
    "V2_API_ENABLED",
    "V2_FUNDING_SYNC_ENABLED"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FundingReceiptRequest"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Broadcast recorded; observation and final accounting continue automatically",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/FundingSubmissionResponse"
          }
        }
      }
    },
    "default": {
      "$ref": "#/components/responses/Error"
    }
  }
}

Shared definitions · schemas & authentication

{
  "security": [
    {
      "V2SessionCookie": []
    },
    {
      "V2SessionHeader": []
    }
  ],
  "components": {
    "securitySchemes": {
      "V2SessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "openads_v2_session"
      },
      "V2SessionHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-openads-v2-session",
        "description": "Use the raw openads_v2_session cookie value from Set-Cookie, not the JSON access_token."
      }
    },
    "parameters": {
      "WalletQuery": {
        "name": "wallet",
        "in": "query",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Wallet"
        }
      },
      "ResourceId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Uuid"
        }
      }
    },
    "schemas": {
      "Wallet": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{40}$"
      },
      "AuthChallenge": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "challenge",
          "message",
          "expires_at"
        ],
        "properties": {
          "schema": {
            "const": "openads.auth-challenge/2.0"
          },
          "challenge": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "expires_at": {
            "$ref": "#/components/schemas/DateTime"
          }
        }
      },
      "DateTime": {
        "type": "string",
        "format": "date-time"
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "error",
          "message"
        ],
        "properties": {
          "schema": {
            "const": "openads.error/2.0"
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "next_action": {
            "type": "string",
            "description": "Shared website/SDK recovery instruction. Never start a second payment to recover an existing transaction."
          },
          "retryable": {
            "type": "boolean",
            "description": "True only for a bounded retry of the same operation. False requires user/operator action or current-state review."
          },
          "retry_after": {
            "type": [
              "string",
              "null"
            ],
            "description": "Minimum delay in seconds when provided; HTTP Retry-After takes precedence. Unknown wait durations remain null."
          }
        }
      },
      "LoginRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "challenge",
          "signature"
        ],
        "properties": {
          "challenge": {
            "type": "string"
          },
          "signature": {
            "type": "string"
          }
        }
      },
      "Session": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "account_id",
          "actor_wallet",
          "expires_at"
        ],
        "properties": {
          "schema": {
            "const": "openads.session/2.0"
          },
          "account_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "actor_wallet": {
            "$ref": "#/components/schemas/Wallet"
          },
          "expires_at": {
            "$ref": "#/components/schemas/DateTime"
          },
          "access_token": {
            "type": "string",
            "description": "Separate site-access token, NOT a V2 API session token. Keep private. For API authentication preserve the openads_v2_session cookie from Set-Cookie."
          }
        }
      },
      "Uuid": {
        "type": "string",
        "format": "uuid"
      },
      "CampaignPolicy": {
        "type": "object",
        "required": [
          "schema",
          "capabilities",
          "available_chain_ids"
        ],
        "properties": {
          "schema": {
            "const": "openads.campaign-policy/1.0"
          },
          "available_chain_ids": {
            "type": "array",
            "uniqueItems": true,
            "maxItems": 2,
            "items": {
              "enum": [
                5042,
                8453
              ]
            }
          },
          "capabilities": {
            "type": "object",
            "required": [
              "web",
              "shares",
              "reward"
            ],
            "properties": {
              "web": {
                "type": "object",
                "required": [
                  "minimum_cpm",
                  "minimum_cpm_default"
                ],
                "properties": {
                  "minimum_cpm": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "number",
                      "exclusiveMinimum": 0
                    }
                  },
                  "minimum_cpm_default": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  }
                },
                "additionalProperties": false
              },
              "shares": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ShareAdvertiserCapability"
                  },
                  {
                    "type": "object",
                    "required": [
                      "runtime_state",
                      "selectable"
                    ],
                    "properties": {
                      "runtime_state": {
                        "const": "DISABLED"
                      },
                      "selectable": {
                        "const": false
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "reward": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/RewardAdvertiserCapability"
                  },
                  {
                    "type": "object",
                    "required": [
                      "runtime_state",
                      "selectable"
                    ],
                    "properties": {
                      "runtime_state": {
                        "const": "DISABLED"
                      },
                      "selectable": {
                        "const": false
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ShareAdvertiserCapability": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "runtime_state",
          "selectable",
          "recommended_cpc_micro",
          "recommended_budget_bps"
        ],
        "properties": {
          "runtime_state": {
            "enum": [
              "OFF",
              "SHADOW",
              "PILOT",
              "LIVE",
              "HOLD"
            ]
          },
          "selectable": {
            "type": "boolean"
          },
          "recommended_cpc_micro": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PositiveMicroUsdc"
              },
              {
                "type": "null"
              }
            ]
          },
          "recommended_budget_bps": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "pricing_policy_version": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          }
        }
      },
      "PositiveMicroUsdc": {
        "type": "string",
        "pattern": "^[1-9][0-9]{0,18}$"
      },
      "RewardAdvertiserCapability": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "runtime_state",
          "selectable",
          "recommended_base_reward_micro",
          "recommended_budget_bps",
          "telegram_bonus_bps",
          "platform_bps",
          "challenge_ttl_seconds",
          "same_campaign_cooldown_seconds",
          "maximum_campaign_allocation_micro"
        ],
        "properties": {
          "runtime_state": {
            "enum": [
              "OFF",
              "SHADOW",
              "PILOT",
              "LIVE",
              "HOLD"
            ]
          },
          "selectable": {
            "type": "boolean"
          },
          "recommended_base_reward_micro": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PositiveMicroUsdc"
              },
              {
                "type": "null"
              }
            ]
          },
          "recommended_budget_bps": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "telegram_bonus_bps": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "platform_bps": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "challenge_ttl_seconds": {
            "type": "integer",
            "minimum": 5
          },
          "same_campaign_cooldown_seconds": {
            "type": "integer",
            "minimum": 3600,
            "maximum": 3600
          },
          "maximum_campaign_allocation_micro": {
            "$ref": "#/components/schemas/PositiveMicroUsdc"
          },
          "pricing_policy_version": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "fixed_platform_fee_micro": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/MicroUsdc"
              },
              {
                "type": "null"
              }
            ]
          },
          "recommended_cost_per_completion_micro": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PositiveMicroUsdc"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "CreateCampaignRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "draft_plan",
          "idempotency_key"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "draft_plan": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "idempotency_key": {
            "$ref": "#/components/schemas/IdempotencyKey"
          }
        }
      },
      "JsonObject": {
        "type": "object",
        "additionalProperties": true
      },
      "IdempotencyKey": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128
      },
      "CampaignView": {
        "allOf": [
          {
            "$ref": "#/components/schemas/VersionedView"
          },
          {
            "type": "object",
            "required": [
              "name",
              "status",
              "effective_status",
              "active_surfaces",
              "total_surfaces",
              "draft_plan",
              "draft_plan_version",
              "surfaces",
              "settlement"
            ],
            "properties": {
              "schema": {
                "const": "openads.campaign/2.0"
              },
              "name": {
                "type": "string"
              },
              "status": {
                "$ref": "#/components/schemas/CampaignLifecycle"
              },
              "effective_status": {
                "type": "string"
              },
              "active_surfaces": {
                "type": "integer",
                "minimum": 0
              },
              "total_surfaces": {
                "type": "integer",
                "minimum": 0
              },
              "draft_plan": {
                "$ref": "#/components/schemas/JsonObject"
              },
              "draft_plan_version": {
                "type": "integer",
                "minimum": 1
              },
              "surfaces": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/JsonObject"
                }
              },
              "funding": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/FundingIntentView"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "settlement": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/CampaignSettlement"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "assets_expired": {
                "type": "boolean",
                "description": "Known temporary images have expired; reprepare before payment."
              }
            }
          }
        ]
      },
      "VersionedView": {
        "type": "object",
        "required": [
          "schema",
          "id",
          "version",
          "as_of",
          "updated_at"
        ],
        "properties": {
          "schema": {
            "type": "string"
          },
          "id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "as_of": {
            "$ref": "#/components/schemas/DateTime"
          },
          "updated_at": {
            "$ref": "#/components/schemas/DateTime"
          }
        }
      },
      "CampaignLifecycle": {
        "enum": [
          "DRAFT",
          "ACTIVE",
          "PAUSED",
          "CLOSING",
          "SETTLED",
          "ARCHIVED",
          "REVOKED"
        ]
      },
      "FundingIntentView": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "enum": [
              "NONE",
              "READY_FROM_AVAILABLE",
              "WAITING_FOR_DEPOSIT"
            ]
          },
          "intent_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "campaign_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "status": {
            "enum": [
              "PENDING",
              "COMPLETED",
              "CANCELLED",
              "EXPIRED"
            ]
          },
          "chain_id": {
            "type": "integer",
            "minimum": 1
          },
          "vault_version": {
            "type": "integer",
            "minimum": 1
          },
          "vault_address": {
            "$ref": "#/components/schemas/Wallet"
          },
          "token_address": {
            "$ref": "#/components/schemas/Wallet"
          },
          "required_total_micro": {
            "$ref": "#/components/schemas/PositiveMicroUsdc"
          },
          "reserved_micro": {
            "$ref": "#/components/schemas/MicroUsdc"
          },
          "confirmed_received_micro": {
            "$ref": "#/components/schemas/MicroUsdc"
          },
          "remaining_shortfall_micro": {
            "$ref": "#/components/schemas/MicroUsdc"
          },
          "funding_ref": {
            "$ref": "#/components/schemas/Bytes32"
          },
          "launch_plan_hash": {
            "$ref": "#/components/schemas/Bytes32"
          },
          "created_block": {
            "type": "integer",
            "minimum": 0
          },
          "last_checked_block": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "expires_at": {
            "$ref": "#/components/schemas/DateTime"
          },
          "recovery_until": {
            "$ref": "#/components/schemas/DateTime"
          },
          "replay": {
            "type": "boolean"
          }
        }
      },
      "MicroUsdc": {
        "type": "string",
        "pattern": "^[0-9]+$",
        "description": "Integer micro-USDC. Never a JSON number."
      },
      "Bytes32": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{64}$"
      },
      "CampaignSettlement": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "vault_version",
          "chain_id",
          "vault_address",
          "token_address"
        ],
        "properties": {
          "vault_version": {
            "type": "integer",
            "minimum": 1
          },
          "chain_id": {
            "enum": [
              8453,
              5042
            ]
          },
          "vault_address": {
            "$ref": "#/components/schemas/Wallet"
          },
          "token_address": {
            "$ref": "#/components/schemas/Wallet"
          }
        }
      },
      "CampaignCommand": {
        "enum": [
          "save-draft",
          "submit-review",
          "review-launch"
        ]
      },
      "CampaignCommandRequest": {
        "type": "object",
        "required": [
          "target_version",
          "idempotency_key"
        ],
        "properties": {
          "target_version": {
            "type": "integer",
            "minimum": 1
          },
          "idempotency_key": {
            "$ref": "#/components/schemas/IdempotencyKey"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "draft_plan": {
            "$ref": "#/components/schemas/JsonObject"
          },
          "funding_ref": {
            "$ref": "#/components/schemas/Bytes32"
          },
          "chain_id": {
            "enum": [
              8453,
              5042
            ]
          },
          "allocations": {
            "type": "array",
            "minItems": 1,
            "maxItems": 7,
            "items": {
              "$ref": "#/components/schemas/ReviewLaunchAllocation"
            }
          },
          "signature": {
            "$ref": "#/components/schemas/CommandSignature"
          }
        }
      },
      "ReviewLaunchAllocation": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "surface",
              "format",
              "amount_micro"
            ],
            "properties": {
              "surface": {
                "const": "WEB"
              },
              "format": {
                "$ref": "#/components/schemas/WebFormat"
              },
              "amount_micro": {
                "$ref": "#/components/schemas/PositiveMicroUsdc"
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "surface",
              "format",
              "amount_micro"
            ],
            "properties": {
              "surface": {
                "const": "SHARE"
              },
              "format": {
                "const": "SHARE_CARD"
              },
              "amount_micro": {
                "$ref": "#/components/schemas/PositiveMicroUsdc"
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "surface",
              "format",
              "amount_micro"
            ],
            "properties": {
              "surface": {
                "const": "REWARD"
              },
              "format": {
                "const": "REWARDED_VISIT"
              },
              "amount_micro": {
                "$ref": "#/components/schemas/PositiveMicroUsdc"
              }
            }
          }
        ]
      },
      "WebFormat": {
        "enum": [
          "320X50_TOP",
          "320X50",
          "300X250",
          "64X64"
        ]
      },
      "CommandSignature": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "signature",
          "issued_at",
          "expires_at"
        ],
        "properties": {
          "signature": {
            "type": "string"
          },
          "issued_at": {
            "$ref": "#/components/schemas/DateTime"
          },
          "expires_at": {
            "$ref": "#/components/schemas/DateTime"
          }
        }
      },
      "ReviewLaunchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "outcome",
          "campaign",
          "approved_launch_plan",
          "funding",
          "replay"
        ],
        "properties": {
          "schema": {
            "const": "openads.review-launch/2.0"
          },
          "outcome": {
            "enum": [
              "ALL_READY",
              "PARTIAL_READY",
              "WAITING_FOR_REVIEW",
              "NEEDS_CHANGES"
            ]
          },
          "campaign": {
            "$ref": "#/components/schemas/CampaignView"
          },
          "approved_launch_plan": {
            "type": "object",
            "required": [
              "allocations"
            ],
            "properties": {
              "launch_plan_hash": {
                "$ref": "#/components/schemas/Bytes32"
              },
              "allocations": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ApprovedLaunchAllocation"
                }
              }
            }
          },
          "funding": {
            "$ref": "#/components/schemas/FundingIntentView"
          },
          "replay": {
            "type": "boolean"
          }
        }
      },
      "ApprovedLaunchAllocation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "surface_term_id",
          "delivery_term_version_id",
          "creative_variant_id",
          "amount_micro"
        ],
        "properties": {
          "surface_term_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "delivery_term_version_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "creative_variant_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "amount_micro": {
            "$ref": "#/components/schemas/PositiveMicroUsdc"
          }
        }
      },
      "CampaignAssetUploadRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campaign_id",
          "format",
          "data_url"
        ],
        "properties": {
          "campaign_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "format": {
            "$ref": "#/components/schemas/CampaignAssetFormat"
          },
          "data_url": {
            "type": "string",
            "pattern": "^data:image/(?:png|jpeg|webp|gif);base64,[A-Za-z0-9+/]+={0,2}$",
            "description": "Complete image data URL. PNG/JPEG/WebP <=3 MiB; GIF <=1 MiB. Server also validates image content, dimensions and animation limits."
          }
        }
      },
      "CampaignAssetFormat": {
        "enum": [
          "320X50_TOP",
          "320X50",
          "300X250",
          "64X64",
          "SHARE_CARD",
          "REWARDED_VISIT"
        ]
      },
      "CampaignAsset": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "campaign_id",
          "format",
          "asset_url",
          "sha256"
        ],
        "properties": {
          "schema": {
            "const": "openads.campaign-asset/2.0"
          },
          "campaign_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "format": {
            "$ref": "#/components/schemas/CampaignAssetFormat"
          },
          "asset_url": {
            "type": "string",
            "format": "uri"
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          }
        }
      },
      "FundingReceiptRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "intent_id",
          "tx_hash"
        ],
        "properties": {
          "intent_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "tx_hash": {
            "$ref": "#/components/schemas/TxHash"
          }
        }
      },
      "TxHash": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{64}$"
      },
      "FundingSubmissionResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "schema",
          "submission_id",
          "intent_id",
          "tx_hash",
          "status"
        ],
        "properties": {
          "schema": {
            "const": "openads.funding-submission/2.0"
          },
          "submission_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "intent_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "tx_hash": {
            "$ref": "#/components/schemas/TxHash"
          },
          "status": {
            "enum": [
              "SUBMITTED",
              "OBSERVED",
              "FINALIZED",
              "REORGED",
              "FAILED"
            ]
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Versioned fail-closed error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}

Integration notes

Back to reference ↑

Relative file paths in this document resolve within /agents/.

Read ./instructions.txt for the execution and approval flow. Resolve all paths relative to this document. HTTP schemas: ./openapi.json. This page does not connect a wallet or create an agent session. Localhost/file links work only on the same computer. If unreachable, obtain the documents or a reachable URL before continuing.

Primary agent setup Use the transaction-signing path below for payment inside the agent. A host must supply its connected wallet tool; the SDK does not install or create one. Production agent real-payment verification covers Arc Website Ads and Base Website Ads Center Popup (300X250). Base funding, campaign/channel ACTIVE, owner dashboard/performance reads and retry without another payment were verified on 2026-10-09. Other Base formats and Share/Earn agent paid activation are outside these checks. Confirm current policy and the user's selected scope.

Optional Node SDK

Requires Node.js 20+, ethers 6 and the same EOA wallet. Direct HTTP does not need the SDK. EIP-1271 smart wallets and x402 are not included. Read ./sdk/example.mjs for the factory and ./sdk/openads-agent.mjs for the client. The sample helper's creative/URL/budget are examples, not advertiser input. Reviewed Arc/Base advertising deposit addresses: ./sdk/production-networks.mjs. They are factory defaults, not copied from an API response. The host supplies the actual wallet signing tool; reading this guide does not create one.

Transaction-signing path (primary): Host integration supplies campaignAgent({getSigner, journalPath, reviewedNetworks?}): getSigner(chainId): advertiser-owned ethers signer with a provider. signTransaction must sign without broadcasting; the SDK journals then sends. reviewedNetworks: optional explicit override reviewed by the operator. journalPath: one private journal shared by processes using that same wallet. USDC must be the official six-decimal token; Vault means the advertising deposit contract, not a Buyback contract. Do not derive trusted addresses from API output, token symbols or screenshots. Missing configuration requires operator setup; do not ask the advertiser to invent addresses or paste signing keys. The journal contains session and signed-transaction recovery data. Keep it out of Git, private, and intact while payment is pending. Do not concurrently send unrelated transactions from this wallet. After a crash, confirm the holder process is stopped before removing a stale .lock file; keep the journal itself.

Browser wallet path (optional handoff): browserCampaignAgent({getAddress, signMessage, journalPath}). getAddress and signMessage call the host's actual advertiser-owned EOA tool. The agent prepares/reviews the ad, obtains approval, then requests a signed launch message. If more USDC is needed, launch_campaign returns COMPLETE_PAYMENT_IN_BROWSER, payment and launch_url for the SAME campaign. Show payment.chain_id, budget_micro, balance_applied_micro, additional_usdc_micro and reviewed Vault/token. Open launch_url, sign in with the same wallet and have the user press Continue and confirm the wallet transactions. Check actual gas in the wallet: the SDK execution cap does not apply to browser transactions. SDK payment signing/broadcasting is disabled here. Retry the same operation for a lost response; it returns the same intent. Recover a browser deposit in the existing browser flow, not by sending a second SDK deposit. Read the campaign after payment to confirm ACTIVE. If existing advertising credit covers the budget, no deposit is needed.

Inputs

Exact SDK input, plan and command-message rules: ./sdk/plan.mjs. - operation_id: 8-100 letters, numbers, hyphens or underscores. Reuse on retries; changed input requires a new operation, after resolving any pending payment. - HTTPS destination, no credentials, <=2048 characters. - Campaign name/title: 1-100 characters. Message defaults to title; supplied message: 1-280. Sponsor <=100; CTA <=40. - 1-6 distinct combinations: Website Ads: WEB / 320X50_TOP, 320X50, 300X250, 64X64. Share Ads: SHARE / SHARE_CARD. Earn Ads: REWARD / REWARDED_VISIT. - SDK budgets/CPM: decimal strings, <=6 decimals. Share/Earn each >=5 USDC; Website budget >=selected CPM. Current policy supplies prices/availability. Earn's maximum allocation also comes from policy. Do not split budgets silently. - API plan amounts: integer micro-USDC strings (5 USDC = "5000000"). - Arc: chain_id 5042; Base: 8453. Require availability in current policy. - Actual PNG/JPEG/WebP <=3 MiB; GIF <=1 MiB. Upload complete data URLs. Static images: single frame, <=4096 pixels/side and <=4 million pixels. GIF: <=1280 pixels/side, <=1 million pixels/frame, <=120 frames and <=48 million total frame pixels. Server content checks and normalization must also succeed.

Direct HTTP preparation (in order)

GET /api/v2/auth/challenge?wallet=<wallet>. Check openads.world audience, wallet and expiry, then request signing of that exact message.
POST /api/v2/auth/session {challenge, signature}. Preserve Set-Cookie's openads_v2_session. x-openads-v2-session accepts the SAME raw cookie value; JSON access_token is a separate site-access token, not V2 API authentication.
GET /api/v2/campaigns/policy. Use current capabilities/available_chain_ids.
POST /api/v2/campaigns {name, draft_plan, idempotency_key}. Use openads.campaign-draft/2.1 from plan.mjs; persist returned ID/version.
POST /api/v2/assets {campaign_id, format, data_url}; retain validated asset_url.
POST /api/v2/campaigns/{id}/commands/save-draft with current target_version, stable idempotency_key, name and finalized draft_plan containing the assets.
POST /api/v2/campaigns/{id}/commands/submit-review with the latest version and stable idempotency_key; GET the campaign to check all selected surfaces: status/effective_status READY, creative_review APPROVED, no expired assets. Preserve each returned version. Unknown responses require replay/recovery with the same identifiers before creating another draft, upload or command.

Direct HTTP launch/payment (only after approval)

Recheck campaign/creative/version and current policy before initial review-launch. POST /api/v2/campaigns/{id}/commands/review-launch with target_version, idempotency_key, chain_id, allocations, persisted random bytes32 funding_ref and signature. Build the EXACT message with buildCommandMessage in plan.mjs: stable sorted-key JSON SHA256 binds payload, wallet, campaign, version, times and idempotency nonce. Sign only the current approved payload. Require ALL_READY and valid funding before additional payment; mode NONE means no deposit. Match campaign, chain, pinned USDC/Vault, intent_id, funding_ref, required total, remaining_shortfall_micro, status and expiry to the operation. Use existing funds first; remaining_shortfall_micro is the additional deposit. Use this selected-chain funding response for the payment breakdown. The account dashboard's aggregate available balance can include other networks; do not subtract it from a single-chain campaign budget to calculate a deposit. If zero, do not deposit. For nonzero shortfall: Estimate gas and enforce approved costs. If allowance is insufficient, approve ONLY the shortfall to the pinned Vault and wait for its successful receipt. Call Vault.deposit(funding_ref, shortfall). Persist signed bytes/hash/nonce BEFORE broadcast; retries use these exact bytes. No unrelated transfer or infinite approval. See ./sdk/ethers-wallet.mjs and ./sdk/file-state.mjs. POST /api/v2/funding/submissions {intent_id, tx_hash} to register that deposit. A 202 submission response records the transaction; server verification and activation may still be pending. Follow next_action and read the same campaign. The existing bounded funding reconciliation also runs after an account read and in the scheduled recovery job. Never deposit again because activation is pending. SDK max_transaction_gas_wei caps gasLimit x fee per transaction, not combined transactions or Base L1 data fees. Approval and deposit may be two transactions. Gas amounts use 18-decimal native units on both chains, unlike six-decimal USDC payment amounts. For example, a 0.01 native-token execution-gas cap is "10000000000000000" wei: 0.01 USDC on Arc, or 0.01 ETH on Base. Activation checks and recovery rules are in instructions.txt.

Shared website, API and SDK error handling Complete guide: ./errors.txt. The same website error-ux.js policy is bundled as ./sdk/error-ux.cjs and used by the API's existing error envelope. Direct HTTP callers receive next_action, retryable and retry_after in openads.error/2.0. HTTP Retry-After takes precedence. Respect denials; never bypass safety blocks. Catch SDK exceptions and report error.toJSON(): error, message, next_action, retryable, plus operation_id/campaign_id/stage/tx_hash when known. Balance errors include exact required, available and shortfall amounts in details. _micro uses six-decimal USDC; _native_wei uses 18-decimal native units. Do not expose the private journal, signed transaction bytes or raw provider error objects. The ethers adapter checks USDC before signing an approval and again before deposit. It checks native funds against execution fees, the current Base L1 fee estimate and, on Arc deposit, the native USDC being deposited. - INSUFFICIENT_USDC_BALANCE: show the selected chain and exact shortfall. Ask for funds, then resume the same operation; no transaction was signed for the failed step. Do not create another campaign or funding intent. - INSUFFICIENT_GAS_BALANCE: request native gas funds on the selected chain. - WALLET_SIGNATURE_REJECTED: obtain consent before requesting another signature. - PAYMENT_SIMULATION_FAILED / PAYMENT_NONCE_CONFLICT / PAYMENT_FAILED: review the saved operation and transaction; do not automatically replace/pay. - TRANSACTION_SUBMISSION_UNKNOWN: inspect the saved hash. Only its exact saved bytes may be rebroadcast. A pending result includes this as payment_error. - HTTP 429/temporary 5xx: respect retry_after and resume the same operation with bounded retries. Disabled/configuration errors can be 503 and require operator setup instead. Definitive API rejections preserve any existing payment. - Unexpected local/wallet errors stop with a safe error; inspect setup and saved records before continuing. Do not assume every failure is retryable. retryable is false for missing funds and rejected signatures: action is needed first. This does not prevent resuming the same operation after that action. These checks belong to the transaction-signing adapter; direct HTTP or custom wallet adapters must enforce the same checks. They do not guarantee unchanged balances or fees between checking and broadcasting.

After launch: one authenticated read

SDK: get_campaign_performance({campaign_id}). Direct HTTP: GET /api/v2/campaigns/{id} using the existing owner's session. SDK performance fields: budget_micro, spent_micro, remaining_budget_micro, as_of, chain_id and channels[]. Each channel includes surface, format, status, budget_micro, spent_micro, remaining_budget_micro and the applicable result: web_ad_views / website_clicks / qualified_share_clicks / completed_earn_visits. Unknown facts remain null. Monetary fields are integer micro-USDC strings; convert with exact decimal arithmetic. No chain call or payment is needed. Use all_selected_surfaces_active along with status ACTIVE to confirm full launch. This read does not invoke funding recovery; get_campaign still recovers a saved deposit registration when needed. Query on request, not in a background loop. My Campaigns selects the campaign from ?campaign=<id> after owner login, with manual Refresh results, channel tabs and the existing management controls. Unused funds remain advertising credit after settlement; deposits are non-refundable.

Preparation resource limits

Advertiser requests also share a lightweight burst guard: 300 requests/IP per 60 seconds within one warm server instance, before authentication/DB work. This is best-effort protection, not a global quota; existing account/network limits still apply. On 429, wait for Retry-After and resume the same operation.
Metadata: 32 KiB. Shared preparation limits: account 60/min, network 120/min; draft creation additionally account 30/hour. Retries consume these limits too.
Policy reads: account 120/min, network 300/min; private/no-store.
Managed images in unfunded DRAFTs with no funding-intent history become eligible for cleanup after seven idle days by default. Last upload and campaign update must both be old; cleanup runs in the existing bounded job, not exactly at the seven-day mark. Any funding-intent history protects these images, including expired intents, because a signed payment may arrive late.
Follow expiry/recovery errors; never delete financial history or auto-repay.

Errors & recovery

Back to reference ↑

Relative file paths in this document resolve within /agents/.

Scope This guide covers campaign preparation, approved funding, activation and performance reads on Arc (5042) and Base (8453), through SDK or direct HTTP. The website's error-ux.js is the shared recovery policy. The SDK bundles the same file as sdk/error-ux.cjs; the API uses it in its existing error handler. The API's existing authentication, validation, review and financial controls remain authoritative. The SDK is not a replacement for server protection.

1. Read the result

HTTP failure: preserve status and the openads.error/2.0 body. SDK failure: catch the exception and use error.toJSON(). Both provide error, message, next_action and retryable. HTTP also provides retry_after; SDK errors include status, retry_after, operation_id, campaign_id, stage and tx_hash when known. Balance details include required/available/shortfall amounts. _micro fields are integer six-decimal USDC; _native_wei fields are 18-decimal native units. Never treat an absent amount as zero or expose a raw provider exception. An unknown error means STOP_AND_REVIEW_ERROR, not permission to pay again.

2. Check whether any transaction already exists

Before acting on any error, inspect the same operation's journal and saved approval/deposit hashes. Preserve campaign ID, funding intent/ref, command idempotency keys and signed transaction records. If payment might have been sent, check the existing hash and campaign first. An error after deposit is not proof of nonpayment. An earlier USDC approval may already have cost gas. Never create a new deposit, operation or journal to fix an uncertain payment.

3. Follow the recovery instruction

ADD_USDC_AND_RETRY_SAME_OPERATION: INSUFFICIENT_USDC_BALANCE. Show chain, required amount, current USDC and exact shortfall. Request funds on that chain, then continue the same operation and valid approval. The failed signing step produced no new transaction; earlier steps may have completed.
ADD_NATIVE_GAS_AND_RETRY_SAME_OPERATION: INSUFFICIENT_GAS_BALANCE or wallet INSUFFICIENT_FUNDS. Request native gas funds on the approved network.
REQUEST_WALLET_SIGNATURE: signing was cancelled (4001/ACTION_REJECTED or WALLET_SIGNATURE_REJECTED). Get consent before requesting another signature.
CONNECT_OWNER_WALLET / CONNECT_APPROVED_NETWORK: connect the campaign owner and approved chain. Do not change a funding intent's chain or wallet.
FINISH_EXISTING_OPERATION: STATE_BUSY/WALLET_BUSY or a wallet prompt is open. Complete that operation. After a crash, confirm the process stopped before removing only a stale .lock; never delete/reset the journal.
SIGN_IN_WITH_OWNER_WALLET: session missing/expired (401). Sign in as the owner and retry the same request once. The SDK performs this once for V2_SESSION_REQUIRED/EXPIRED. Do not retry other 401 errors as session expiry.
REVIEW_AND_SIGN_CURRENT_COMMAND: command signature required, expired or invalid. Read the current campaign/version and reviewed payload, get consent as needed and sign the correct command. Never replay a different payload under an existing idempotency key.
FIX_INPUT_AND_GET_APPROVAL: malformed JSON/input/URL/image/amount, missing assets, minimum/maximum budget or oversized body (400/413/422). Correct the identified input once; changed campaign/costs require approval. Use editable drafts where supported. Already-submitted drafts cannot simply be edited.
PREPARE_AND_GET_NEW_APPROVAL: campaign, version, pricing or approval changed. Resolve existing payments before preparing the new approved operation.
PREPARE_NEW_CAMPAIGN: CAMPAIGN_ASSET_EXPIRED. Reupload only if the draft is still editable; otherwise prepare a new campaign and obtain approval. Never repay a campaign with an unresolved payment.
SELECT_SUPPORTED_NETWORK_AND_GET_APPROVAL: unsupported/unavailable selected network. Read current policy, offer an enabled network and obtain approval. Do not silently switch Arc/Base or use credit from the wrong chain.
CHECK_RESOURCE_AND_OWNER: not found (404). Verify the ID and owner session. A resource not visible to this wallet must not be accessed via another ID.
REVIEW_EXISTING_OPERATION: changed input for the same operation ID or an IDEMPOTENCY_CONFLICT. Recover the original request; do not invent a new key to hide a mismatch or bypass a denied command.
READ_CURRENT_STATE_BEFORE_CONTINUING: state conflict/closed/ended/noneditable campaign or expired resource (409/410). Read once and explain the actual state. Do not assume that changing identifiers makes the command valid.
WAIT_FOR_SETTLEMENT: ended campaign activity is still settling. Keep the same campaign and launch operation; check later before further payment.
REVIEW_PAYMENT_BEFORE_RETRY: simulation failed. Check balances, allowance, approved network and payment data. No automatic replacement or repayment.
CHECK_EXISTING_TRANSACTION: uncertain send, nonce conflict or pending receipt/confirmations/finality. Check the saved hash on its original chain. A signing SDK may rebroadcast only the identical saved signed bytes. A direct HTTP/browser integration must use its existing payment recovery.
REVIEW_EXISTING_PAYMENT: reverted transaction, expired/closed/changed funding, reorg/finality conflict, or definitive 400/409/410/422 during funding registration. Show the saved hash and current state; ask for review. Do not automatically sign a replacement or create another deposit.
STOP_AND_REQUEST_REVIEW: forbidden access, blocked campaign, safety hold, self-dealing or other 403/423 rejection. Stop and explain the reason. Ask the operator to review a safety block; correct legitimate ownership through the normal login process. Do not rotate accounts/IPs or change IDs to bypass.
REQUEST_OPERATOR_SETUP: disabled feature, missing/invalid configuration, unavailable signing setup or reviewed payment adapter/configuration. Stop spending and request operator setup. HTTP 503 does not always mean retry.
STOP_AND_REVIEW_ERROR: payment destination/hash/evidence mismatch, excessive approved gas, wrong journal, corrupt/local state or an unrecognized failure. Preserve records and request review. Never trust provider prose suggesting another payment or serialize signed bytes, credentials or the private journal.
COMPLETE_REQUIRED_VERIFICATION: complete the verification requested by a 428 response through its supported flow. Do not forge/bypass verification.
WAIT_AND_RETRY_SAME_OPERATION / RETRY_SAME_OPERATION: temporary API/RPC outage, rate limit or lost response. Follow the bounded retry rules below.

4. Bound retries

retryable=true allows repeating the same request/operation, not spending again. Honor HTTP Retry-After first (seconds or HTTP date), then retry_after when provided. Never shorten that wait. Without a delay, use 10, 30, 60 seconds for at most three automatic retries, then show pending/error and await another user request. Do not reset the retry counter on each callback or nested step. For long Retry-After delays, show when the user can resume instead of keeping a process awake. No continuous polling, new background AI or parallel attempts. Read only the existing campaign or hash when confirmation is pending. retryable=false means user/operator action or review is required first. It does not prevent continuing the same operation after funds/consent are supplied. Do not retry a permanently denied command or unknown error automatically.

5. Handle non-error states too

prepare ready=false / WAIT_FOR_REVIEW_OR_FIX_CREATIVE: show review/change requirements. Do not launch or pay until every selected surface is approved. REVIEW_REQUIRED_NO_ADDITIONAL_PAYMENT: explain review outcome; no new deposit. COMPLETE_PAYMENT_IN_BROWSER: hand off the same campaign to the existing website. RETRY_SAME_LAUNCH_AFTER_APPROVAL_CONFIRMATION: check the existing approval. RETRY_SAME_LAUNCH_AFTER_DEPOSIT_CONFIRMATION: check the existing deposit. RETRY_SAME_LAUNCH_TO_REGISTER_EXISTING_TRANSACTION: register that same hash. RETRY_SAME_LAUNCH_WITH_APPROVAL: resume the same operation and saved approval. WAIT_FOR_ACTIVATION / GET_CAMPAIGN_LATER: payment/activation is pending. Read the same campaign later; do not fund again. Report payment_error when present. Only say live when campaign status is ACTIVE and every selected surface is active. Partial activation or unavailable performance is not full success. Return ID, actual state, existing hash and owner-login dashboard link. Performance reads do not pay. Unknown metrics stay null, not invented zeroes. Advertising deposits are non-refundable; settled unused funds are ad credit.

6. Arc and Base payment preflight

Both use pinned official six-decimal USDC and the reviewed advertising Vault. The standard wallet adapter checks USDC before approval and before deposit. Arc native gas is USDC; a deposit's native balance must cover transferred USDC plus gas. Base native gas is ETH; its check includes the current L1 fee estimate. The approved per-transaction execution cap excludes Base L1 fees. Approval and deposit are separate steps. If deposit is denied after approval, report both facts: approval may have succeeded, but no new deposit was signed by that step. Balances/fees may change after preflight. Keep subsequent receipt/error checks.

7. Direct HTTP without the campaign SDK

Use the same auth, draft, review, funding and campaign endpoints described in integration.txt. Read API error fields and use the recovery instructions above. The server validates inputs/access/review/financial records, but cannot inspect an external wallet's cancelled prompt or promise it has funds before signing. Your wallet integration must report those local failures too. You can reuse the bundled createEthersWallet adapter without the campaign client: verify pinned funding data, call preparePayment only after approval, durably save its signed packet before broadcast, then submit that exact hash. Preserve the same intent/ref and private journal. Alternatively use the existing website handoff. Never use a bare API 202 response or a chain receipt as proof that ads are ACTIVE.

Verification scope Arc/Base denial, insufficient funds, signing, recovery, request limits and direct HTTP error envelopes are checked with isolated tests. Production Arc Website Ads and Base Website Ads Center Popup (300X250) paid activation and performance have been verified separately. Base verification also covers exact-shortfall funding, campaign/channel ACTIVE, owner dashboard reads and retry without another signature or broadcast. Base actual balance-shortage handling was checked separately without signing or sending. Other Base formats and Share/Earn agent paid activation are not proven by these checks.