Agent workflow

This is the setup path for an agent with a wallet session. 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:

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

{"name":"My merchant","email":"[email protected]"}

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

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: 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.

3. Issue a shop API key

Use your session to create a key 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.

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:

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.

Read Invoice and deposit 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 for the page index and OpenAPI for structured contracts. Reading tools lists Markdown and full-text exports.