Agent integration starter

This page is the fastest path from “I have a Dino account” to “my integration can run a governed checkout and get a payment credential.” It pairs with the architecture guide Connecting AI Agents to Dino.

At the bottom of this page, the embedded Scalar reference matches api.dino.id — use it for organized tags, full request/response schemas, and optional try-it calls. You can jump there directly after reading the prerequisites and runnable examples below.

#Before you run anything

1. Fund your workspace wallet and complete any issuing / Stripe setup your team needs.
2. Create a Dino spending key (din_…) for the right agent budget — Agent Bank → API Keys or Cards → View policy → Keys. You only see the full secret once.
3. Never put that key in an LLM (prompts, skills, custom instructions, or chat logs). The model talks to your small server; your server adds Authorization: Bearer ….

#Pick a flow

For card checkout, authorization can return approved, declined, or needs_approval. If it needs approval, a human must act in the dashboard (or you consume webhooks) before you call issue-credential. Use Scalar’s Checkout operations for field-level detail.

#Runnable examples

These are the fastest ways to prove wiring end-to-end; Scalar below is the source of truth for every field.

#Option A — Copy-paste shell (three API calls)

From a trusted terminal (not inside a chat UI):

export DINO_SPEND_KEY='din_...'   # your real key
export DINO_API_BASE='https://api.dino.id'   # optional; default shown
bash scripts/agent-spend-checkout-example.sh

If you have the Dino monorepo, the script is at scripts/agent-spend-checkout-example.sh — copy it into your own repo if you only need the pattern. It uses curl and python3 only.

Adjust the JSON inside the script for real product_url, amounts, and buyer fields.

#Option B — Minimal Node “tool harness” (localhost)

Your agent (or MCP tool) should call your HTTP server; the server holds DINO_SPEND_KEY and calls Dino.

From the repo:

export DINO_SPEND_KEY='din_...'
node scripts/agent-spend-tool-harness-minimal.mjs

Then:

curl -sS -X POST http://127.0.0.1:3847/buy \
  -H 'Content-Type: application/json' \
  -d '{
    "product_url": "https://example.com/product",
    "expected_total_cents": 4599,
    "merchant_lock": "example.com"
  }'

The script is demo-grade: no TLS, no auth on /buy, fixed buyer stub — copy the pattern into your real service and add validation, authentication, and HTTPS.

In the Dino monorepo this lives at scripts/agent-spend-tool-harness-minimal.mjs.

#Option C — Raw curl (same three steps as the shell script)

Details and field lists: Purchase Intents API (checkout) and Agent Spend Quickstart (direct spend).

Always send Idempotency-Key on POST requests that create economic state, and reuse the same key when retrying the same logical operation.

#What to expose to the model (tool contract)

Keep the surface narrow, for example:

• buy_item(product_url, amount_cents, merchant_hint) → your backend runs checkout intents and returns safe fields (status, intent_id, payment_credential_handle, or “pending approval”).
• get_balance() → GET /v1/balance
• get_checkout_status(intent_id) → GET /v1/checkout/intents/:id

Do not expose arbitrary HTTP to Dino or pass through merchant-controlled headers from the model without review.

#In-repo SDK (for Dino engineers)

If you develop inside this monorepo, prefer @dino/agent-spend-sdk over hand-rolled fetch when possible.

#Related docs

• Connecting AI Agents to Dino — recommended architecture
• API Reference — overview + links
• Agent Bank API
• Purchase Intents API
• Agent Spend Webhooks
• Cross-Team Transfers