# Agent workflow

From wallet sign-in to a paid invoice, the full path for an automated agent.

Source: https://docs.invoise.me/agents/integration/

This is the setup path for an agent with a [wallet session](https://docs.invoise.me/agents/sign-in/). If you already have a shop ID and API key, go straight to step 4.

All JSON writes below need `Content-Type: application/json`, your session bearer token and a saved `Idempotency-Key` unique to the action.

## 1. Select a merchant

Read `GET /api/v1/me`. If `user.onboarding_required` is true, ask your human for their email address first, then complete setup:

```http
POST /api/v1/onboarding
Content-Type: application/json

{"name":"My merchant","email":"owner@example.com"}
```

An account that signed in only with a wallet must send `email`; without it the answer is `400 email_required`. A malformed address returns `invalid_email`, a disposable one `disposable_email`, and an email that already belongs to another account `identity_already_linked`. The email becomes a sign-in method of this same account. Invoise sends the person a notice: they open the dashboard, sign in with that email using a one-time code and land in the account you created.

This returns `{"completed":true}`, not the merchant ID. Next call `GET /api/v1/merchants` and save the intended merchant's `id`.

A returning account can belong to several merchants. Choose explicitly; do not silently use the first entry. Do not use `POST /merchants` for onboarding — it returns `forbidden`.

## 2. Create a shop

```http
POST /api/v1/merchants/{merchant_id}/shops
Content-Type: application/json

{
  "name": "Agent payments",
  "sandbox": true,
  "recipient": "<your-payout-address>"
}
```

Save the returned `id` as `shop_id`. Start in sandbox for a test; create a separate live shop with `sandbox: false` afterwards.

The optional EVM `delegate` is a settlement wallet that you control. Set it only if you need one. Never use an exchange deposit address for that role.

You can change the recipient and the delegate later with `PATCH /api/v1/shops/{shop_id}`. Invoices and addresses already created keep the ones they were created with.

A live shop can instead pay into the account's [Invoise wallet](https://docs.invoise.me/payments/wallet/): send `"payout_target":"wallet"` without `recipient`. Your human sets that wallet up in the dashboard; until then, creating an invoice returns `400 wallet_not_ready`. Solana and Tron need their own recipient; see [Solana and Tron](https://docs.invoise.me/payments/solana-and-tron/).

## 3. Issue a shop API key

Use your session to [create a key](https://docs.invoise.me/integration/api-keys/) with `read` and `write`. Save the returned `ivk_` token in your secret store, then use it for the following payment calls.

## 4. Create an invoice

1. Read `GET /api/v1/networks`. Use an enabled network and a ready token, with its actual address and decimals.
2. Save an idempotency key with the invoice in your system before sending the request.
3. Call `POST /api/v1/shops/{shop_id}/invoices`:

| Field | Value |
| --- | --- |
| `chain_id` | Selected network ID from the API; an integer. |
| `token` | Selected token address from the API. |
| `amount` | Invoice amount in the token’s smallest units; an integer string. |
| `external_id` | Optional reference to a record in your system. |

For a reusable top-up address, call `/deposits` without `amount`. To let the payer choose among several tokens or networks, send `assets` instead of `chain_id` and `token`; see [Deposits and invoices](https://docs.invoise.me/payments/deposits-and-invoices/#offer-several-tokens-or-networks).

After a timeout, retry the same request with the same key. `external_id` alone does not prevent duplicates.

## 5. Wait for the address, then for payment

Save `id` from the `202` response. Poll:

```bash
curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'
```

Wait for a non-empty `address`, then share `payment_url`. Keep polling this same endpoint for `status` and `received`. Receive change notifications through [webhooks](https://docs.invoise.me/integration/webhooks/).

Read [Invoice and deposit status](https://docs.invoise.me/payments/status/) before recording invoice payment: `funded`, `settled`, cancellation and reusable deposits have different meanings. Persist each business update once.

## Read documentation without a browser

Start at [llms.txt](https://docs.invoise.me/llms.txt) for the page index and [OpenAPI](https://docs.invoise.me/openapi.json) for structured contracts. [Reading tools](https://docs.invoise.me/agents/reading/) lists Markdown and full-text exports.