# Onboard your agent to Meta Knox

These are Knox's instructions for integrating a customer repository in sandbox mode.
Read the complete instructions before making changes. Follow the customer's project rules and tool permissions.
Run supported steps yourself; ask the customer only for missing business facts, account access or credentials.

## Set up your coding agent

Download and read https://docs.knoxapi.com/agent-setup/skills/knox-meta/SKILL.md.
If you are Codex, save it to `.agents/skills/knox-meta/SKILL.md` in the customer's repository.
If you are Claude Code, save it to `.claude/skills/knox-meta/SKILL.md` in the customer's repository.
For Cursor and other coding agents, follow the skill directly during this session; persistent installation is optional.
Preserve existing files: inspect before writing; do not replace a customized skill without approval.
Keep installation scoped to this repository. Do not change global agent configuration or unrelated instruction files.
Report where you installed the skill and any reload needed. If the skill is not discovered yet, follow its contents now.
There is no published Knox agent CLI or hosted MCP server in this release; they are not available. Use HTTPS directly.
Optionally, for Payments, run Knox's local stdio MCP server: download https://docs.knoxapi.com/agent-setup/tools/knox-mcp.py
(Python 3.10+, standard library only) and register it with your agent as a local command, for example
`claude mcp add knox -- python3 <path>/knox-mcp.py` or `codex mcp add knox -- python3 <path>/knox-mcp.py`. Its tools
request test keys (written to a git-ignored env file, never shown), return the prescribed template for the app's stack,
run the required-field preflight, register the webhook, make a test payment and read the integration status.
Do not invent install commands, package names, OAuth endpoints or MCP URLs.

Sources for supported project skill locations:
- https://developers.openai.com/codex/skills
- https://code.claude.com/docs/en/skills


# Integrate Meta Knox routing

Test mode only. Meta Knox is an independent routing product; adopting the Knox Payments checkout API is optional.
Keep the customer's existing processors, payment path and production traffic intact.

## Inspect and establish access

1. Inspect repository instructions, current processor integration, routing configuration, framework and test commands.
   Work on a new branch, preserve unrelated changes and ask for unknown processor mappings or routing intent.
2. Read https://docs.knoxapi.com and the Meta section of https://docs.knoxapi.com/llms.txt.
   The Stripe OpenAPI document describes Payments; it does not describe Meta control operations.
3. Customer login: https://meta.knoxapi.com/dashboard/login. Keys: https://meta.knoxapi.com/dashboard/api-keys.
   Use an existing authorized workspace; new accounts require an operator-issued invite.
   Read `KNOX_SECRET_KEY` privately from the environment or secret store. It must be a test key: `sk_test_`, or an `rk_test_`
   restricted key with the `gateways`, `routing_rules` or `traffic` permission each call needs. The key from a payments
   agent key request has none of these, so Meta configuration needs a key the customer creates.
   Do not paste keys, processor credentials, payment data or raw API responses containing secrets into chat, source, fixtures or logs.
   Secret keys identify the workspace and mode and are not limited to this product.
   There is no publishable-key routing API. Keep configuration calls on the customer's server.

## Use the control API

The base is https://meta.knoxapi.com/v1, authenticated with `Authorization: Bearer $KNOX_SECRET_KEY`.
Use GET query parameters and form-encoded POST bodies with Stripe bracket notation.
Control operations belong to this host, not https://api.knoxapi.com.

- `GET /gateway_providers` and `GET /gateway_providers/{id}` describe credential fields and provider availability. Fields with `required: false` are optional; omit them when unconfigured. An absent `required` flag means required for older catalogs. NMI/Paysafe webhook signing secrets are needed only when receiving processor webhooks; payment API authentication remains required.
- `GET /gateways` lists existing connected processor accounts. GET lists are paginated; follow `has_more` with `starting_after`.
- `GET /routing_rules` lists routing configurations. `GET /routing_rules/{id}` reads one.
- `GET /bins/{bin}` (6 to 8 digits) answers what routing knows about a card BIN: brand, funding, issuing country,
  segment, regulated and issuer. It needs the `routing_rules` permission and is a 404 when no BIN database is configured.
- `GET /traffic/ramp` and `GET /traffic/metrics` inspect staged traffic state and measurements.
- `GET /dashboard/routing_activity` uses the authenticated dashboard session, not API-key authentication; do not call it with a secret key.
  View existing recorded destinations at https://meta.knoxapi.com/dashboard/activity.

Do not create a gateway automatically. Adding the first real gateway disables the workspace sandbox connector.
Provider catalog entries do not all imply an executable connector is installed. If the desired provider is unavailable, report it.
Obtain explicit authorization and the provider's required sandbox credentials privately before `POST /gateways`.
Never infer credentials, select a processor or create dummy gateway IDs just to make a configuration request pass.

After inspecting existing gateways, implement the customer's intended sandbox routing configuration.
`POST https://meta.knoxapi.com/v1/routing_rules` creates a rule. `POST /routing_rules/{id}` updates one;
`DELETE /routing_rules/{id}` removes it. Creating with `active=false` saves a draft without changing the active rule.
Automatic configuration work must use a newly created inactive draft. Inspect the current rule's `active` flag before any update or deletion.
Editing an active rule changes routing even if the POST omits `active`; deleting one also changes routing.
Require separate customer approval for either operation. Do not overwrite existing customer drafts without authorization.

```text
name=Agent integration sandbox
type=priority
active=false
gateways[0]=<existing authorized gateway id>
```

Rule shapes:
- `priority`: `gateways[0]`, `gateways[1]`, ... are ordered destinations.
- `semantic`: explicitly enabled test workspaces only. `instructions` is a nonblank question/policy up to 300 characters; `gateways` lists at most eight allowed destinations, in fallback order. Jev receives amount, currency and known card classifications, never card numbers or customer data. A five-second deadline, unavailable engine or invalid answer uses the first enabled listed gateway. No enabled listed gateway refuses routing. The first decision is committed before processor authorization and retained on retries, even if the rule changes. A single enabled destination uses it without calling Jev. Jev cannot inspect processor pricing or health; include only supported facts in instructions.
- `volume_split`: `split[0][gateway]`, `split[0][percent]`, ...; percentages are whole numbers totaling 100.
- `conditional`: ordered `conditions` with currency or amount comparisons (`gt`, `gte`, `lt`, `lte`, `eq`),
  each condition's `gateways`, and top-level fallback `gateways`. Amounts are in minor units.
  A condition can also match the card: `card_brand` (visa, mastercard, amex, discover, diners, jcb, unionpay,
  cartes_bancaires, eftpos_au), `card_funding` (credit, debit, prepaid), `card_country` (issuing country, two
  letters), `card_bin` (1 to 8 leading digits), `card_segment` (consumer, commercial) and `card_regulated` (true,
  false: US regulated debit). Each takes a value, or `[ne]` and a value, for example `conditions[0][card_country][ne]=US`.
  A card whose value is not known matches no condition on it.

Obtain the customer's approval before activating a rule: `POST /routing_rules/{id}` with `active=true` changes the active configuration
and deactivates the previous one in this workspace/mode. Traffic-ramp actions (`advance`, `pause`, `resume`, `rollback`, `evaluate`)
also change state; do not invoke them as inspection or automatically start migration.
Activation and traffic changes need separate customer authorization beyond setting up the integration.

## Verify and report

Run the customer's tests and prove that its server can authenticate to the Meta API, list actual gateways and read routing rules.
If authorized to save a draft, read it back and compare its type, destinations, percentages/conditions and inactive flag.
Record nonsecret resource IDs and configuration evidence. Do not call the Payments integration-status check to verify Meta.
Configuration readback proves control-plane setup, not that external processor transactions were routed.
The current activity view reports payments recorded by Knox; external-only routing activity needs a separate ingestion integration.
If end-to-end routed traffic is unavailable, say so and identify what remains to be verified.

Review the diff for secrets and unrelated changes. Produce a nonsecret integration report with mappings, tests,
configuration evidence, any saved draft ID, limitations and rollback (revert customer code; delete only your authorized inactive draft).
Provide a reviewable branch/PR where the customer authorizes publication. Do not deploy or change live traffic.
